You are browsing documentation for an older version. See the latest documentation here.

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 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.

Vault mode

In 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.

In 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 each proxy.

Configure Vault

The vault mTLS backend expects a kuma-pki-${MESH_NAME} PKI already configured in Vault. For example, the PKI path for a mesh named default is kuma-pki-default.

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.

vault secrets enable -path=kuma-pki-default pki

vault secrets tune -max-lease-ttl=87600h kuma-pki-default

vault write -field=certificate kuma-pki-default/root/generate/internal \
  common_name="Kuma Mesh Default" \
  uri_sans="spiffe://default" \
  ttl=87600h

vault secrets enable pki

vault secrets tune -max-lease-ttl=87600h pki

vault write -field=certificate pki/root/generate/internal \
  common_name="Organization CA" \
  ttl=87600h > ca.pem

vault secrets enable -path=kuma-pki-default pki

vault write -format=json kuma-pki-default/intermediate/generate/internal \
    common_name="Kuma Mesh Default" \
    uri_sans="spiffe://default" \
    | jq -r '.data.csr' > pki_intermediate.csr

vault write -format=json pki/root/sign-intermediate csr=@pki_intermediate.csr \
  format=pem_bundle \
  ttl="43800h" \
  | jq -r '.data.certificate' > intermediate.cert.pem

cat intermediate.cert.pem > bundle.pem
echo "" >> bundle.pem
cat ca.pem >> bundle.pem
vault write kuma-pki-default/intermediate/set-signed certificate=@bundle.pem

Step 2. Create a role for generating data plane proxy certificates:

vault write kuma-pki-default/roles/dataplanes \
  allowed_uri_sans="spiffe://default/*,kuma://*" \
  key_usage="KeyUsageKeyEncipherment,KeyUsageKeyAgreement,KeyUsageDigitalSignature" \
  ext_key_usage="ExtKeyUsageServerAuth,ExtKeyUsageClientAuth" \
  client_flag=true \
  require_cn=false \
  basic_constraints_valid_for_non_ca=true \
  max_ttl="720h" \
  ttl="720h"

Step 3. Create a policy to use the new role:

cat > kuma-default-dataplanes.hcl <<- EOM
path "/kuma-pki-default/issue/dataplanes"
{
  capabilities = ["create", "update"]
}
EOM
vault policy write kuma-default-dataplanes kuma-default-dataplanes.hcl

Step 4. Create a Vault token:

vault token create -format=json -policy="kuma-default-dataplanes" | 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 Mesh object.

Configure Mesh

kuma-cp communicates directly with Vault. To connect to Vault, you must provide credentials in the configuration of the mesh object of kuma-cp.

You can authenticate with the token or with client certificates by providing clientKey and clientCert.

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 vault-backed CA:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  mtls:
    enabledBackend: vault-1
    backends:
      - name: vault-1
        type: vault
        dpCert:
          rotation:
            expiration: 1d # must be lower than max_ttl in Vault role
        conf:
          fromCp:
            address: https://vault.8200
            agentAddress: "" # optional
            namespace: "" # optional
            tls:
              caCert:
                secret: sec-1
              skipVerify: false # if set to true, caCert is optional. Set to true only for development
              serverName: "" # verify sever name
            auth: # only one auth options is allowed so it's either "token" or "tls"
              token:
                secret: token-1  # can be file, secret or inlineString
              tls:
                clientKey:
                  secret: sec-2  # can be file, secret or inline
                clientCert:
                  file: /tmp/cert.pem # can be file, secret or inlineString

type: Mesh
name: default
mtls:
  enabledBackend: vault-1
  backends:
  - name: vault-1
    type: vault
    dpCert:
      rotation:
        expiration: 24h # must be lower than max_ttl in Vault role
    conf:
      fromCp:
        address: https://vault.8200
        agentAddress: "" # optional
        namespace: "" # optional
        tls:
          caCert:
            secret: sec-1
          skipVerify: false # if set to true, caCert is optional. Set to true only for development
          serverName: "" # verify sever name
        auth: # only one auth options is allowed so it's either "token" or "tls"
          token:
            secret: token-1  # can be file, secret or inlineString
          tls:
            clientKey:
              secret: sec-2  # can be file, secret or inlineString
            clientCert:
              file: /tmp/cert.pem # can be file, secret or inline