Create a global control plane and a system account zone token with the Konnect API, then deploy a Universal (VM or bare metal) zone control plane that connects to the Konnect-managed global control plane.
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'Using the Konnect API, you can create a global control plane that Konnect manages while you run your zone control planes on Universal (VMs or bare metal). This guide creates a global control plane, provisions a zone token, and deploys a Universal zone control plane that connects to Konnect.
To deploy services and test traffic across the mesh, see Configure a Kong Mesh global control plane on Kubernetes with the Konnect API.
Before you can add services or apply configurations, you must create a global control plane.
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"
}'Export the control plane id so you can reference it when you create a zone:
export CONTROL_PLANE_ID='YOUR_CONTROL_PLANE_ID'Export your region:
export KONNECT_REGION='us'The global control plane is now created but has no functionality until you connect a zone.
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.
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'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"'"
}'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.
Export the token:
export CONTROL_PLANE_TOKEN='YOUR_ZONE_TOKEN'With the token created, deploy the zone control plane on your machine:
Create and navigate to the working directory for this guide:
mkdir -p ~/mesh-konnect && cd ~/mesh-konnectExport the KDS global address for your region:
export CONTROL_PLANE_URL="grpcs://$KONNECT_REGION.mesh.sync.konghq.com:443"Save the control plane token to a file:
echo $CONTROL_PLANE_TOKEN > cpTokenFile && chmod 600 cpTokenFileCreate the zone configuration file:
cat <<EOF > config.yaml
environment: universal
mode: zone
multizone:
zone:
name: zone-1
globalAddress: $CONTROL_PLANE_URL
kmesh:
multizone:
zone:
konnect:
cpId: $CONTROL_PLANE_ID
experimental:
kdsDeltaEnabled: true
EOFDownload and install Kong Mesh:
curl -L http://developer.konghq.com/mesh/installer.sh | sh -Start the zone control plane in the background, so you can keep using the same terminal (and its exported variables) for the following steps:
KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_PATH=cpTokenFile kong-mesh-*/bin/kuma-cp run --config-file config.yaml > kuma-cp.log 2>&1 &The control plane keeps running in the background and its output goes to
kuma-cp.log. Check that file if the zone doesn’t connect. To stop it later, runpkill -f kuma-cp.
Confirm the zone is connected to your global control plane:
zone-1 appears in the list of zones with an Online status.Stop the background zone control plane started in this guide:
pkill -f kuma-cpDelete 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"Return to the parent directory, then delete the working directory and the files created during this guide:
cd ../
rm -rf ~/mesh-konnectHow 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:
kpat_ and tied to an individual user account. Use a PAT for interactive or one-off tasks.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.