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
Early Access
  • 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
    • 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
    • MeshTrace (Beta)
    • MeshAccessLog (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • 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

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Data plane proxy to control plane communication
    • Encrypted communication
    • Authentication
  • Prometheus to control plane communication
  • User to control plane communication
    • Encrypted communication
    • Authentication
  • Control plane to control plane (Multizone)
    • Encrypted communication
    • Authentication
Kong Mesh
2.0.x
  • Home
  • Kong Mesh
  • Security
  • Secure access across Kong Mesh components
You are browsing documentation for an outdated version. See the latest documentation here.

Secure access across Kong Mesh components

This page explains how secure access is provided across a Kong Mesh deployment:

  • security between the data plane proxies and the Kong Mesh control plane
  • security between the user and the Kong Mesh control plane
  • security between the Kong Mesh control planes (Multizone)

Kong Mesh stores autogenerated certificates and other files in a working directory. The default value for this directory is $HOME/.kuma. You can change the working directory by setting the KUMA_GENERAL_WORK_DIR environment variable.

This section is not to be confused with the mTLS policy that we can apply to a Mesh to secure service-to-service traffic.

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.

It is recommended that the data plane proxy verifies 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 service-to-service communication.

To override autogenerated certificates

If overridden, Kong Mesh uses the certificates to protect not only data plane proxy to control plane traffic but also user to control plane traffic and control plane to control plane traffic.

1) Prepare certificates

Generate a TLS pair with a PKI of your choice and store it in PEM-encoded format in /tmp/tls.crt, /tmp/tls.key. Store the CA that was used to sign this pair in /tmp/ca.crt.

We can also use kumactl to generate self-signed certs:

kumactl generate tls-certificate \
  --type=server \
  --hostname=<KUMA_CP_DNS_NAME> \
  --cert-file=/tmp/tls.crt \
  --key-file=/tmp/tls.key

Since “tls.crt” is a self-signed cert, it is also a CA:

cp /tmp/tls.crt /tmp/ca.crt

2) Configure the control plane with generated certs:

Kubernetes (kumactl)
Kubernetes (HELM)
Universal

Create a secret in the namespace where the control plane is installed:

kubectl create secret generic general-tls-certs -n <namespace> \
  --from-file=tls.crt=/tmp/tls.crt \
  --from-file=tls.key=/tmp/tls.key \
  --from-file=ca.crt=/tmp/ca.crt

Point to this secret when installing Kong Mesh:

kumactl install control-plane \
  --tls-general-secret=general-tls-certs \
  --tls-general-ca-bundle=$(cat /tmp/ca.crt | base64)

The data plane proxy Injector in the control plane automatically provides the CA to the Kong Mesh DP sidecar so Kong Mesh DP can confirm the control plane identity.

Create a secret in the namespace where the control plane is installed:

kubectl create secret generic general-tls-certs -n <namespace> \
  --from-file=tls.crt=/tmp/tls.crt \
  --from-file=tls.key=/tmp/tls.key \
  --from-file=ca.crt=/tmp/ca.crt

Point to this secret when installing Kong Mesh:

helm install --create-namespace --namespace <namespace> kuma kuma/kuma \
  --set controlPlane.tls.general.secretName=general-tls-certs \
  --set controlPlane.tls.general.caBundle=$(cat /tmp/ca.crt | base64)

The data plane proxy Injector in the control plane automatically provides the CA to the Kong Mesh DP sidecar so Kong Mesh DP can confirm the control plane identity.

Configure the control plane with generated certificates:

KUMA_GENERAL_TLS_CERT_FILE=/tmp/tls.crt \
  KUMA_GENERAL_TLS_KEY_FILE=/tmp/tls.key \
  kuma-cp run

Configure the data plane proxy with CA:

kuma-dp run \
  --cp-address=https://<KUMA_CP_DNS_NAME>:5678 \
  --ca-cert-file=/tmp/ca.crt \
  --dataplane-file=dp.yaml \
  --dataplane-token-file=/tmp/kuma-dp-redis-1-token

You can also provide the CA via environment variable KUMA_CONTROL_PLANE_CA_CERT.

Authentication

See Data plane proxy authentication and Zone proxy authentication.

Prometheus to control plane communication

You can enable TLS on the Monitoring Assignment Discovery Service. By default, it uses the same certificate used for CP to DP communication. This is the certificate configured with the --tls-general options. You can enable it by using the KUMA_MONITORING_ASSIGNMENT_SERVER_TLS_ENABLED=true environment variable.

Kubernetes
Universal

Create a secret in the namespace where the control plane is installed:

kubectl create secret generic general-tls-certs -n <namespace> \
  --from-file=tls.crt=/tmp/tls.crt \
  --from-file=tls.key=/tmp/tls.key \
  --from-file=ca.crt=/tmp/ca.crt

Point to this secret when installing Kuma:

kumactl install control-plane \
  --tls-general-secret=general-tls-certs \
  --tls-general-ca-bundle=$(cat /tmp/ca.crt | base64) \
  --env-var 'KUMA_MONITORING_ASSIGNMENT_SERVER_TLS_ENABLED=true'

Configure the control plane with generated certificates:

KUMA_MONITORING_ASSIGNMENT_SERVER_TLS_CERT_FILE=/tmp/tls.crt \
  KUMA_MONITORING_ASSIGNMENT_SERVER_TLS_KEY_FILE=/tmp/tls.key \
  KUMA_MONITORING_ASSIGNMENT_SERVER_TLS_ENABLED=true \
  kuma-cp run

Now you can configure Kuma’s Prometheus SD with the correct TLS configuration using the Prometheus docs.

User to control plane communication

Users and automation tools can interact with the control plane via the API Server using tools like curl or kumactl. API Server is exposed by default on :5681 on HTTP and :5682 on HTTPS.

Encrypted communication

The API Server HTTPS server is secured by default by autogenerated certificates.

To override autogenerated certificates.

1) Prepare certificates

Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in /tmp/tls.crt, /tmp/tls.key. Store the CA that was used to sign this pair in /tmp/ca.crt

We can also use kumactl to generate self-signed certs:

kumactl generate tls-certificate \
  --type=server \
  --hostname=<KUMA_CP_DNS_NAME> \
  --cert-file=/tmp/tls.crt \
  --key-file=/tmp/tls.key

Since “tls.crt” is a self-signed cert, it is also a CA:

cp /tmp/tls.crt /tmp/ca.crt

2) Configure the control plane with generated certificates

Kubernetes (kumactl)
Kubernetes (HELM)
Universal

Create a secret in the namespace in which the control plane is installed:

kubectl create secret tls api-server-tls -n <namespace> \
  --cert=/tmp/tls.crt \
  --key=/tmp/tls.key

Point to this secret when installing Kong Mesh:

kumactl install control-plane \
  --tls-api-server-secret=api-server-tls

Create a secret in the namespace in which the control plane is installed:

kubectl create secret tls api-server-tls -n <namespace> \
  --cert=/tmp/tls.crt \
  --key=/tmp/tls.key

Point to this secret when installing Kong Mesh:

helm install --create-namespace --namespace <namespace> kuma kuma/kuma \
  --set controlPlane.tls.apiServer.secretName=api-server-tls

Point to the certificate and the key:

KUMA_API_SERVER_HTTPS_TLS_CERT_FILE=/tmp/tls.crt \
  KUMA_API_SERVER_HTTPS_TLS_KEY_FILE=/tmp/tls.key \
  kuma-cp run

3) Configure secure connection using kumactl CLI tool:

kumactl config control-planes add \
  --name=<NAME> \
  --address=https://<KUMA_CP_DNS_NAME>:5682 \
  --ca-cert-file=/tmp/ca.crt \

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 KUMA_API_SERVER_HTTP_ENABLED: false

Authentication

See API Server authentication.

Control plane to control plane (Multizone)

A zone control plane connects to a global control plane for policies configuration.

Encrypted communication

Because the global control plane and the zone control plane exchange sensitive information, the communication needs to be encrypted by TLS. By default, the global control plane’s server that is consumed by the zone control plane is secured by TLS with autogenerated certificates.

It is recommended that the zone control plane verifies the identity of the global control plane. To do so, zone control planes need to obtain the CA that was used to generate the certificate by which the control plane’s server is secured.

To override autogenerated certificates

1) Prepare certificates

Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in /tmp/tls.crt, /tmp/tls.key. Store the CA that was used to sign this pair in /tmp/ca.crt

We can also use kumactl to generate self-signed certs:

kumactl generate tls-certificate \
  --type=server \
  --hostname=<CROSS_ZONE_KUMA_CP_DNS_NAME> \
  --cert-file=/tmp/tls.crt \
  --key-file=/tmp/tls.key

Since “tls.crt” is a self-signed cert, it is also a CA:

cp /tmp/tls.crt /tmp/ca.crt

2) Configure global control plane

Kubernetes (kumactl)
Kubernetes (HELM)
Universal

Create a secret in the namespace where the global control plane is installed:

kubectl create secret tls kds-server-tls -n <namespace> \
  --cert=/tmp/tls.crt \
  --key=/tmp/tls.key

Point to this secret when installing the global control plane:

kumactl install control-plane \
  --mode=global \
  --tls-kds-global-server-secret=general-tls-certs

Create a secret in the namespace where the global control plane is installed:

kubectl create secret tls kds-server-tls -n <namespace> \
  --cert=/tmp/tls.crt \
  --key=/tmp/tls.key

Point to this secret when installing Kong Mesh:

helm install --create-namespace --namespace <namespace> kuma kuma/kuma \
  --set controlPlane.tls.kdsGlobalServer.secretName=kds-server-tls

Point to the certificate and the key:

KUMA_MULTIZONE_GLOBAL_KDS_TLS_CERT_FILE=/tmp/tls.crt \
  KUMA_MULTIZONE_GLOBAL_KDS_TLS_KEY_FILE=/tmp/tls.key \
  KUMA_MODE=global \
  kuma-cp run

3) Configure the zone control plane

Kubernetes (kumactl)
Kubernetes (HELM)
Universal

Create a secret in the namespace where the zone control plane is installed:

kubectl create secret generic kds-ca-certs -n <namespace> \
  --from-file=ca.crt.pem=/tmp/ca.crt

Point to this secret when installing the zone control plane:

kumactl install control-plane \
  --mode=zone \
  --tls-kds-zone-client-secret=kds-ca-certs

Create a secret in the namespace where the zone control plane is installed:

kubectl create secret generic kds-ca-certs -n <namespace> \
  --from-file=ca.crt.pem=/tmp/ca.crt

Point to this secret when installing Kong Mesh:

helm install --create-namespace --namespace <namespace> kuma kuma/kuma \
  --set controlPlane.tls.kdsZoneClient.secretName=kds-ca-certs

Point to the certificate and the key:

KUMA_MULTIZONE_ZONE_KDS_ROOT_CA_FILE=/tmp/ca.crt \
  KUMA_MODE=zone \
  KUMA_MULTIZONE_ZONE_GLOBAL_ADDRESS=grpcs://<CROSS_ZONE_KUMA_CP_DNS_NAME>:5685 \
  kuma-cp run

Authentication

Define firewall rules on the global control plane to only accept connections from known IPs of the zone control planes.

Third-party extensions, cloud implementations or commercial offerings may be extending the authentication support.

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