Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Multi-zone deployment
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Non-mesh traffic
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Understanding TargetRef policies
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshAccessLog (Beta)
    • MeshCircuitBreaker (Beta)
    • MeshFaultInjection (Beta)
    • MeshHealthCheck (Beta)
    • MeshHTTPRoute (Beta)
    • MeshProxyPatch (Beta)
    • MeshRateLimit (Beta)
    • MeshRetry (Beta)
    • MeshTimeout (Beta)
    • MeshTrace (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference
    • Open source License
    • Contribute to Mesh

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • cert-manager CA Backend
  • Kubernetes cert-manager CA mode
    • Configure Kubernetes cert-manager CA
    • Configure Mesh
  • multi-zone and Kubernetes cert-manager
Kong Mesh
2.1.x (latest)
  • Home
  • Kong Mesh
  • Features
  • Kubernetes cert-manager CA Policy

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

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

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.

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.

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.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023