Managing secrets in Kong Mesh

The Secret resource enables users to store sensitive data. This includes anything a user considers non-public, such as:

• TLS keys
• Tokens
• Passwords

Secrets belong to a specific Mesh resource, and can’t be shared across different Meshes. Policies use secrets at runtime.

Kong Mesh leverages Secret resources internally for certain operations, for example when storing auto-generated certificates and keys when Mutual TLS is enabled.

How you store secrets in the Secrets resource depends on if you’re using Kubernetes or Universal for your environment.

echo "apiVersion: v1
kind: Secret
metadata:
  name: sample-secret
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
data:
  value: dGVzdAo=
type: system.kuma.io/secret" | kubectl apply -f -

kubectl get secrets -n kong-mesh-system --field-selector='type=system.kuma.io/secret'

echo "type: Secret
mesh: default
name: sample-secret
data: dGVzdAo=" | kumactl apply -f -

The data field of a Kong Mesh secret is a Base64-encoded value. Use the base64 command in Linux or macOS to encode any value in Base64:

# Base64 encode a file
cat cert.pem | base64

# or Base64 encode a string
echo "value" | base64

Kong Mesh provides two types of secrets:

• Mesh-scoped
• Global

Mesh-scoped secrets

Mesh-scoped secrets are bound to a given mesh. This is the only type of secret that can be used in mesh policies like the Provided CA or TLS setting in External Service.

apiVersion: v1
kind: Secret
metadata:
  name: sample-secret
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
data:
  value: dGVzdAo=
type: system.kuma.io/secret

type: Secret
name: sample-secret
mesh: default
data: dGVzdAo=

Global secrets

Global secrets are not bound to a given mesh and can’t be used in mesh policies. Global secrets are used for internal purposes, to store zone tokens or user token signing keys for example.

apiVersion: v1
kind: Secret
metadata:
  name: sample-secret
  namespace: kong-mesh-system
data:
  value: dGVzdAo=
type: system.kuma.io/global-secret

type: GlobalSecret
name: sample-global-secret
data: dGVzdAo=

Secrets are synced from the global control plane to the zones CPs, but not the other way around as this would risk exposing sensitive information.

v2.10+ If there’s a name conflict between a secret on the global CP and a secret on a zone CP, the secret is not overwritten and a warning will appear in the logs. In versions prior to 2.10, secrets can’t be created on a zone control plane.

Here is an example of how to use a Kong Mesh Secret with a provided Mutual TLS backend.

The examples below assume that the Secret object has already been created:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  mtls:
    backends:
      - name: ca-1
        type: provided
        config:
          cert:
            secret: my-cert # name of the Kubernetes secret
          key:
            secret: my-key # name of the Kubernetes secret

type: Mesh
name: default
mtls:
  backends:
    - name: ca-1
      type: provided
      config:
        cert:
          secret: my-cert # name of the Kong Mesh secret
        key:
          secret: my-key # name of the Kong Mesh secret