Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Mesh
1.4.x
  • Home icon
  • Kong Mesh
  • Features
  • Kong Mesh - Vault Policy
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.4.x (latest)
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 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
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Vault CA Backend
  • Vault mode
    • Configure Vault
    • Configure Mesh
  • Multizone and Vault
You are browsing documentation for an outdated 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 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.

Root CA
Intermediate CA

Create a new PKI for the default Mesh called kmesh-pki-default:

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

Generate a new Root Certificate Authority for the default Mesh:

vault secrets tune -max-lease-ttl=87600h kmesh-pki-default
vault write -field=certificate kmesh-pki-default/root/generate/internal \
  common_name="Kong Mesh Default" \
  uri_sans="spiffe://default" \
  ttl=87600h

Create a new Root Certificate Authority and save it to a file called ca.pem:

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

You can also use your current Root CA, retrieve the PEM-encoded certificate, and save it to ca.pem.

Create a new PKI for the default Mesh:

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

Generate the Intermediate CA for the default Mesh:

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

Sign the Intermediate CA with the Root CA. Make sure to pass the right path for the PKI that has the Root CA. In this example, the path value is pki:

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

Set the certificate of signed Intermediate CA to the default Mesh PKI. You must include the public certificate of the Root CA so that data plane proxies can verify the certificates:

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

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

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

Note: Use the allowed_domains and allow_subdomains parameters only when commonName is set in the mTLS Vault backend.

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

cat > kmesh-default-dataplane-proxies.hcl <<- EOM
path "/kmesh-pki-default/issue/dataplane-proxies"
{
  capabilities = ["create", "update"]
}
EOM
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 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:

Kubernetes
Universal
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
            pki: kmesh-pki-default # name of the configured PKI
            role: dataplane-proxies # name of the role that will be used to generate data plane proxy certificates
            commonName: '{{ tag "kuma.io/service" }}.mesh' # optional. If set, then commonName is added to the certificate. You can use "tag" directive to pick a tag which will be base for commonName.
            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

Apply the configuration with kubectl apply -f [..].

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
        pki: kmesh-pki-default # name of the configured PKI
        role: dataplane-proxies # name of the role that will be used to generate data plane proxy certificates
        commonName: '{{ tag "kuma.io/service" }}.mesh' # optional. If set, then commonName is added to the certificate. You can use "tag" directive to pick a tag which will be base for commonName.
        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

Apply the configuration with kumactl apply -f [..], or with the HTTP API.

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.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • 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