Create a global control plane with a request to the Mesh control planes API, then provision a zone by creating a system account access token with the Connector role and deploying a zone control plane with it. Deploy workloads with kubectl and use kumactl for read-only visibility.
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'This guide requires a running Kubernetes cluster that supports the LoadBalancer service type. If you already have a Kubernetes cluster running, you can skip this step.
It can be a cluster running locally, like Docker, or in a public cloud like AWS EKS, GCP GKE, etc.
Using the Konnect API, you can create a global control plane, connect a Kubernetes zone, and manage your Kong Mesh mesh. This guide creates a global control plane, provisions a zone token, deploys a zone control plane and the demo application, and validates traffic through the mesh.
To run your zone control plane on a VM or bare metal instead, see Configure a Kong Mesh global control plane on Universal 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 Kubernetes cluster:
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"Create the kong-mesh-system namespace:
kubectl create namespace kong-mesh-systemAdd the Kong Mesh Helm repository:
helm repo add kong-mesh https://kong.github.io/kong-mesh-chartsUpdate your Helm repositories:
helm repo updateStore the control plane 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 -Create the Helm values file:
cat <<EOF > values.yaml
kuma:
controlPlane:
mode: zone
zone: zone-1
kdsGlobalAddress: $CONTROL_PLANE_URL
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
EOFInstall Kong Mesh:
helm upgrade --install -n kong-mesh-system kong-mesh kong-mesh/kong-mesh -f values.yamlOnce the zone control plane is running, it connects to the global control plane and appears in Konnect.
To test your mesh, deploy the Kong Mesh demo app into the kong-mesh-demo namespace:
echo "
apiVersion: v1
kind: Namespace
metadata:
labels:
kuma.io/sidecar-injection: enabled
name: kong-mesh-demo
---
apiVersion: v1
kind: Service
metadata:
name: demo-app
namespace: kong-mesh-demo
spec:
ports:
- appProtocol: http
port: 5050
protocol: TCP
targetPort: 5050
selector:
app: demo-app
---
apiVersion: v1
kind: Service
metadata:
name: kv
namespace: kong-mesh-demo
spec:
ports:
- appProtocol: http
port: 5050
protocol: TCP
targetPort: 5050
selector:
app: kv
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: demo-app
version: v1
name: demo-app
namespace: kong-mesh-demo
spec:
replicas: 1
selector:
matchLabels:
app: demo-app
version: v1
template:
metadata:
labels:
app: demo-app
version: v1
spec:
containers:
- env:
- name: KV_URL
value: http://kv.kong-mesh-demo.svc.cluster.local:5050
- name: APP_VERSION
valueFrom:
fieldRef:
fieldPath: metadata.labels['version']
image: ghcr.io/kumahq/kuma-counter-demo:latest@sha256:daf8f5cffa10b576ff845be84e4e3bd5a8a6470c7e66293c5e03a148f08ac148
name: demo-app
ports:
- containerPort: 5050
name: http
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: kv
namespace: kong-mesh-demo
spec:
replicas: 1
selector:
matchLabels:
app: kv
template:
metadata:
labels:
app: kv
spec:
containers:
- image: ghcr.io/kumahq/kuma-counter-demo:latest
name: kv
ports:
- containerPort: 5050
name: http
" | kubectl apply -f -Wait for the demo app to be ready:
kubectl wait -n kong-mesh-demo --for=condition=available --timeout=120s deployment --allThis creates:
demo-app: a counter web app on port 5050kv: the key-value store that backs the counterConfirm the zone and demo services are connected to your global control plane.
Click default, then click the Services tab.
You should see the demo-app and kv services.
It may take a few minutes for the services to reach the
Onlinestatus.
Port-forward the demo-app service to your local machine:
kubectl port-forward svc/demo-app -n kong-mesh-demo 5050:5050In a browser, go to http://127.0.0.1:5050 and increment the counter.
The counter is stored in the kv service through the mesh, so a successful increment confirms that traffic is flowing between your services.
Delete the demo app namespace and all of its resources:
kubectl delete namespace kong-mesh-demoUninstall Kong Mesh and remove its namespace:
helm uninstall kong-mesh --namespace kong-mesh-system
kubectl delete namespace kong-mesh-systemDelete 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.
How do I configure kumactl to connect to the global control plane?
Because the mesh is deployed on Kubernetes, kumactl is read-only. You manage resources using kubectl. Still, we recommend configuring kumactl for visibility and diagnostics.
kumactl.See the kumactl command reference for more information.