You are browsing documentation for an outdated version. See the latest documentation here.
Kubernetes cert-manager CA Policy
cert-manager CA Backend
The default mTLS policy in Kong Mesh supports the following backends:
builtin: Kong Mesh automatically generates the Certificate Authority (CA) root certificate and key that will be used to generate the data plane certificates.
provided: the CA root certificate and key can be provided by the user.
Kong Mesh adds:
vault: Kong Mesh generates data plane certificates using a CA root certificate and key stored in a HashiCorp Vault server.
acmpca: Kong Mesh generates data plane certificates using Amazon Certificate Manager Private CA.
certmanager: Kong Mesh generates data plane certificates using Kubernetes cert-manager certificate controller.
Kubernetes cert-manager CA mode
certmanager mTLS mode, Kong Mesh communicates with a locally installed cert-manager
which generates the data plane proxy certificates automatically.
Kong Mesh does not retrieve any CA private keys,
which means that the private key of the CA is secured by cert-manager itself,
or an upstream CA,
and not exposed to third parties.
certmanager mode, you provide Kong Mesh with a cert-manager
ClusterIssuer reference. Kong Mesh will communicate with cert-manager
via Kubernetes resources which reference the
When Kong Mesh is running in
certmanager mode, the backend communicates with cert-manager
and ensures data plane certificates are issued and rotated for each proxy.
certmanager is only available for Kong Mesh in the Kubernetes environment.
Configure Kubernetes cert-manager CA
certmanager mTLS backend requires a cert-manager
ClusterIssuer to be accessible
from the Kong Mesh system namespace.
ClusterIssuer is accessible from the entire Kubernetes
Issuer is only accessible from within its own namespace,
and must reside in the Kong Mesh system namespace
o be available to Kong Mesh.
The Kong Mesh system namespace is
kong-mesh-system by default.
If the cert-manager is configured outside of the Kong Mesh system namespace,
ClusterIssuer is not used,
this may require cert-manager configuration and secrets to be “reflected” into the
in the Kong Mesh system namespace. See cert-manager documentation for details.
The following steps show how to configure cert-manager for Kong Mesh with
a mesh named
default. For your environment, replace
default with the appropriate mesh name.
See cert-manager.io to learn how to install and configure cert-manager.
Once created, you will need the
IssuerRef information of the
to configure Kong Mesh
Here’s an example of mTLS configuration with
which references an
apiVersion: kuma.io/v1alpha1 kind: Mesh metadata: name: default spec: mtls: enabledBackend: certmanager-1 backends: - name: certmanager-1 type: certmanager dpCert: rotation: expiration: 24h conf: issuerRef: name: my-ca-issuer kind: Issuer group: cert-manager.io
name is strictly required.
kind will default to cert-manager default values. See
issuerRef in cert-manager API for details.
Apply the configuration with
kubectl apply -f [..].
multi-zone and Kubernetes cert-manager
In a multi-zone environment, the global control plane provides the
Mesh to the zone control planes. However, you must make sure that each zone control plane can communicate with cert-manager using the same configuration.
This is because certificates for data plane proxies are requested from cert-manager by the zone control plane, not the global control plane.
This implies that each Kubernetes cluster in multi-zone must include an
resource with the
issuerRef specified in the
certmanager backend specification.
Also, because the backend is
Mesh scoped configuration and
certmanager backend is limited to the Kubernetes environment,
Universal and Kubernetes cannot be used together in a multi-zone environment which includes a
certmanager mTLS backend.
You must also ensure the global control plan can access cert-manager.
When a new
certmanagerbackend is configured, Kong Mesh validates the connection by issuing a test certificate.
In a multi-zone environment, validation is performed on the global control plane.