You are browsing unreleased documentation. See the latest documentation here.

Kubernetes cert-manager CA Policy

Available with Kong Gateway Enterprise subscription - Contact Sales

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

In certmanager mTLS mode, Kong Mesh communicates with a locally installed cert-manager Issuer, 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.

In certmanager mode, you provide Kong Mesh with a cert-manager Issuer or ClusterIssuer reference. Kong Mesh will communicate with cert-manager via Kubernetes resources which reference the Issuer or ClusterIssuer.

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

The certmanager mTLS backend requires a cert-manager Issuer or ClusterIssuer to be accessible from the Kong Mesh system namespace. A ClusterIssuer is accessible from the entire Kubernetes cluster. An 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, and ClusterIssuer is not used, this may require cert-manager configuration and secrets to be “reflected” into the Issuer 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 Issuer or ClusterIssuer to configure Kong Mesh

Configure Mesh

Here’s an example of mTLS configuration with certmanager backend which references an Issuer named my-ca-issuer:

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
        caCert: # can be used to specify the root CA
          inlineString: | # or secret
            -----BEGIN CERTIFICATE-----
            ...

In issuerRef, only name is strictly required. group and kind will default to cert-manager default values. See issuerRef in cert-manager API for details.

If caCert is not provided, Kong Mesh assumes that the issuer sets status.CA on CertificateRequests. Note that if secret is used, it must be a Kong Mesh Secret.

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 Issuer or ClusterIssuer resource with the issuerRef specified in the Mesh 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.