Careful!
You are browsing documentation for a version of Kuma that is not the latest release.
Looking for even older versions? Learn more.
Secure access across services
This page explains how secure access is provided across a Kuma deployment:
- Security between our services, via the mTLS policy.
- Security between the Kuma control plane and its data plane proxies, via the data plane proxy token.
- Security when accessing the control plane.
- Security when external systems access the control plane.
Kuma stores autogenerated certificates and other files in a working directory. The default value for this
directory is $HOME/.kuma
. You can change the working directory by setting the KUMA_GENERAL_WORK_DIR
environment variable.
This section is not to be confused with the mTLS policy that we can apply to a Mesh to secure service-to-service traffic.
Data plane proxy to control plane communication
A data plane proxy connects to the control plane for its configuration, including mTLS certificates described in the following sections.
Encrypted communication
Because the data plane proxy and the control plane exchange sensitive information, the communication needs to be encrypted by TLS. By default, the control plane’s server that is consumed by the data plane proxy is secured by TLS with autogenerated certificates.
It is recommended that the data plane proxy verifies the identity of the control plane. To do so, data plane proxies need to obtain the CA that was used to generate the certificate by which the control plane’s server is secured. Note, this CA is not the same CA for service-to-service communication.
To override autogenerated certificates
1) Prepare certificates
Generate a TLS pair with a PKI of your choice and store it in PEM-encoded format in /tmp/tls.crt
, /tmp/tls.key
. Store the CA that was used to sign this pair in /tmp/ca.crt
We can also use kumactl
to generate self-signed certs.
kumactl generate tls-certificate \
--type=server \
--hostname=kuma-control-plane.kuma-system \ # adjust the name if you are installing Kuma to other namespace
--hostname=kuma-control-plane.kuma-system.svc \ # adjust the name if you are installing Kuma to other namespace
--cert-file=/tmp/tls.crt \
--key-file=/tmp/tls.key
cp /tmp/tls.crt /tmp/ca.crt # since this is self-signed cert, the cert is also a CA
2) Create a secret in the namespace where the control plane is installed
kubectl create secret generic general-tls-certs -n kuma-system \
--from-file=tls.crt=/tmp/tls.crt \
--from-file=tls.key=/tmp/tls.key \
--from-file=ca.crt=/tmp/ca.crt
3) Point to this secret when installing Kuma
kumactl install control-plane \
--tls-general-secret=general-tls-certs \
--tls-general-ca-bundle=$(cat /tmp/ca.crt | base64)
The data plane proxy Injector in the control plane automatically provides the CA to the Kuma DP sidecar so Kuma DP can confirm the control plane identity.
When configured using the --tls-general-secret
and --tls-general-ca-bundle
flags, Kuma will use the specified CA and certificate to protect data plane proxy to control plane traffic. Additionally, if not configured otherwise using additional options described below, Kuma will also use the specified CA and certificate to protect user to control plane traffic and control plane to control plane traffic when in multizone configurations.
Authentication
See Data plane proxy authentication and Zone Ingress authentication.
User to control plane communication
Users and automation tools can interact with the control plane via the API Server using tools like curl
or kumactl
.
API Server is exposed by default on :5681
on HTTP and :5682
on HTTPS.
Encrypted communication
The API Server HTTPS server is secured by default by autogenerated certificates.
To override autogenerated certificates.
1) Prepare certificates
Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in /tmp/tls.crt
, /tmp/tls.key
. Store the CA that was used to sign this pair in /tmp/ca.crt
We can also use kumactl
to generate self-signed certs.
kumactl generate tls-certificate \
--type=server \
--hostname=<KUMA_CP_DNS_NAME> \ # pick a name that will be used by kumactl or other client to connect to the control plane
--cert-file=/tmp/tls.crt \
--key-file=/tmp/tls.key
cp /tmp/tls.crt /tmp/ca.crt # since this is self-signed cert, the cert is also a CA
2) Configure the control plane with generated certificates
Create a secret in the namespace in which the control plane is installed
kubectl create secret tls api-server-tls -n kuma-system \
--cert=/tmp/tls.crt \
--key=/tmp/tls.key
Point to this secret when installing Kuma
kumactl install control-plane \
--tls-api-server-secret=api-server-tls
3) Configure secure connection using kumactl
CLI tool.
kumactl config control-planes add \
--name=<NAME> \
--address=https://<KUMA_CP_DNS_NAME>:5682 \
--ca-cert-file=/tmp/ca.crt \
We can also hide the HTTP version of API Server by binding it to localhost KUMA_API_SERVER_HTTP_INTERFACE: 127.0.0.1
or by disabling it altogether KUMA_API_SERVER_HTTP_ENABLED: false
Authentication
See API Server authentication.
Control plane to control plane (Multizone)
A zone control plane connects to a global control plane for policies configuration.
Encrypted communication
Because the global control plane and the zone control plane exchange sensitive information, the communication needs to be encrypted by TLS. By default, the global control plane’s server that is consumed by the zone control plane is secured by TLS with autogenerated certificates.
It is recommended that the zone control plane verifies the identity of the global control plane. To do so, zone control planes need to obtain the CA that was used to generate the certificate by which the control plane’s server is secured.
To override autogenerated certificates
1) Prepare certificates
Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in /tmp/tls.crt
, /tmp/tls.key
. Store the CA that was used to sign this pair in /tmp/ca.crt
We can also use kumactl
to generate self-signed certs.
kumactl generate tls-certificate \
--type=server \
--hostname=<CROSS_ZONE_KUMA_CP_DNS_NAME> \
--cert-file=/tmp/tls.crt \
--key-file=/tmp/tls.key
cp /tmp/tls.crt /tmp/ca.crt # since this is self-signed cert, the cert is also a CA
2) Configure global control plane
Create a secret in the namespace where the global control plane is installed
kubectl create secret tls kds-server-tls -n kuma-system \
--cert=/tmp/tls.crt \
--key=/tmp/tls.key
Point to this secret when installing the global control plane
kumactl install control-plane \
--mode=global \
--tls-kds-global-server-secret=general-tls-certs
3) Configure the zone control plane
Create a secret in the namespace where the zone control plane is installed
kubectl create secret generic kds-ca-certs -n kuma-system \
--from-file=ca.crt.pem=/tmp/ca.crt
Point to this secret when installing the zone control plane
kumactl install control-plane \
--mode=zone \
--tls-kds-zone-client-secret=kds-ca-certs
Authentication
Define firewall rules on the global control plane to only accept connections from known IPs of the zone control planes.
Third-party extensions, cloud implementations or commercial offerings may be extending the authentication support.
Control plane to Postgres communication
Since on Universal secrets such as provided
CA’s private key are stored in Postgres, a connection between Postgres and Kuma CP should be secured with TLS.
To secure the connection, we first need to pick the security mode using KUMA_STORE_POSTGRES_TLS_MODE
. There are several modes:
disable
- is not secured with TLS (secrets will be transmitted over network in plain text).verifyNone
- the connection is secured but neither hostname, nor by which CA the certificate is signed is checked.verifyCa
- the connection is secured and the certificate presented by the server is verified using the provided CA.verifyFull
- the connection is secured, certificate presented by the server is verified using the provided CA and server hostname must match the one in the certificate.
The CA used to verify the server’s certificate can be set using the KUMA_STORE_POSTGRES_TLS_CA_PATH
environment variable.
After configuring the above security settings in Kuma, we also have to configure Postgres’ pg_hba.conf
file to restrict unsecured connections.
Here is an example configuration that will allow only TLS connections and will require username and password:
# TYPE DATABASE USER ADDRESS METHOD
hostssl all all 0.0.0.0/0 password
We can also provide a client key and certificate for mTLS using the KUMA_STORE_POSTGRES_TLS_CERT_PATH
and KUMA_STORE_POSTGRES_TLS_KEY_PATH
variables. This pair can be used in conjunction with the cert
auth-method described here.
← IPv6 Support Secrets →