Skip to main content

Documentation Index

Fetch the complete documentation index at: https://wukong.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

Scaling Guide

Scale your upgraded cluster

Multi-Node Deployment

Learn about cluster deployment

Monitoring Setup

Set up monitoring for upgraded system

Server Configuration

Configure advanced settings