> ## Documentation Index
> Fetch the complete documentation index at: https://wukong.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Node Deployment

> Deploy WuKongIM multi-node cluster in Kubernetes using Helm

Deploy WuKongIM multi-node cluster in Kubernetes cluster, providing high availability, disaster recovery capability and load balancing.

## 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
* Enterprise production environments

<Warning>
  **Note**: WuKongIM currently supports hot scaling but does not support hot shrinking!
</Warning>

## Prerequisites

* Kubernetes cluster 1.19+
* kubectl configured and able to access cluster
* Helm 3.0+
* At least 3 worker nodes, each with 4GB+ memory and 2 CPU cores

## Deployment Steps

### 1. Add Helm Repository

```bash theme={null}
helm repo add wukongim https://wukongim.github.io/helm/
```

### 2. Update Helm Repository

```bash theme={null}
helm repo update
```

### 3. Search Available Charts

```bash theme={null}
helm search repo wukongim
```

### 4. Deploy WuKongIM Multi-Node Cluster

```bash theme={null}
# Multi-node deployment (replica count is 3)
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --version 0.1.0 \
  --set replicaCount=3
```

**Optional parameters**:

* `replicaCount=3`: Number of replicas (default is 2)
* `externalIP=<IP_ADDRESS>`: External IP address

### 5. Check Installation Status

```bash theme={null}
helm status wkim -n wukongim
```

### 6. Verify Deployment

```bash theme={null}
# Check Pod status
kubectl get pods -n wukongim

# Check service status
kubectl get svc -n wukongim

# Check cluster status
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/cluster/nodes
```

## Access Services

### Port Forward Access

```bash theme={null}
# 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

* **API Endpoint**: [http://localhost:5001](http://localhost:5001)
* **WebSocket**: ws\://localhost:5200
* **Demo Interface**: [http://localhost:5172](http://localhost:5172)
* **Management Interface**: [http://localhost:5300](http://localhost:5300)

## Configuration Options

### Common Helm Parameters

```bash theme={null}
# Complete configuration example
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --version 0.1.0 \
  --set replicaCount=3 \
  --set image.tag=v2.0.0 \
  --set service.type=LoadBalancer \
  --set persistence.enabled=true \
  --set persistence.size=50Gi \
  --set resources.requests.memory=4Gi \
  --set resources.requests.cpu=2000m
```

### 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 Cluster

```bash theme={null}
# Scale to 5 replicas
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version 0.1.0 \
  --set replicaCount=5
```

### Verify Scaling

```bash theme={null}
# 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

# View cluster node information
curl http://localhost:5001/cluster/nodes | jq '.'
```

## Troubleshooting

### Common Issues

**Pod startup failure**:

```bash theme={null}
# 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
```

**Cluster nodes cannot communicate**:

```bash theme={null}
# Check network connectivity
kubectl exec -it <pod-name> -n wukongim -- ping <other-pod-ip>

# Check cluster ports
kubectl exec -it <pod-name> -n wukongim -- netstat -tulpn | grep 11110

# View cluster status
kubectl logs <pod-name> -n wukongim | grep cluster
```

**Service inaccessible**:

```bash theme={null}
# 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
```

### Log Viewing

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Uninstall WuKongIM
helm uninstall wkim -n wukongim

# Delete namespace (optional)
kubectl delete namespace wukongim
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Single Node Deployment" icon="cube" href="/en/installation/k8s/single-node">
    Learn about single node deployment
  </Card>

  <Card title="Server Configuration" icon="gear" href="/en/server/configuration">
    Detailed configuration options
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/en/installation/docker/multi-node">
    Docker multi-node deployment
  </Card>

  <Card title="API Documentation" icon="code" href="/en/api/introduction">
    Start using the API
  </Card>
</CardGroup>