Kubernetes (Beta)

Deploy a verified artifact as a WuKongIM cluster with stable identities, independent storage, and correct probes.

This path is for teams that already operate a Kubernetes platform. Design the WuKongIM topology first, then let the platform orchestrate a verified image and configuration. Kubernetes does not create membership, data replicas, or upgrade compatibility by itself.

Beta, not an official installer

The repository does not ship a production-ready Helm chart or complete Kubernetes manifest. This page gives the shortest implementation order; the platform team must review and own the final resources, secrets, network, capacity, and recovery evidence.

Confirm the fit first

Complete the member, address, replica, and failure-domain design in Multi-node Cluster;
provide a stable StorageClass and rehearse snapshot and recovery for independent PVCs;
own image digests, secrets, NetworkPolicy, ingress, and monitoring;
separate the network boundaries for API, TCP, WebSocket/WSS, Manager, metrics, and node transport.

The reference resources use three nodes and three replicas. This has no node headroom: after any node is lost, the others return 503 from /readyz because replica candidates are insufficient. If the failure objective requires three eligible replica candidates after one loss, provide at least four qualified data nodes.

1. Build and pin the image

git rev-parse HEAD
docker buildx build --load --pull \
  -t registry.example.com/wukongim:${GIT_COMMIT} .
docker push registry.example.com/wukongim:${GIT_COMMIT}
docker inspect --format='{{index .RepoDigests 0}}' \
  registry.example.com/wukongim:${GIT_COMMIT}

The release pipeline must set ${GIT_COMMIT} explicitly. The final Pod image must be pinned as registry.example.com/wukongim@sha256:REPLACE_WITH_REVIEWED_DIGEST, never by a floating tag.

2. Adapt the resources

Copy and review the ConfigMap, Headless Service, client Service, StatefulSet, PVC, and PodDisruptionBudget fragments in Kubernetes Resource Reference. Replace at least the following:

Item	Required decision
Image	Every Pod uses the same reviewed digest
Identity	StatefulSet ordinal maps stably to a unique `WK_NODE_ID`
Inventory	`WK_CLUSTER_NODES` is a complete JSON list with mutually reachable Headless Service addresses
Configuration	`hash_slot_count = 256`; replicas fit node count and failure objectives
Storage	Every Pod has an independent PVC with explicit capacity, topology, and retention
Probes	Startup/liveness use `/healthz`; readiness uses `/readyz`
Network	Client addresses are reachable; Manager, metrics, and transport stay private
Secrets	Join token, Manager JWT, and users stay out of ConfigMap and Git

Keep enableServiceLinks: false in the StatefulSet so Kubernetes does not inject unknown WK_* environment variables. See the Kubernetes documentation for StatefulSet identity and PVC semantics and probe behavior.

3. Apply the platform-owned manifests

Store the reviewed resources in your team's release repository and apply them in dependency order. These filenames are examples, not repository-shipped manifests:

kubectl apply -f namespace.yaml
kubectl apply -f secrets.yaml
kubectl apply -f config.yaml
kubectl apply -f services.yaml
kubectl apply -f statefulset.yaml
kubectl apply -f pdb.yaml

kubectl -n wukongim rollout status statefulset/wukongim --timeout=10m

4. Verify

kubectl -n wukongim get pods -o wide
kubectl -n wukongim get pvc
kubectl -n wukongim get endpointslice \
  -l kubernetes.io/service-name=wukongim-peer
kubectl -n wukongim logs wukongim-0 --tail=200

kubectl -n wukongim port-forward pod/wukongim-0 15001:5001
curl --fail http://127.0.0.1:15001/healthz
curl --fail http://127.0.0.1:15001/readyz

Then confirm on every node that:

Pod identity, WK_NODE_ID, PVC, and transport DNS map one to one;
/readyz returns 200, with no duplicate node IDs in Manager or metrics;
a client uses the advertised addresses to route, connect, send, receive, and reconnect-sync;
a recreated Pod reattaches its original PVC and restores routing and persistent messages as expected.

Lifecycle boundaries

Scale: never change only replicas; a new Pod needs a valid node ID, member address, independent PVC, and controlled migration.
Upgrade: update one node at a time only when the target release explicitly supports mixed operation; otherwise use a maintenance window. Follow Upgrade & Migration.
Launch: complete the Production Checklist before accepting production traffic.

Kubernetes deployment is complete only when the image digest is pinned, state is persistent, every node is ready, client addresses are reachable, and end-to-end and recovery evidence is retained.

Kubernetes Deployment (Beta)