A secret is any sensitive piece of information required for API gateway
operations. Secrets may be part of the core Kong Gateway configuration,
they may be used in plugins, or they might be part of configuration associated
with APIs serviced by the gateway.
Some of the most common types of secrets used by Kong Gateway include:
- Data store usernames and passwords, used with PostgreSQL and Redis
- Private X.509 certificates
- API keys
- Sensitive plugin configuration fields, generally used for authentication,
hashing, signing, or encryption.
Kong Gateway lets you store certain values in a vault.
By storing sensitive values as secrets, you ensure that they are not
visible in plaintext throughout the platform, in places such as
in declarative configuration files, logs, or in the Kong Manager UI. Instead,
you can reference each secret with a
For example, the following reference resolves to the environment variable
In this way, secrets management becomes centralized.
A secret reference points to a string value. No other data types are currently supported.
The vault backend may store multiple related secrets inside an object, but the reference
should always point to a key that resolves to a string value. For example, the following reference:
Would point to a secret object called
pg inside a HashiCorp Vault, which may return the following value:
Kong receives the payload and extracts the
"username" value of
"john" for the secret reference of
What can be stored as a secret?
Most of the Kong configuration values
can be stored as a secret, such as
Limitation: Kong Gateway doesn’t currently support storing certificate key content into vaults or environment variables for
kong.conf settings that use file paths. For example, ssl_cert_key configures a certificate key
file path which can’t be stored as a reference.
The Kong license, usually configured with
KONG_LICENSE_DATA environment variable, can be stored as a secret.
The Kong Admin API certificate object
can be stored as a secret.
The following plugins have fields that can be stored as secrets in a
vault backend. These fields are labelled as
referenceable. See the
documentation for each plugin to identify the referenceable fields:
Kong Gateway supports the following vault backends:
- Environment variables
- AWS Secrets Manager
- GCP Secrets Manager
- HashiCorp Vault
See the backends overview
for more information about each option.
For further information on secrets management, see the following topics: