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
  • 1.19.x (latest)
  • 1.18.x
  • 1.17.x
  • 1.16.x
  • 1.15.x
  • 1.14.x
  • 1.13.x
  • 1.12.x
  • 1.11.x
  • 1.10.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • pre-1.7
    • Terminology
    • Architecture
    • Compatibility Promise
    • Getting Started with decK
    • Backup and Restore
    • Upgrade to Kong Gateway 3.x
    • Configuration as Code and GitOps
    • Distributed Configuration
    • Best Practices
    • Using decK with Kong Gateway (Enterprise)
    • Using decK with Konnect
    • Run decK with Docker
    • Using Multiple Files to Store Configuration
    • De-duplicate Plugin Configuration
    • Set Up Object Defaults
      • Overview
      • Secret Management with decK
      • Using Environment Variables with decK
    • Entities Managed by decK
      • deck completion
      • deck convert
      • deck diff
      • deck dump
      • deck ping
      • deck reset
      • deck sync
      • deck validate
      • deck version

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Configure a secret vault
  • Store and reference secrets
  • Best practices
    • Manage vaults with distributed configuration
decK
1.16.x
  • Home
  • decK
  • Guides
  • Vaults
  • Secret Management with decK
You are browsing documentation for an outdated version. See the latest documentation here.

Secret Management with decK

decK supports secret references for encoded values in Kong Gateway. You can store your secrets in a vault backend, then reference them in your declarative configuration files.

You can use secrets to store sensitive data, such as credentials.

See Secrets Management in Kong Gateway for a full list of values that can be stored as secrets.

For storing configuration values as environment variables on the node running decK, see Using Environment Variables with decK. The reference format for secrets is not the same as references for environment variables used by decK.

Configure a secret vault

Set up a secret vault using the Kong Gateway vaults entity.

For example, add the following snippet to your declarative configuration file (kong.yaml by default) to set up a vault using environment variables as the backend, configure a prefix for the vault, and a prefix for the reference:

_format_version: "3.0"
vaults:
- config:
    prefix: MY_SECRET_
  description: ENV vault for secrets
  name: env
  prefix: my-env-vault
Key Description
vaults.config Stores the configuration for a particular vault. The configuration values required depend on the vault that you are using. In this example, the vaults.config.prefix value configures the prefix for the environment variable that the value will be stored in. See the individual vault backends to find the required configuration values for your particular vault type.
vaults.description An optional description for your vault.
vaults.name The type of vault. Accepts one of: env, gcp, aws, or hcv.
vaults.prefix The reference prefix. You need this prefix to access secrets stored in this vault. For example, {vault://my-env-vault/<some-secret>}.

Kong Gateway also supports HashiCorp Vault, GCP, and AWS as vault backends.

Important: Manage your vault configuration separately from other Kong Gateway entities. See Best Practices in this topic for more information.

Store and reference secrets

Store your sensitive values as secrets on the node running the Kong Gateway instance:

export MY_SECRET_CERT="<cert data>" \
export MY_SECRET_KEY="<key data>"

Now you can reference the secret in subsequent configurations:

certificates:
- id: B0DBE8FD-E5E6-414A-A0DC-0160665620AB
  cert: "{vault://my-env-vault/cert}"
  key: "{vault://my-env-vault/key}"

Important: If a vault reference changes, it can cause Kong Gateway to not function correctly. If changing references, make sure to update both the vault configuration and all places that the reference is used in.

Best practices

When managing vaults with declarative configuration, you need to take certain precautions. For larger teams with many contributors, or organizations with multiple teams, we recommend splitting vault configuration and managing it separately.

Why split out vault configuration?

  • Vault are closer to infrastructure than other Kong Gateway configurations. Separation of routing policies from infrastructure-specific configurations helps keep configuration organized.
  • Vaults may be shared across teams. In this case, one specific team shouldn’t control the vault’s configuration. One team changing the vault a can have disastrous impact on another team.
  • If a vault is deleted while in use – that is, if there are still references to secrets in a vault in configuration – it can lead to total loss of proxy capabilities. Those secrets would be unrecoverable.

How should I manage my vault configuration with decK?

To keep your environment secure and avoid taking down your proxies by accident, make sure to:

  • Manage vaults with distributed configuration via tags.
  • Use a separate RBAC role, user, and token to manage vaults. Don’t use a generic admin user.
  • Set up a separate CI pipeline for vaults.

Manage vaults with distributed configuration

Avoid mixing vault configuration with other Kong Gateway entities. Instead, manage vaults with distributed configuration via tags.

Tag your vault in the declarative configuration file:

_format_version: "3.0"
vaults:
- config:
    prefix: MY_SECRET_
  description: ENV vault for secrets
  name: env
  prefix: my-env-vault
  tags:
    - env-vault

When updating the vault, deck dump the configuration with the --select-tag flag:

deck dump --select-tag env-vault

Make your changes to the vault, then push it back up with deck sync. You don’t need to specify --select-tag in this case, as decK recognizes the tag in the declarative configuration file that you’re syncing and updates those entities accordingly.

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