Home / Kong Mesh
Edit
Report

Federate a zone control plane to Konnect

Uses: Kong Mesh
Incompatible with
on-prem
Related Documentation
Mesh Documentation
Tags
#service-mesh
Related Resources
Kong Mesh in Konnect
Migrate a self-managed zone control plane to Konnect
TL;DR

Export federation-ready resources from your existing zone control plane, apply them to a Konnect-managed global control plane, then reconnect the zone to Konnect to move from a single-zone to a multi-zone mesh.

Prerequisites

Kong Konnect

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

  1. The following Konnect items are required to complete this tutorial:
    • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

Konnect global control plane

Before you can add services or apply configurations, you must create a global control plane.

  1. Create the control plane by sending a request to the Mesh control planes API:

    curl -X POST "https://us.api.konghq.com/v1/mesh/control-planes" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "example-cp"
     }'

  2. Export the control plane id so you can reference it when you create a zone:

    export CONTROL_PLANE_ID='YOUR_CONTROL_PLANE_ID'

  3. Export your region:

    export KONNECT_REGION='us'

The global control plane is now created but has no functionality until you connect a zone.

Install kumactl

  1. Go to the Kong Mesh packages page to download and extract the installation archive for your OS, or download and extract the latest release automatically (Linux or macOS):

    curl -L https://developer.konghq.com/mesh/installer.sh | VERSION=2.14.2 sh -

  2. Add the Kong Mesh binaries directory to your path. By default, the directory is /kong-mesh-2.14.2/bin. You can use the following command to set the directory in your path for the current terminal window:

    export PATH=$PATH:$(pwd)/kong-mesh-2.14.2/bin

Zone control plane

Deploy a standalone Kong Mesh control plane on Kubernetes. This is the single-zone control plane that you’ll federate to Konnect; it isn’t connected to any global control plane yet.

  1. Add the Kong Mesh Helm repository:

    helm repo add kong-mesh https://kong.github.io/kong-mesh-charts
helm repo update

  2. Install the control plane:

    helm install --create-namespace --namespace kong-mesh-system kong-mesh kong-mesh/kong-mesh

  3. Wait for the control plane to be ready:

    kubectl wait -n kong-mesh-system --for=condition=ready pod --selector=app=kong-mesh-control-plane --timeout=90s

If you already have a zone control plane that isn’t connected to any global control plane, you can federate it to Konnect.

Federating a zone control plane moves Kong Mesh from a single-zone setup to a multi-zone setup, which enables automatic service failover if a specific zone becomes unavailable. This guide federates a zone control plane to Konnect by transferring an existing Kong Mesh zone and reconnecting it. To learn more, see Kong Mesh in Konnect.

Configure kumactl to access your zone control plane

This example uses a zone control plane deployed on Kubernetes. If you have a Universal zone control plane, see the API server authentication guide to configure kumactl.

  1. Forward port 5681:

    kubectl port-forward svc/kong-mesh-control-plane -n kong-mesh-system 5681:5681 > /dev/null 2>&1 &

  2. Configure kumactl to access the zone control plane. Requests over the port-forward reach the control plane from localhost, which Kong Mesh authenticates as an administrator by default, so no token is required:

    kumactl config control-planes add \
  --address http://localhost:5681 \
  --name "zone-cp" \
  --overwrite

Transfer resources from the zone control plane to Konnect

  1. Create and navigate to the working directory:

    mkdir -p ~/mesh-konnect && cd ~/mesh-konnect

  2. Export federation-ready resources from the zone control plane:

    kumactl export --profile=federation --format=universal > resources.yaml

  3. Export your Konnect region:

    export KONNECT_REGION='us'

  4. Configure kumactl to target the Konnect-managed global control plane. This points kumactl at your control plane’s Mesh API and authenticates with your Konnect token:

    kumactl config control-planes add \
  --name konnect \
  --address https://$KONNECT_REGION.api.konghq.com/v1/mesh/control-planes/$CONTROL_PLANE_ID/api \
  --headers "authorization=Bearer $KONNECT_TOKEN" \
  --overwrite

  5. Apply the exported resources to the Konnect global control plane:

    kumactl apply -f resources.yaml

Connect the zone control plane to Konnect

Generate a zone token from the Konnect-managed global control plane, then reconfigure your existing zone control plane to connect to Konnect.

A zone isn’t a standalone Konnect resource. To provision one through the API, create a system account access token with the Connector role scoped to your control plane, then connect a zone control plane with that token. This is the same model that the Terraform guide automates.

  1. Create a system account:

    curl -X POST https://global.api.konghq.com/v3/system-accounts \
  -H "Authorization: Bearer $KONNECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "zone-1",
    "description": "Authentication for zone-1",
    "konnect_managed": false
  }'

    Export the returned account id:

    export ACCOUNT_ID='YOUR_SYSTEM_ACCOUNT_ID'

  2. Assign the Connector role for your control plane to the system account:

    curl -X POST https://global.api.konghq.com/v3/system-accounts/$ACCOUNT_ID/assigned-roles \
  -H "Authorization: Bearer $KONNECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "Connector",
    "entity_type_name": "Mesh Control Planes",
    "entity_id": "'"$CONTROL_PLANE_ID"'",
    "entity_region": "'"$KONNECT_REGION"'"
  }'

  3. Generate an access token for the system account:

    curl -X POST https://global.api.konghq.com/v3/system-accounts/$ACCOUNT_ID/access-tokens \
  -H "Authorization: Bearer $KONNECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "zone-1",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

    The response includes the token value, which is shown only once. Copy it now.

  4. Export the token:

    export CONTROL_PLANE_TOKEN='YOUR_ZONE_TOKEN'

  5. Store the zone token in a Kubernetes secret:

    echo "
apiVersion: v1
kind: Secret
metadata:
  name: cp-token
  namespace: kong-mesh-system
type: Opaque
stringData:
  token: $CONTROL_PLANE_TOKEN
" | kubectl apply -f -

  6. Create a Helm values file that connects the zone to Konnect. Use the same zone name as your existing zone:

    cat <<EOF > values.yaml
kuma:
  controlPlane:
    mode: zone
    zone: zone-1
    kdsGlobalAddress: grpcs://$KONNECT_REGION.mesh.sync.konghq.com:443
    konnect:
      cpId: $CONTROL_PLANE_ID
    secrets:
      - Env: KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_INLINE
        Secret: cp-token
        Key: token
  ingress:
    enabled: true
  egress:
    enabled: true
EOF

  7. Apply the new configuration to the existing zone control plane:

    helm upgrade --namespace kong-mesh-system kong-mesh kong-mesh/kong-mesh -f values.yaml

    Konnect automatically detects and displays the zone once it reconnects.

Validate
  1. In the Konnect sidebar, click Service Mesh.
  2. Click example-cp and confirm that:
    • The new zone appears as Online.
    • Existing policies from the zone control plane are visible.
    • Data plane proxies from the federated zone appear as expected.

It may take a few minutes for the zone to appear in Konnect.

Cleanup

Stop the port-forward

Stop the kubectl port-forward process used to reach the zone control plane:

pkill -f "kubectl port-forward.*5681"

Uninstall the zone control plane

Uninstall Kong Mesh and remove its namespace:

helm uninstall kong-mesh --namespace kong-mesh-system
kubectl delete namespace kong-mesh-system

Delete the Konnect control plane

Delete the global control plane, which also removes its zones and mesh:

curl -X DELETE https://$KONNECT_REGION.api.konghq.com/v1/mesh/control-planes/$CONTROL_PLANE_ID \
  -H "Authorization: Bearer $KONNECT_TOKEN"

Delete the system account created for the zone token:

curl -X DELETE https://global.api.konghq.com/v3/system-accounts/$ACCOUNT_ID \
  -H "Authorization: Bearer $KONNECT_TOKEN"

Remove the kumactl control plane configurations

Remove the control plane configurations added to kumactl during this guide:

kumactl config control-planes remove --name zone-cp
kumactl config control-planes remove --name konnect

Remove the working directory

Return to the parent directory, then delete the working directory and the files created during this guide:

cd ../
rm -rf ~/mesh-konnect

FAQs

How does a zone authenticate to the global control plane?

Each zone control plane authenticates to the Konnect-managed global control plane with an access token. When you create a zone with the UI wizard, Konnect provisions this token for you as a system account access token and includes it in the generated deployment instructions, so you don’t need to create one manually.

Konnect supports two types of access tokens:

  • Personal access token (PAT): Prefixed with kpat_ and tied to an individual user account. Use a PAT for interactive or one-off tasks.
  • System account access token (SAT): Prefixed with spat_ and tied to a system account rather than a person. We recommend system account tokens for zone authentication and automation because they aren’t tied to a user who might leave the organization.

If you provision zones with automation instead of the UI wizard, such as with Terraform, create a system account, assign it the Connector role on the control plane, and generate a system account access token to authenticate the zone. For a full example, see Deploy Kong Mesh using Terraform and Konnect.

Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support