Skip to main content
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.
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

Upgrade Steps

1. Check Current Version

First, check your current WuKongIM version:
# 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

helm repo update

3. Search for New Version Charts

helm search repo wukongim

4. Backup Current Configuration

# 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

# 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

# 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

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

# 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

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

# 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

# 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:
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version <new_version> \
  -f upgrade-values.yaml

Monitoring During Upgrade

Health Checks

# 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

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

#!/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:
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