Home / Kong Mesh
Edit
Report

Migrate a self-managed 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
Federate a zone control plane to Konnect
TL;DR

Export your meshes, policies, and secrets from the self-managed global control plane, apply them to a Konnect-managed global control plane, then reconnect each zone control plane to Konnect.

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'

A 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.

A self-managed zone control plane

Deploy a self-managed Kong Mesh global control plane and a zone control plane connected to it on Kubernetes. You’ll migrate this zone to Konnect.

  1. Export the names of the contexts to your environment:

    export GLOBAL_CONTEXT=global
export ZONE_CONTEXT=zone

  2. Create separate clusters for the global and zone control planes. The global and zone control planes must run in separate clusters. These steps use minikube:

    minikube start -p $GLOBAL_CONTEXT
minikube start -p $ZONE_CONTEXT

  3. Provision load balancer addresses on the global cluster so the zone can reach the control plane’s KDS address:

    nohup minikube tunnel -p $GLOBAL_CONTEXT > /dev/null 2>&1 &

  4. Add the Kong Mesh Helm repository:

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

  5. Deploy the global control plane:

    helm install --kube-context $GLOBAL_CONTEXT --create-namespace --namespace kong-mesh-system \
  --set kuma.controlPlane.mode=global \
  kong-mesh kong-mesh/kong-mesh

  6. Export the global control plane’s KDS address:

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

  7. Deploy a zone control plane connected to the global control plane:

    helm install --kube-context $ZONE_CONTEXT --create-namespace --namespace kong-mesh-system \
  --set kuma.controlPlane.mode=zone \
  --set kuma.controlPlane.zone=zone-1 \
  --set kuma.controlPlane.kdsGlobalAddress=$KDS_ADDRESS \
  --set kuma.controlPlane.tls.kdsZoneClient.skipVerify=true \
  --set kuma.ingress.enabled=true \
  kong-mesh kong-mesh/kong-mesh

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

If you already run Kong Mesh with a self-managed global control plane, you can migrate your zones to a Konnect-managed global control plane so that Konnect hosts and operates the global control plane for you. To learn more, see Kong Mesh in Konnect.

This guide migrates a self-managed zone control plane to Konnect by transferring your meshes and policies to the Konnect-managed global control plane and reconnecting the zone.

This process assumes you’re migrating zones one by one. During migration, zone-to-zone communication may break temporarily because each zone’s zone ingress must be registered with the new global control plane in Konnect. Until both zones are migrated, cross-zone service discovery won’t work.

Transfer resources from the self-managed global control plane

  1. Create and navigate to the working directory for this guide:

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

  2. Forward port 5681 from the self-managed global control plane:

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

  3. Configure kumactl to access the self-managed global 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 "global-cp" \
  --overwrite

  4. Export the meshes, policies, and secrets from the self-managed global control plane. The federation-with-policies profile includes the mesh definitions, all policies, and the signing keys and secrets (including mTLS CA secrets) that the zone needs to keep working after it moves:

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

  5. Export your Konnect region:

    export KONNECT_REGION='us'

  6. 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

  7. 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 instead of the self-managed global control plane.

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 --context $ZONE_CONTEXT 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 --kube-context $ZONE_CONTEXT --namespace kong-mesh-system kong-mesh kong-mesh/kong-mesh -f values.yaml

    Konnect automatically detects and displays the zone once it reconnects.

Validate

In Konnect, confirm the migrated zone is connected:

  1. In the Konnect sidebar, click Service Mesh.
  2. Confirm that the migrated zone appears with an Online status.
  3. Confirm that the meshes, policies, and data plane proxies you transferred are present.

Cleanup

Stop the background processes

Stop the kubectl port-forward and minikube tunnel processes started during this guide:

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

Delete the self-managed clusters

Delete the global and zone clusters created for this guide:

minikube delete -p $GLOBAL_CONTEXT
minikube delete -p $ZONE_CONTEXT

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 global-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