Deploy WuKongIM single node instance in Kubernetes cluster, suitable for development, testing, and small-scale production environments.
Deployment Features
Advantages:
- High availability and strong disaster recovery capability
- Supports online scaling
- Real-time automatic backup between multiple replicas
- Load balancing without manual configuration
- Fast scaling
Applicable scenarios:
- Applications with high data security requirements
- Large applications
- Environments requiring rapid deployment
Note: WuKongIM currently supports hot scaling but does not support hot shrinking!
Prerequisites
- Kubernetes cluster 1.19+
- kubectl configured and able to access cluster
- Helm 3.0+
- At least 2GB available memory and 2 CPU cores
Deployment Steps
1. Add Helm Repository
helm repo add wukongim https://wukongim.github.io/helm/
2. Update Helm Repository
3. Search Available Charts
helm search repo wukongim
4. Deploy WuKongIM
# Single node deployment (replica count is 1)
helm install wkim wukongim/wukongim \
-n wukongim \
--create-namespace \
--version 0.1.0 \
--set replicaCount=1
replicaCount=1: Number of replicas (default is 2)externalIP=<IP_ADDRESS>: External IP address
5. Check Installation Status
helm status wkim -n wukongim
6. Verify Deployment
# Check Pod status
kubectl get pods -n wukongim
# Check service status
kubectl get svc -n wukongim
# View logs
kubectl logs -l app.kubernetes.io/name=wukongim -n wukongim
Access Services
Port Forward Access
# API service
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim
# WebSocket service
kubectl port-forward svc/wkim-wukongim 5200:5200 -n wukongim
# Demo interface
kubectl port-forward svc/wkim-wukongim 5172:5172 -n wukongim
# Management interface
kubectl port-forward svc/wkim-wukongim 5300:5300 -n wukongim
Access URLs
Configuration Options
Common Helm Parameters
# Complete configuration example
helm install wkim wukongim/wukongim \
-n wukongim \
--create-namespace \
--version 0.1.0 \
--set replicaCount=1 \
--set image.tag=v2.0.0 \
--set service.type=LoadBalancer \
--set persistence.enabled=true \
--set persistence.size=20Gi \
--set resources.requests.memory=2Gi \
--set resources.requests.cpu=1000m
Main Configuration Parameters
| Parameter | Description | Default Value |
|---|
replicaCount | Number of replicas | 2 |
image.tag | Image version | latest |
service.type | Service type | ClusterIP |
persistence.enabled | Enable persistent storage | true |
persistence.size | Storage size | 10Gi |
externalIP | External IP address | "" |
Scaling Operations
Scale to Multi-Node
# Scale to 3 replicas
helm upgrade wkim wukongim/wukongim \
-n wukongim \
--version 0.1.0 \
--set replicaCount=3
Verify Scaling
# Check Pod count
kubectl get pods -n wukongim
# Check cluster status
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/cluster/nodes
Troubleshooting
Common Issues
Pod startup failure:
# Check Pod status
kubectl get pods -n wukongim
# View detailed information
kubectl describe pod <pod-name> -n wukongim
# View logs
kubectl logs <pod-name> -n wukongim
# Check service status
kubectl get svc -n wukongim
# Check endpoints
kubectl get endpoints -n wukongim
# Test service connectivity
kubectl exec -it <pod-name> -n wukongim -- wget -qO- http://localhost:5001/health
# Check PVC status
kubectl get pvc -n wukongim
# View storage details
kubectl describe pvc <pvc-name> -n wukongim
Log Viewing
# View real-time logs
kubectl logs -f deployment/wkim-wukongim -n wukongim
# View all replica logs
kubectl logs -l app.kubernetes.io/name=wukongim -n wukongim
# View historical logs
kubectl logs deployment/wkim-wukongim -n wukongim --previous
Upgrade and Maintenance
Version Upgrade
# Update Helm repository
helm repo update
# Search for new versions
helm search repo wukongim
# Upgrade to new version
helm upgrade wkim wukongim/wukongim \
-n wukongim \
--version <new_version>
Data Backup
# Create data snapshot
kubectl exec -n wukongim deployment/wkim-wukongim -- \
tar czf /tmp/backup-$(date +%Y%m%d).tar.gz /data
# Copy backup file to local
kubectl cp wukongim/<pod-name>:/tmp/backup-$(date +%Y%m%d).tar.gz \
./wukongim-backup-$(date +%Y%m%d).tar.gz
Uninstall
# Uninstall WuKongIM
helm uninstall wkim -n wukongim
# Delete namespace (optional)
kubectl delete namespace wukongim
Advanced Configuration
Custom Values File
Create a values.yaml file for custom configuration:
# values.yaml
replicaCount: 1
image:
repository: registry.cn-shanghai.aliyuncs.com/wukongim/wukongim
tag: "v2"
pullPolicy: IfNotPresent
service:
type: LoadBalancer
ports:
api: 5001
tcp: 5100
websocket: 5200
management: 5300
demo: 5172
persistence:
enabled: true
size: 20Gi
storageClass: ""
resources:
requests:
memory: "2Gi"
cpu: "1000m"
limits:
memory: "4Gi"
cpu: "2000m"
nodeSelector: {}
tolerations: []
affinity: {}
helm install wkim wukongim/wukongim \
-n wukongim \
--create-namespace \
-f values.yaml
Environment Variables
Configure WuKongIM through environment variables:
# In values.yaml
env:
- name: WK_MODE
value: "release"
- name: WK_TOKENAUTHON
value: "true"
- name: WK_EXTERNAL_IP
value: "your-external-ip"
Monitoring and Observability
Enable Monitoring
# Deploy with monitoring enabled
helm install wkim wukongim/wukongim \
-n wukongim \
--create-namespace \
--set monitoring.enabled=true \
--set monitoring.prometheus.enabled=true
Health Checks
# Check health endpoint
kubectl exec -n wukongim deployment/wkim-wukongim -- \
curl -f http://localhost:5001/health
# Check cluster status
kubectl exec -n wukongim deployment/wkim-wukongim -- \
curl -f http://localhost:5001/cluster/nodes
Next Steps
