# PKI certificates
This section addresses the certificate generation in Kuma across the following use-cases:
- 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 system access the control plane.
# 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.
For security purposes, the data plane proxy must verify 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 data plane proxy to data plane proxy communication.
# Data plane proxy authentication
To obtain an mTLS certificate from the server (SDS (opens new window) built-in in the control plane), a data plane proxy must authenticate itself.
When running in multizone, mode we can generate data plane proxy token both on Global and Remote Control Plane. If the deployment pipeline is configured to generate data plane proxy token before running the proxy, it can rely on the Remote CP. This way Global CP is not a single point of failure.
# Data plane to data plane communication
Kuma helps us to secure the existing infrastructure with mTLS.
# Mutual TLS
Once a data plane proxy has proved its identity to the control plane, it will be allowed to fetch its own identity certificate and a root CA certificate of the mesh. When establishing a connection between two data plane proxies, each side validates the other's certificate using the root CA of the mesh, which then confirms their identity.
mTLS is not enabled by default. To enable it, we must apply proper settings in Mesh policy. Additionally, when running on Universal we have to ensure that every data plane proxy in the mesh has been configured with a dataplane proxy token.
In Kuma, any TLS certificate that is being issued by the control plane must have a CA (Certificate Authority) that can be either auto-generated by Kuma via a
builtin backend, or can be initialized with a customer certificate and key via a
Third-party extensions, cloud implementations or commercial offerings may be extending the CA backend support.
provided CA backends, on Kubernetes the root CA certificate is stored as a Kubernetes Secret (opens new window), while on Universal Kuma leverages the same underlying storage backend that is used for storing policies.
When the mTLS policy is enabled, data plane proxy certificates are ephemeral: thet are re-created on every data plane proxy restart and never persisted on disk.
Data plane proxy certificates generated by Kuma are X.509 certificates that are SPIFFE (opens new window) compliant. The SAN of the certificates is set to
spiffe://<mesh name>/<service name>.
# User to control plane communication
Users and automation tools can interact with the control plane via the API Server using tools like
API Server is exposed by default on
:5681 on HTTP and
:5682 on HTTPS.
# Encrypted communication
API Server HTTPS server is secured by default by autogenerated certificates. We can override those certificates.
We can then configure secure connection using
kumactl CLI tool.
kumactl config control-planes add \ --name <NAME> \ --address https://<KUMA_CP_DNS_NAME>:5682 \ --ca-cert-file <CA.PEM> \
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
Some endpoints like managing Secrets or generating data plane proxy token require authentication. There are two ways to access those endpoints.
# Request originating from localhost
For the simplicity of use, requests that are originating from the same machine as CP are authenticated. We can disable this behavior by setting
On Kubernetes, we can port-forward 5681 port and access the admin endpoints.
# Client certificates
When accessing admin endpoints from a different machine we need to use client certificates.
- Generate client certificates by using kumactl
$ kumactl generate tls-certificate --type=client \ --cert-file=/path/to/cert \ --key-file=/path/to/key
- Configure the control plane with client certificates
kumactlwith valid client certificates
$ kumactl config control-planes add \ --name <NAME> --address https://<KUMA_CP_DNS_NAME>:5682 \ --client-cert-file <CERT.PEM> \ --client-key-file <KEY.PEM> \ --ca-cert-file <CA.PEM>
# 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 (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
We can also provide a client key and certificate for mTLS using the
KUMA_STORE_POSTGRES_TLS_KEY_PATH variables. This pair can be used in conjunction with the
cert auth-method described here (opens new window).