Migrate a self-managed zone Control Plane to Konnect

Uses: Kong Mesh
Related Documentation

If you already have zone Control Planes in Kong Mesh, you can migrate them to Konnect using Mesh Manager.

Here are a few benefits of managing your service mesh in Konnect:

  • Kong-managed global Control Plane: Konnect hosts and operates the global Control Plane for you.
  • Unified view: Access all Kong Mesh, Kong Ingress Controller, and Konnect entities from one place.
  • Setup wizard: A UI-driven setup guides you through zone configuration.

This guide explains how to migrate a self-managed zone Control Plane to Konnect.

Before migration

Figure 1: Kong Mesh services and data plane proxies connect to a self-managed global Control Plane.

After migration

Figure 2: After migration, the global Control Plane is hosted in Konnect, while zones and services remain self-managed.

Limitation

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.

Prerequisites

Transfer resources from the self-managed global Control Plane

  1. Make sure your self-managed global Control Plane is the active context:

    kumactl config control-planes list
    
    Copied to clipboard!

    If using Kubernetes, you can port-forward for access:

    kubectl port-forward deployment/mesh-cp-name -n mesh-namespace 5681
    
    Copied to clipboard!
  2. Export mesh resources and policies using this script:

    #!/bin/bash
    
    outdir="policies"
    mkdir -p ${outdir}
    
    types="circuit-breakers external-services fault-injections healthchecks meshaccesslogs meshcircuitbreakers
    meshfaultinjections meshgateways meshgatewayroutes meshhealthchecks meshhttproutes meshloadbalancingstrategies
    meshproxypatches meshratelimits meshretries meshtcproutes meshtimeouts meshtraces meshtrafficpermissions
    proxytemplates rate-limits retries timeouts traffic-logs traffic-permissions traffic-routes traffic-traces
    virtual-outbounds access-role-bindings access-roles accessaudits meshglobalratelimits meshopas opa-policies"
    
    meshes=$(kumactl get meshes -oyaml | yq '.items[].name')
    
    for mesh in ${meshes}; do
      kumactl get mesh ${mesh} -oyaml | yq '(del(.creationTime,.modificationTime))' > "${outdir}/${mesh}.yaml"
      echo "---" >> "${outdir}/${mesh}.yaml"
    
      for type in ${types}; do
        kumactl get ${type} --mesh ${mesh} -oyaml | yq '.items[] |= (del(.creationTime,.modificationTime)) | .items[] | split_doc' | grep ^ >> "${outdir}/${mesh}.yaml" && echo "---" >> "${outdir}/${mesh}.yaml"
      done
    done
    
    Copied to clipboard!
  3. If mTLS is enabled, copy mesh secrets:

    • Builtin CA: Copy secrets named {mesh}.ca-builtin-cert-{backend} and {mesh}.ca-builtin-key-{backend}.
    • Provided CA: Copy the secrets listed in the mesh resource. See mTLS secret storage for details.
  4. Switch to the Konnect global Control Plane:

    kumactl config control-planes switch --name {konnect-config-name}
    
    Copied to clipboard!
  5. Apply the exported resources:

    kumactl apply -f {file_name}
    
    Copied to clipboard!

Connect the zone Control Plane to Konnect

  1. Create a new zone in Konnect.

    Use the same name as the existing zone. Replace your current zone’s values.yaml with the config provided by the UI wizard.

  2. If KDS TLS is enabled with self-signed certs, disable custom certs so the zone can use Konnect’s default CA:

    kumactl install control-plane \
      --set "kuma.controlPlane.tls.kdsZoneClient.secretName=kds-ca-certs" \
      | kubectl apply -f -
    
    Copied to clipboard!
  3. Restart the zone Control Plane.

    Konnect will automatically detect and display the new zone in the UI.

Did this doc help?

Something wrong?

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!