Kong Mesh control plane configuration

There are two ways to customize the Kong Mesh control plane configuration:

• With environment variables
• With a YAML configuration file

If both are specified, environment variables take precedence over YAML configuration.

All possible parameters 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, for the YAML path store.postgres.port, the corresponding environment variable is KUMA_STORE_POSTGRES_PORT.

The following examples show you how to apply configuration with environment variables or a YAML file, on Kubernetes or Universal.

These examples show you how to set the refresh interval, but the format applies to all Kong Mesh control plane configuration options.

Kubernetes

kumactl install control-plane \
  --set "kuma.controlPlane.envVars.KUMA_XDS_SERVER_DATAPLANE_CONFIGURATION_REFRESH_INTERVAL=5s" \
  --set "kuma.controlPlane.envVars.KUMA_XDS_SERVER_DATAPLANE_STATUS_FLUSH_INTERVAL=5s" \
  | kubectl apply -f -

# Before installing Kong Mesh with Helm, configure your local Helm repository:
# https://developer.konghq.com/mesh/2.13/production/cp-deployment/kubernetes/#helm
helm install \
  --create-namespace \
  --namespace kong-mesh-system \
  --set "kuma.controlPlane.envVars.KUMA_XDS_SERVER_DATAPLANE_CONFIGURATION_REFRESH_INTERVAL=5s" \
  --set "kuma.controlPlane.envVars.KUMA_XDS_SERVER_DATAPLANE_STATUS_FLUSH_INTERVAL=5s" \
  kong-mesh kong-mesh/kong-mesh

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

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

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

Universal

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

xdsServer:
  dataplaneConfigurationRefreshInterval: 5s
  dataplaneStatusFlushInterval: 5s

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

There are many ways to see your control plane configuration:

• In the kuma-cp logs, the configuration is logged on startup.
• Using the control plane API server /config endpoint (for example, http://YOUR_CP_ADDRESS:5681/config).
• In the UI’s Diagnostic tab.
• Using the kumactl inspect zones -o yaml command on a global control plane in a multi-zone deployment.

When the Kong Mesh control plane is up and running, it needs to store its state.

Kong Mesh supports a few different types of store. You can configure the backend storage by setting the KUMA_STORE_TYPE environment variable or store.type in the YAML configuration file when running the control plane. The following values are supported:

• kubernetes
• memory
• postgres

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 control planes from a control plane with a Kubernetes store.

Memory

Kong Mesh stores all the state in-memory. Restarting Kong Mesh deletes all the data, and you can’t 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.

Don’t use this store in production, as the state isn’t persisted.

PostgreSQL

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

To configure it, run the following command with your database details:

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

TLS

Connections between PostgreSQL and Kong Mesh control planes should be secured with TLS. You can configure the TLS mode with the KUMA_STORE_POSTGRES_TLS_MODE environment variable, or the store.postgres.tls.mode YAML path.

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

• disable: The connection is not secured with TLS. Secrets will be transmitted over network in plain text.
• verifyNone: The connection is secured but the hostname and the signing CA are not checked.
• verifyCa: The connection is secured and the certificate presented by the server is verified using the provided CA.
• verifyFull: The connection is secured, the certificate presented by the server is verified using the provided CA, and the server hostname must match the one in the certificate.

For theverifyCA and verifyFull options, you also need to configure the KUMA_STORE_POSTGRES_TLS_CA_PATH environment variable or the store.postgres.tls.capath YAML path.

After configuring the PostgreSQL TLS security settings in Kong Mesh, you also have to configure PostgreSQL’s 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, or their YAML paths. This pair can be used in conjunction with the cert authentication method. For more information, see the PostgreSQL documentation.

Migrations

To simplify upgrades to new versions, Kong Mesh provides a migration system for the PostgreSQL database schema.

When upgrading to a new version of Kong Mesh, run kuma-cp migrate up to apply the new schema:

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

When it starts, the Kong Mesh control plane checks if the current database 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.