Kuma helps you secure your existing infrastructure with mTLS. The following sections cover details of how it works.
Kuma uses a built-in CA (Certificate Authority) to issue certificates for dataplanes. The root CA certificate is unique for each mesh in the system. On Kubernetes, the root CA certificate is stored as a Kubernetes Secret (opens new window). On Universal, we leverage the same storage (Postgres) that is used for storing policies. Certificates for dataplanes are ephemeral, re-created on dataplane restart and never persisted on disk.
Dataplane certificates generated by Kuma are X.509 certificates that are SPIFFE (opens new window) compliant. The SAN of certificate is set to
spiffe://<mesh name>/<service name>
Kuma also supports other CAs. For further details refer to Mutual TLS policy.
# Dataplane Authentication
In order to obtain an mTLS certificate from the server (SDS (opens new window) built-in in the control plane), a dataplane must authenticate itself.
# Accessing Admin Server from a different machine
By default, the Admin Server that is serving Dataplane Tokens is exposed only on
localhost. If you want to generate tokens from a different machine than the control plane you have to secure the connection:
- Enable public server by setting
true. Make sure to specify hostname which can be used to access Kuma from other machine via
- Generate certificate for the HTTPS Admin Server and set via
KUMA_ADMIN_SERVER_PUBLIC_TLS_KEY_FILEconfig environment variable. For generating self-signed certificate you can use
$ kumactl generate tls-certificate --cert-file=/path/to/cert --key-file=/path/to/key --type=server --cp-hostname=<name from KUMA_GENERAL_ADVERTISED_HOSTNAME>
- Pick a public interface on which HTTPS server will be exposed and set it via
KUMA_ADMIN_SERVER_PUBLIC_INTERFACE. Optionally pick the port via
KUMA_ADMIN_SERVER_PUBLIC_PORT. By default, it will be the same as the port for the HTTP server exposed on localhost.
- Generate one or more certificates for the clients of this server. Pass the path to the directory with client certificates (without keys) via
KUMA_ADMIN_SERVER_PUBLIC_CLIENT_CERTS_DIR. For generating self-signed client certificates you can use
$ kumactl generate tls-certificate --cert-file=/path/to/cert --key-file=/path/to/key --type=client
kumactlwith client certificate.
$ kumactl config control-planes add \ --name <NAME> --address http://<KUMA_CP_DNS_NAME>:5681 \ --admin-client-cert <CERT.PEM> \ --admin-client-key <KEY.PEM>
When running in multizone mode you can generate tokens both on Global and Remote Control Plane If you configure your deployment pipeline to generate Dataplane Token before running a dataplane you can use Remote CP. This way Global CP is not a single point of failure.
If you are running Global CP on Kubernetes and trying to generate tokens. Port forward
5681 ports first and then use
curl) to generate tokens.
Once a dataplane has proved its identity, it will be allowed to fetch its own identity certificate and a root CA certificate of the mesh. When establishing a connection between two dataplanes each side validates each other dataplane certificate confirming the identity using the root CA of the mesh.
mTLS is not enabled by default. To enable it, apply proper settings in Mesh policy. Additionally, when running on Universal you have to ensure that every dataplane in the mesh has been configured with a Dataplane Token.
When mTLS is enabled, every connection between dataplanes is denied by default, so you have to explicitly allow it using TrafficPermission.
Since on Universal, the 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, first 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 for verification server's certificate can be set using
Once secured connections are configured in Kuma CP, you have to configure Postgres'
pg_hba.conf (opens new window) 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
You can also provide client key and certificate for mTLS using
This pair can be used for auth-method
cert described here (opens new window).