このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Vault Policy
Vault CA Backend
The default mTLS policy in Kong Mesh 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. -
acmpca
: Kong Mesh generates data plane certificates using Amazon Certificate Manager Private CA. -
certmanager
: Kong Mesh generates data plane certificates using Kubernetes cert-manager certificate controller.
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.
If Kong Mesh is configured to authenticate to Vault using a renewable token, it will handle keeping the token renewed.
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.
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
andallow_subdomains
parameters only whencommonName
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. Configure authentication method:
To authorize Kong Mesh to vault using a token, generate the following orphan token and pass it to the mesh:
vault token create -type=service -orphan -format=json -policy="kmesh-default-dataplane-proxies" | jq -r ".auth.client_token"
We suggest using an orphan token to avoid surprising behavior around expiration in token hierarchies.
You need root/sudo permissions to execute the previous command.
The output should print a Vault token that you then provide as the conf.fromCp.auth.token
value of the Mesh
object.
Note: There are some failure modes where the
vault
CLI still returns a token even though an error was encountered and the token is invalid. For example, if the policy creation fails in the previous step, then thevault token create
command both returns a token and exposes an error. In such situations, usingjq
to parse the output hides the error message provided in thevault
CLI output. Manually parse the output instead of usingjq
so that the full output of thevault
CLI command is available.
Kong Mesh also supports AWS Instance Role authentication to Vault. Vault must be configured to accept EC2 or IAM role authentication. See Vault documentation for details. With Vault configured, select AWS authentication in the Mesh
object by setting conf.fromCp.auth.aws
. Kong Mesh will authenticate using the instance or IRSA role available within the environment.
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
, with client certificates by providing clientKey
and clientCert
, or by AWS role-based authentication.
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
. When using a secret
, it should be a
mesh-scoped secret.
On Kubernetes, this mesh-scoped secret should be stored
in the system namespace (kong-mesh-system
by default) and should be configured as type: system.kuma.io/secret
.
Here’s an example of a configuration with a vault
-backed CA:
Apply the configuration with kumactl apply -f [..]
.
If you’re running in Universal mode, you can also use the HTTP API to apply configuration.
Common name
Kong Mesh uses Service Alternative Name with spiffe://
format to verify secure connection between services. In this case, the common name in the certificate is not used.
You may need to set a common name in the certificate, for compliance reasons. To do this, set the commonName
field in the Vault mTLS backend configuration.
The value contains the template that will be used to generate the name.
For example, assuming that the template is '{{ tag "kuma.io/service" }}.mesh'
, a data plane proxy with kuma.io/service: backend
tag will receive a certificate with the backend.mesh
common name.
You can also use the replace
function to replace _
with -
. For example, '{{ tag "kuma.io/service" | replace "_" "-" }}.mesh'
changes the common name of kuma.io/service: my_backend
from my_backend.mesh
to my-backend.mesh
.
Multi-zone and Vault
In a multi-zone 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 multi-zone environment, validation is performed on the global control plane.