Deploy a single-zone control plane
In order to deploy Kuma in a single-zone deployment, the kuma-cp control plane must be started in zone mode:
This is the standard installation method. After the installation, make sure to restart application pods that are running such that the data plane objects can be generated and the proxies can be connected.
kumactl install control-plane \
--set "controlPlane.mode=zone" \
| kubectl apply -f -
# Before installing Kuma with Helm, configure your local Helm repository:
# https://kuma.io/docs/dev/production/cp-deployment/kubernetes/#helm
helm install \
--create-namespace \
--namespace kuma-system \
--set "controlPlane.mode=zone" \
kuma kuma/kuma
With zone egress:
It’s possible to run ZoneEgress for single-zone deployment. In order to deploy Kuma with ZoneEgress run the install command with an additional parameter.
kumactl install control-plane \
--set "controlPlane.mode=zone" \
--set "egress.enabled=true" \
| kubectl apply -f -
# Before installing Kuma with Helm, configure your local Helm repository:
# https://kuma.io/docs/dev/production/cp-deployment/kubernetes/#helm
helm install \
--create-namespace \
--namespace kuma-system \
--set "controlPlane.mode=zone" \
--set "egress.enabled=true" \
kuma kuma/kuma
When running a control plane in Universal mode, a database must be used to persist state for production deployments.
Ensure that migrations have been run against the database prior to running the control plane.
This is the standard installation method.
KUMA_STORE_TYPE=postgres \
KUMA_STORE_POSTGRES_HOST=<postgres-host> \
KUMA_STORE_POSTGRES_PORT=<postgres-port> \
KUMA_STORE_POSTGRES_USER=<postgres-user> \
KUMA_STORE_POSTGRES_PASSWORD=<postgres-password> \
KUMA_STORE_POSTGRES_DB_NAME=<postgres-db-name> \
kuma-cp run
With zone egress:
ZoneEgress works for Universal deployment as well. In order to deploy ZoneEgress for Universal deployment follow the instruction.
Once Kuma is up and running, data plane proxies can now connect directly to it.
When the mode is not specified, Kuma will always start in zone mode by default.
Optional: control plane authentication
Running administrative tasks (like generating auth tokens) requires authentication by token or a connection via localhost when interacting with the control plane.
You can authenticate by port-forwarding API service and extracting admin user token.
kubectl port-forward svc/kuma-control-plane -n kuma-system 5681:5681
export ADMIN_TOKEN=$(kubectl get secrets -n kuma-system admin-user-token -ojson | jq -r .data.value | base64 -d)
kumactl config control-planes add \
--address http://localhost:5681 \
--headers "authorization=Bearer $ADMIN_TOKEN" \
--name "zone-cp" \
--overwrite
Localhost authentication
For kuma-cp to recognize requests issued to docker published port it needs to run the container in the host network.
To do this, add --network="host" parameter to the docker run command.
Authenticate via token
You can also configure kumactl to access kuma-dp from the container.
Get the kuma-cp container id:
docker ps # copy kuma-cp container id
export KUMA_CP_CONTAINER_ID='...'
Configure kumactl:
TOKEN=$(bash -c "docker exec -it $KUMA_CP_CONTAINER_ID wget -q -O - http://localhost:5681/global-secrets/admin-user-token" | jq -r .data | base64 -d)
kumactl config control-planes add \
--name my-control-plane \
--address http://localhost:5681 \
--auth-type=tokens \
--auth-conf token=$TOKEN \
--skip-verify
Moving to a multi-zone deployment
You can transform a single-zone deployment into a multi-zone deployment by doing federation.
