Kong Mesh - Vault Policy
Vault CA Backend
The default mTLS policy in Kuma
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
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
vault mTLS mode, Kong Mesh communicates with the HashiCorp Vault PKI,
which generates the data plane proxy certificates automatically.
Kong Mesh does not retrieve private key of the CA to generate data plane proxy certificates,
which means that private key of the CA is secured by Vault and not exposed to third parties.
vault mode, you point Kong Mesh to the
Vault server and provide the appropriate credentials. Kong Mesh
uses these parameters to authenticate the control plane and generate the
data plane certificates.
When Kong Mesh is running in
vault mode, the backend communicates with Vault and ensures
that Vault’s PKI automatically issues data plane certificates and rotates them for
If Kong Mesh is configured to authenticate to Vault using a renewable token,
it will handle keeping the token renewed.
vault mTLS backend expects a configured PKI and role for generating data plane proxy certificates.
The following steps show how to configure Vault for Kong Mesh with a mesh named
default. For your environment, replace
default with the appropriate mesh name.
Step 1. Configure the Certificate Authority
Kong Mesh works with a Root CA or an Intermediate CA.
Step 2. Create a role for generating data plane proxy certificates:
vault write kmesh-pki-default/roles/dataplane-proxies \
allowed_domains="mesh" \ # use only when commonName in mTLS Vault backend is set
allow_subdomains=true \ # use only when commonName in mTLS Vault backend is set
Step 3. Create a policy to use the new role:
cat > kmesh-default-dataplane-proxies.hcl <<- EOM
capabilities = ["create", "update"]
vault policy write kmesh-default-dataplane-proxies kmesh-default-dataplane-proxies.hcl
Step 4. Create a Vault token:
vault token create -format=json -policy="kmesh-default-dataplane-proxies" | jq -r ".auth.client_token"
The output should print a Vault token that you then provide as the
conf.fromCp.auth.token value of the
kuma-cp communicates directly with Vault. To connect to
Vault, you must provide credentials in the configuration of the
mesh object of
You can authenticate with the
token or with client certificates by providing
You can provide these values inline for testing purposes only, as a path to a file on the
same host as
kuma-cp, or contained in a
secret. See the Kuma Secrets documentation.
Here’s an example of a configuration with a
Multizone and Vault
In a multizone environment, the global control plane provides the
Mesh to the zone control planes. However, you must make sure that each zone control plane communicates with Vault over the same address. This is because certificates for data plane proxies are issued from the zone control plane, not from the global control plane.
You must also make sure the global control plane communicates with Vault. When a new Vault backend is configured, Kong Mesh validates the connection by issuing a test certificate. In a multizone environment, validation is performed on the global control plane.