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
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:
description: ENV vault for secrets
|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.
|An optional description for your vault.
|The type of vault. Accepts one of:
|The reference prefix. You need this prefix to access secrets stored in this vault. For example,
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:
- id: B0DBE8FD-E5E6-414A-A0DC-0160665620AB
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.
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:
description: ENV vault for secrets
When updating the vault,
deck dump the configuration with the
deck dump --select-tag env-vault
Make your changes to the vault, then push it back up with
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.