Secrets

Kuma provides a built-in interface to store sensitive information such as TLS keys and tokens that can be used later on by any policy at runtime. This functionality is being implemented by introducing a Secret resource.

Secrets belong to a specific Mesh resource, and cannot be shared across different Meshes.

Kuma will also leverage Secret resources internally for certain operations, for example when storing auto-generated certificates and keys when Mutual TLS is enabled.

Universal

A Secret is a simple resource that stores specific data:

  1. type: Secret
  2. name: sample-secret
  3. mesh: default
  4. data: dGVzdAo= # bytes encoded in Base64

You can use kumactl to manage any Secret like you would do for other resources:

  1. $ echo "type: Secret
  2. mesh: default
  3. name: sample-secret
  4. data: dGVzdAo=" | kumactl apply -f -

Access to the Secret HTTP API

This API is exposed on the Admin Server which means that by default it is only available on the same machine as the Control Plane. Consult Accessing Admin Server from a different machine how to configure remote access.

Kubernetes

On Kubernetes, Kuma under the hood leverages the native Kubernetes SecretSecrets - 图1 resource to store sensitive information.

Kuma secrets are stored in the same namespace as the Control Plane with type valued as system.kuma.io/secret:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: sample-secret
  5.   namespace: kuma-system # Kuma will only manage secrets in the same namespace as the CP
  6.   labels:
  7.     kuma.io/mesh: default # specify the Mesh scope of the secret 
  8. data:
  9.   value: dGVzdAo= # bytes encoded in Base64
  10. type: system.kuma.io/secret # Kuma will only manage secrets of this type

Use kubectl to manage secrets like any other Kubernetes resource.

  1. $ echo "apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: sample-secret
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default 
  8. data:
  9.   value: dGVzdAo=
  10. type: system.kuma.io/secret" | kubectl apply -f -
  12. $ kubectl get secrets -n kuma-system --field-selector='type=system.kuma.io/secret'
  13. NAME            TYPE                    DATA   AGE
  14. sample-secret   system.kuma.io/secret   1      3m12s

Like any other Kuma resources, if kuma.io/mesh is not specified then the Secret will automatically belong to the default Mesh.

Kubernetes Secrets always belongs to a specific Mesh resource and they are internally they are identified with the name + namespace format, therefore it is not possible to have a Secret with the same name in multiple meshes (since multiple Meshes always belong to one Kuma CP that always runs in one Namespace).

In order to reassign a Secret to another Mesh you need to delete the Secret resource and apply it again.

The data field of a Kuma Secret should always be a Base64 encoded value. You can use the base64 command in Linux or macOS to encode any value in Base64:

  1. # Base64 encode a file
  2. $ cat cert.pem | base64
  4. # or Base64 encode a string
  5. $ echo "value" | base64

Usage

Here is example of how you can use a Kuma Secret with a provided Mutual TLS backend.

The examples below assume that the Secret object has already been created before-hand.

Universal

  1. type: Mesh
  2. name: default
  3. mtls:
  4.   backends:
  5.   - name: ca-1
  6.     type: provided
  7.     config:
  8.       cert:
  9.         secret: my-cert # name of the Kuma Secret
  10.       key:
  11.         secret: my-key # name of the Kuma Secret

Kubernetes

  1. apiVersion: kuma.io/v1alpha1
  2. kind: Mesh
  3. metadata:
  4.   name: default
  5. spec:
  6.   mtls:
  7.     backends:
  8.     - name: ca-1
  9.       type: provided
  10.       config:
  11.         cert:
  12.           secret: my-cert # name of the Kubernetes Secret
  13.         key:
  14.           secret: my-key # name of the Kubernetes Secret