Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.2.x (latest)
  • 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

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this pageOn this page
  • Access to the Secret HTTP API
  • Mesh-scoped Secrets
  • Global-scoped Secrets
Kong Mesh
2.1.x
  • Home
  • Kong Mesh
  • Security
  • Manage secrets
You are browsing documentation for an outdated version. See the latest documentation here.

Manage secrets

The Secret resource enables users to store sensitive data. Sensitive information is anything a user considers non-public, e.g.:

  • TLS keys
  • tokens
  • passwords

Secrets belong to a specific Mesh resource, and cannot 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.

Kubernetes
Universal

On Kubernetes, Kong Mesh under the hood leverages the native Kubernetes Secret resource to store sensitive information.

Kong Mesh secrets are stored in the same namespace as the Control Plane with type set to system.kuma.io/secret:

apiVersion: v1
kind: Secret
metadata:
  name: sample-secret
  namespace: kong-mesh-system # Kong Mesh will only manage secrets in the same namespace as the CP
  labels:
    kuma.io/mesh: default # specify the Mesh scope of the secret
data:
  value: dGVzdAo= # Base64 encoded
type: system.kuma.io/secret # Kong Mesh will only manage secrets of this type

Use kubectl to manage secrets like any other Kubernetes resource.

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'
# NAME            TYPE                    DATA   AGE
# sample-secret   system.kuma.io/secret   1      3m12s

Kubernetes Secrets are identified with the name + namespace format, therefore it is not possible to have a Secret with the same name in multiple meshes. Multiple Meshes always belong to one Kong Mesh CP that always runs in one Namespace.

In order to reassign a Secret from one Mesh to another Mesh you need to delete the Secret resource and create it in another Mesh.

A Secret is a simple resource that stores specific data:

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

Use kumactl to manage any Secret the same way you would do for other resources:

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

Access to the Secret HTTP API

Secret API requires authentication. Consult Accessing Admin Server from a different machine for how to configure remote access.

Scope of the Secret

Kong Mesh provides two types of Secrets.

Mesh-scoped Secrets

Mesh-scoped Secrets are bound to a given Mesh. Only this kind of Secrets can be used in Mesh Policies like Provided CA or TLS setting in External Service.

Kubernetes
Universal
apiVersion: v1
kind: Secret
metadata:
  name: sample-secret
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default # specify the Mesh scope of the secret
data:
  value: dGVzdAo=
type: system.kuma.io/secret
type: Secret
name: sample-secret
mesh: default # specify the Mesh scope of the secret
data: dGVzdAo=

Global-scoped Secrets

Global-scoped Secrets are not bound to a given Mesh and cannot be used in Mesh Policies. Global-scoped Secrets are used for internal purposes. You can manage them just like the regular secrets using kumactl or kubectl.

Kubernetes
Universal

Notice that the type is different and kuma.io/mesh label is not present.

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

Notice that the type is different and mesh field is not present.

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

Usage

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

The examples below assumes that the Secret object has already been created beforehand.

Universal
Kubernetes
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
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
Thank you for your feedback.
Was this page useful?
  • 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