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

# Version Upgrade

> WuKongIM Kubernetes deployment version upgrade guide

WuKongIM supports version upgrades in Kubernetes environments with rolling updates to ensure zero-downtime deployments.

## Upgrade Overview

Kubernetes deployments provide built-in rolling update capabilities, making WuKongIM upgrades safe and seamless. The upgrade process maintains service availability by updating pods gradually.

<Note>
  **Version Compatibility**:

  * **Patch updates** (e.g., 2.0.1 → 2.0.2): Always safe, includes bug fixes and minor improvements
  * **Minor updates** (e.g., 2.0.x → 2.1.x): Generally safe, includes new features with backward compatibility
  * **Major updates** (e.g., 2.x.x → 3.x.x): May include breaking changes, requires careful planning
</Note>

## Upgrade Steps

### 1. Check Current Version

First, check your current WuKongIM version:

```bash theme={null}
# Check current Helm release
helm list -n wukongim

# Check running version via API
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/version
```

### 2. Update Helm Repository

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

### 3. Search for New Version Charts

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

### 4. Backup Current Configuration

```bash theme={null}
# Export current values
helm get values wkim -n wukongim > current-values.yaml

# Create data backup
kubectl exec -n wukongim deployment/wkim-wukongim -- \
  tar czf /tmp/backup-$(date +%Y%m%d).tar.gz /data

# Copy backup to local
kubectl cp wukongim/<pod-name>:/tmp/backup-$(date +%Y%m%d).tar.gz \
  ./wukongim-backup-$(date +%Y%m%d).tar.gz
```

### 5. Perform Upgrade

```bash theme={null}
# Upgrade to specific version
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version <new_version_number>

# Or upgrade with custom values
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version <new_version_number> \
  -f current-values.yaml
```

### 6. Monitor Upgrade Progress

```bash theme={null}
# Watch the rolling update
kubectl rollout status deployment/wkim-wukongim -n wukongim

# Monitor pods during upgrade
kubectl get pods -n wukongim -w

# Check events
kubectl get events -n wukongim --sort-by='.lastTimestamp'
```

### 7. Verify Upgrade

```bash theme={null}
# Check all pods are running
kubectl get pods -n wukongim

# Verify new version
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/version

# Check cluster health
curl http://localhost:5001/health
curl http://localhost:5001/cluster/nodes
```

## Advanced Upgrade Strategies

### Blue-Green Deployment

For critical production environments:

```bash theme={null}
# Deploy new version to different namespace
helm install wkim-green wukongim/wukongim \
  -n wukongim-green \
  --create-namespace \
  --version <new_version>

# Test new deployment
kubectl port-forward svc/wkim-green-wukongim 5001:5001 -n wukongim-green &
curl http://localhost:5001/health

# Switch traffic (update ingress/load balancer)
# Remove old deployment after verification
helm uninstall wkim -n wukongim
```

### Canary Deployment

For gradual rollout:

```bash theme={null}
# Scale down current deployment
kubectl scale deployment wkim-wukongim --replicas=2 -n wukongim

# Deploy canary version
helm install wkim-canary wukongim/wukongim \
  -n wukongim-canary \
  --create-namespace \
  --version <new_version> \
  --set replicaCount=1

# Monitor canary performance
# Gradually increase canary replicas and decrease old replicas
```

## Rollback Procedures

### Quick Rollback

```bash theme={null}
# Rollback to previous version
helm rollback wkim -n wukongim

# Or rollback to specific revision
helm rollback wkim <revision_number> -n wukongim

# Check rollback status
kubectl rollout status deployment/wkim-wukongim -n wukongim
```

### Manual Rollback

```bash theme={null}
# List revision history
helm history wkim -n wukongim

# Rollback to specific version
helm rollback wkim <revision> -n wukongim

# Verify rollback
kubectl get pods -n wukongim
curl http://localhost:5001/version
```

### Data Rollback (if needed)

```bash theme={null}
# Stop current deployment
kubectl scale deployment wkim-wukongim --replicas=0 -n wukongim

# Restore data from backup
kubectl exec -n wukongim deployment/wkim-wukongim -- \
  tar -xzf /tmp/backup-YYYYMMDD.tar.gz -C /

# Restart deployment
kubectl scale deployment wkim-wukongim --replicas=3 -n wukongim
```

## Upgrade Configuration

### Custom Values for Upgrade

```yaml theme={null}
# upgrade-values.yaml
replicaCount: 3

image:
  tag: "v2.1.0"
  pullPolicy: IfNotPresent

resources:
  requests:
    memory: "4Gi"
    cpu: "2000m"
  limits:
    memory: "8Gi"
    cpu: "4000m"

persistence:
  enabled: true
  size: 50Gi

# Rolling update strategy
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 1
    maxSurge: 1

# Health checks
livenessProbe:
  httpGet:
    path: /health
    port: 5001
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5001
  initialDelaySeconds: 5
  periodSeconds: 5
```

Use custom values during upgrade:

```bash theme={null}
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version <new_version> \
  -f upgrade-values.yaml
```

## Monitoring During Upgrade

### Health Checks

```bash theme={null}
# Monitor pod health
kubectl get pods -n wukongim -o wide

# Check service endpoints
kubectl get endpoints -n wukongim

# Test API availability
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
while true; do
  curl -f http://localhost:5001/health && echo " - OK" || echo " - FAIL"
  sleep 5
done
```

### Performance Monitoring

```bash theme={null}
# Monitor resource usage
kubectl top pods -n wukongim

# Check cluster metrics
kubectl port-forward svc/wkim-wukongim 5300:5300 -n wukongim &
curl http://localhost:5300/metrics

# View upgrade logs
kubectl logs -f deployment/wkim-wukongim -n wukongim
```

## Troubleshooting Upgrades

### Common Issues

**Upgrade stuck or failing**:

```bash theme={null}
# Check deployment status
kubectl describe deployment wkim-wukongim -n wukongim

# Check pod events
kubectl describe pods -n wukongim

# View detailed logs
kubectl logs deployment/wkim-wukongim -n wukongim
```

**Resource constraints**:

```bash theme={null}
# Check node resources
kubectl describe nodes

# Check resource requests
kubectl describe deployment wkim-wukongim -n wukongim

# Adjust resources if needed
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --set resources.requests.memory=2Gi \
  --set resources.requests.cpu=1000m
```

**Image pull issues**:

```bash theme={null}
# Check image pull status
kubectl describe pods -n wukongim | grep -A 5 "Events:"

# Verify image exists
kubectl run test-image --image=registry.cn-shanghai.aliyuncs.com/wukongim/wukongim:v2.1.0 --rm -it --restart=Never
```

## Automation Scripts

### Automated Upgrade Script

```bash theme={null}
#!/bin/bash
# upgrade-wukongim.sh

set -e

NAMESPACE="wukongim"
RELEASE_NAME="wkim"
NEW_VERSION="$1"

if [ -z "$NEW_VERSION" ]; then
    echo "Usage: $0 <new_version>"
    exit 1
fi

echo "Starting WuKongIM upgrade to version $NEW_VERSION..."

# Backup current configuration
echo "Backing up current configuration..."
helm get values $RELEASE_NAME -n $NAMESPACE > backup-values-$(date +%Y%m%d).yaml

# Update Helm repository
echo "Updating Helm repository..."
helm repo update

# Perform upgrade
echo "Performing upgrade..."
helm upgrade $RELEASE_NAME wukongim/wukongim \
    -n $NAMESPACE \
    --version $NEW_VERSION \
    --wait \
    --timeout=10m

# Verify upgrade
echo "Verifying upgrade..."
kubectl rollout status deployment/wkim-wukongim -n $NAMESPACE

# Check health
echo "Checking health..."
kubectl port-forward svc/wkim-wukongim 5001:5001 -n $NAMESPACE &
PF_PID=$!
sleep 5

if curl -f http://localhost:5001/health > /dev/null 2>&1; then
    echo "Upgrade successful! WuKongIM is healthy."
else
    echo "Health check failed! Consider rollback."
    kill $PF_PID
    exit 1
fi

kill $PF_PID
echo "Upgrade completed successfully!"
```

Make script executable and use:

```bash theme={null}
chmod +x upgrade-wukongim.sh
./upgrade-wukongim.sh v2.1.0
```

## Best Practices

### Pre-Upgrade Checklist

* [ ] Review release notes for breaking changes
* [ ] Backup current configuration and data
* [ ] Test upgrade in staging environment
* [ ] Plan maintenance window
* [ ] Notify users of potential brief interruption
* [ ] Prepare rollback plan

### During Upgrade

* [ ] Monitor pod status and logs
* [ ] Watch resource usage
* [ ] Test API endpoints
* [ ] Verify cluster communication
* [ ] Check performance metrics

### Post-Upgrade

* [ ] Verify version upgrade successful
* [ ] Test all major features
* [ ] Monitor performance for 24 hours
* [ ] Update documentation
* [ ] Clean up old backups after verification period

## Next Steps

<CardGroup cols={2}>
  <Card title="Scaling Guide" icon="expand" href="/en/installation/k8s/scaling">
    Scale your upgraded cluster
  </Card>

  <Card title="Multi-Node Deployment" icon="network" href="/en/installation/k8s/multi-node">
    Learn about cluster deployment
  </Card>

  <Card title="Monitoring Setup" icon="chart-line" href="/en/installation/linux/monitoring">
    Set up monitoring for upgraded system
  </Card>

  <Card title="Server Configuration" icon="gear" href="/en/server/configuration">
    Configure advanced settings
  </Card>
</CardGroup>