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
    • Deploy a standalone control plane
    • Multi-zone deployment
    • Deploy a multi-zone global control plane
    • 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
  • Modifying the configuration
  • Inspecting the configuration
  • Store
    • Kubernetes
    • Memory
    • Postgres
Kong Mesh
2.1.x (latest)
  • Home
  • Kong Mesh
  • Documentation
  • Control Plane Configuration

Control Plane Configuration

Modifying the configuration

There are 2 ways to configure the control plane:

  • Environment variables
  • YAML configuration file

Environment variables take precedence over YAML configuration.

All possible configuration and their default values are in the kuma-cp reference doc.

Environment variables usually match the yaml path by replacing . with _, capitalizing names and prefixing with KUMA.

For example the yaml path: store.postgres.port is the environment variable: KUMA_STORE_POSTGRES_PORT.

Kubernetes (kumactl)
Kubernetes (HELM)
Universal

When using kumactl, override the configuration with the --env-var flag. For example, to configure the refresh interval for configuration of the data plane proxy, specify:

kumactl install control plane \
  --env-var KUMA_XDS_SERVER_DATAPLANE_CONFIGURATION_REFRESH_INTERVAL=5s \
  --env-var KUMA_XDS_SERVER_DATAPLANE_STATUS_FLUSH_INTERVAL=5s | kubectl apply -f -

When using helm, you can override the configuration with the envVars field. For example, to configure the refresh interval for configuration with the data plane proxy, specify:

helm install \
  --set controlPlane.envVars.KUMA_XDS_SERVER_DATAPLANE_CONFIGURATION_REFRESH_INTERVAL=5s \
  --set controlPlane.envVars.KUMA_XDS_SERVER_DATAPLANE_STATUS_FLUSH_INTERVAL=5s \
  kong-mesh kong-mesh/kong-mesh

Or you can create a values.yaml file with:

controlPlane:
  envVars:
    KUMA_XDS_SERVER_DATAPLANE_CONFIGURATION_REFRESH_INTERVAL: 5s
    KUMA_XDS_SERVER_DATAPLANE_STATUS_FLUSH_INTERVAL: 5s

and then specify it in the helm install command:

helm install -f values.yaml  kong-mesh/kong-mesh

If you have a lot of configuration you can just write them all in a YAML file and use:

helm install kong-mesh kong-mesh/kong-mesh --set-file controlPlace.config=cp-conf.yaml

The value of the configmap kong-mesh-control-plane-config is now the content of cp-conf.yaml.

First, specify your configuration in the appropriate config file, then run kuma-cp:

For example create a kuma-cp.conf.overrides.yml file with:

xdsServer:
  dataplaneConfigurationRefreshInterval: 5s
  dataplaneStatusFlushInterval: 5s

Use this configuration file in the arguments:

kuma-cp run -c kuma-cp.conf.overrides.yml

Or you can specify environment variables:

KUMA_XDS_SERVER_DATAPLANE_CONFIGURATION_REFRESH_INTERVAL=5s \
  KUMA_XDS_SERVER_DATAPLANE_STATUS_FLUSH_INTERVAL=5s \
  kuma-cp run

If you configure kuma-cp with a YAML file, make sure to provide only values that you want to override. Otherwise, upgrading Kong Mesh might be harder, because you need to keep track of your changes when replacing this file on every upgrade.

Inspecting the configuration

There are many ways to see your control plane configuration:

  • In the kuma-cp logs, the configuration is logged on startup.
  • The control plane API server has an endpoint: http://<CP_ADDRESS>:5681/config
  • The GUI exposes the configuration on the Diagnostic tab, accessible in the lower left corner.
  • In a multi-zone deployment, the zone control plane sends its configuration to the global control plane. This lets you inspect all configurations with kumactl inspect zones -oyaml or in the GUI.

Store

When Kong Mesh (kuma-cp) is up and running it needs to store its state on Universal it’s Postgres, for Kubernetes it’s leveraging Kubernetes custom resource definitions. Thus state includes the policies configured, the data plane proxy status, and so on.

Kong Mesh supports a few different types of store. You can configure the backend storage by setting the KUMA_STORE_TYPE environment variable when running the control plane.

The following backends are available:

  • memory
  • kubernetes
  • postgres

The configuration to set the store is the yaml path store.type or the environment variable KUMA_STORE_TYPE.

Kubernetes

Kong Mesh stores all the state in the underlying Kubernetes cluster.

This is only usable if the control plane is running in Kubernetes mode. You can’t manage Universal CPPs from a control plane with a Kubernetes store.

Memory

Kong Mesh stores all the state in-memory. Restarting Kong Mesh will delete all the data, and you cannot have more than one control plane instance running.

Memory is the default memory store when running in Universal mode and is only available in Universal mode.

Because the state is not persisted this store should only be used when trying things out.

Postgres

Kong Mesh stores all the state in a PostgreSQL database. This can only be used when running in Universal mode.

KUMA_STORE_TYPE=postgres \
  KUMA_STORE_POSTGRES_HOST=localhost \
  KUMA_STORE_POSTGRES_PORT=5432 \
  KUMA_STORE_POSTGRES_USER=kuma-user \
  KUMA_STORE_POSTGRES_PASSWORD=kuma-password \
  KUMA_STORE_POSTGRES_DB_NAME=kuma \
  kuma-cp run

For great availability and low maintenance cost you can use a PostgreSQL database offered by any cloud vendor.

TLS

Connection between Postgres and Kong Mesh CP should be secured with TLS.

The following modes are available to secure the connection to Postgres:

  • disable: the connection 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 mode is configured with the KUMA_STORE_POSTGRES_TLS_MODE environment variable. The CA used to verify the server’s certificate is configured with the KUMA_STORE_POSTGRES_TLS_CA_PATH environment variable.

After configuring the above security settings in Kong Mesh, we also have to configure Postgres’ pg_hba.conf file to restrict unsecured connections.

Here is an example configuration that allows only TLS connections and requires a username and password:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
hostssl all             all             0.0.0.0/0               password

You can also provide a client key and certificate for mTLS using the KUMA_STORE_POSTGRES_TLS_CERT_PATH and KUMA_STORE_POSTGRES_TLS_KEY_PATH variables. This pair can be used in conjunction with the cert auth-method described in the Postgres documentation.

Migrations

To provide easy upgrades between Kong Mesh versions there is a migration system for the Postgres DB schema.

When upgrading to a new version of Kong Mesh, run kuma-cp migrate up so the new schema is applied.

KUMA_STORE_TYPE=postgres \
  KUMA_STORE_POSTGRES_HOST=localhost \
  KUMA_STORE_POSTGRES_PORT=5432 \
  KUMA_STORE_POSTGRES_USER=kuma-user \
  KUMA_STORE_POSTGRES_PASSWORD=kuma-password \
  KUMA_STORE_POSTGRES_DB_NAME=kuma \
  kuma-cp migrate up

Kong Mesh CP at the start checks if the current DB schema is compatible with the version of Kong Mesh you are trying to run. Information about the latest migration is stored in schema_migration table.

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