Federate zone Control Plane

With Kong Mesh you can first start with just one zone control plane and then federate it to a multi-zone deployment. This way you can:

• see your mesh deployment in one centralized place
• connect multiple zones and introduce cross zone connectivity
• manage policies that are pushed to all zones

• Completed quickstart to set up a zone control plane with demo application
• Have kumactl installed and in your path

If you are already familiar with quickstart you can set up required environment by running: sh helm upgrade \ --install \ --create-namespace \ --namespace kong-mesh-system \ kong-mesh kong-mesh/kong-mesh kubectl wait -n kong-mesh-system --for=condition=ready pod --selector=app=kong-mesh-control-plane --timeout=90s kubectl apply -f https://raw.githubusercontent.com/kumahq/kuma-counter-demo/refs/heads/main/k8s/001-with-mtls.yaml

Start a new Kubernetes cluster

Currently, it’s not possible to deploy global and zone control plane in the same Kubernetes cluster, therefore we need a new Kubernetes cluster.

You can skip this step if you already have a Kubernetes cluster running. It can be a cluster running locally or in a public cloud like AWS EKS, GCP GKE, etc.

minikube start -p mesh-global

Setup the minikube tunnel

If you are using minikube for local testing, you can take advantage of the built-in minikube tunnel command. This command allows load balancer addresses to be provisioned using localhost.

Using nohup will allow the tunnel to continue running should your current terminal session end.

nohup minikube tunnel -p mesh-global &

Deploy a global control plane

helm install --kube-context mesh-global --create-namespace --namespace kong-mesh-system \
--set kuma.controlPlane.mode=global \
--set kuma.controlPlane.defaults.skipMeshCreation=true \
kong-mesh kong-mesh/kong-mesh

We skip default mesh creation as we will bring mesh from zone control plane in the next steps.

Sync endpoint

Find and save the external IP and port of the kong-mesh-global-zone-sync service in the kong-mesh-system namespace:

export KDS_IP=$(kubectl --context mesh-global get svc -n kong-mesh-system kong-mesh-global-zone-sync -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

If you are using minikube, you should use host.minikube.internal to ensure networking works correctly.

sh export KDS_IP=host.minikube.internal

To federate zone control plane without any traffic interruption, we need to copy resources like secrets, meshes etc. First, we need to expose API server of zone control plane:

kubectl --context mesh-zone port-forward svc/kong-mesh-control-plane -n kong-mesh-system 5681:5681

Then we export resources:

export ZONE_USER_ADMIN_TOKEN=$(kubectl --context mesh-zone get secrets -n kong-mesh-system admin-user-token -o json | jq -r .data.value | base64 -d)
kumactl config control-planes add \
  --address http://localhost:5681 \
  --headers "authorization=Bearer $ZONE_USER_ADMIN_TOKEN" \
  --name "zone-cp" \
  --overwrite  
  
kumactl export --profile federation-with-policies --format kubernetes > resources.yaml

And finally, we apply resources on global control plane

kubectl apply --context mesh-global -f resources.yaml

Update Helm deployment of zone control plane to configure connection to the global control plane.

helm upgrade --kube-context mesh-zone --namespace kong-mesh-system \
--set kuma.controlPlane.mode=zone \
--set kuma.controlPlane.zone=zone-1 \
--set kuma.ingress.enabled=true \
--set kuma.controlPlane.kdsGlobalAddress=grpcs://${KDS_IP}:5685 \
--set kuma.controlPlane.tls.kdsZoneClient.skipVerify=true \
kong-mesh kong-mesh/kong-mesh

To verify federation, first port-forward the API service from the global control plane to port 15681 to avoid collision with previous port forward.

kubectl --context mesh-global port-forward svc/kong-mesh-control-plane -n kong-mesh-system 15681:5681

And then navigate to 127.0.0.1:15681/gui to see the GUI.

You should eventually see

• a zone in list of zones
• policies including kv MeshTrafficPermission that we applied in the quickstart guide.
• data plane proxies for the demo application that we installed in the quickstart guide.

Apply policy on global control plane

We can check policy synchronization from global control plane to zone control plane by applying a policy on global control plane:

echo "apiVersion: kuma.io/v1alpha1
kind: MeshCircuitBreaker
metadata:
  name: demo-app-to-redis
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
  - targetRef:
      kind: MeshService
      name: kv
    default:
      connectionLimits:
        maxConnections: 2
        maxPendingRequests: 8
        maxRetries: 2
        maxRequests: 2" | kubectl --context mesh-global apply -f -

If we execute the following command:

kubectl get --context mesh-zone meshcircuitbreakers -A

The policy should be eventually available in zone control plane

NAMESPACE     NAME                                                TARGETREF KIND   TARGETREF NAME
kong-mesh-system demo-app-to-redis-65xb45x2xfd5bf7f        MeshService      demo-app_kuma-demo_svc_5000
kong-mesh-system mesh-circuit-breaker-all-default          Mesh

• Read the multi-zone docs to learn more about this deployment model and cross-zone connectivity.