Vaults

Uses: Kong Gateway Admin API decK KIC Konnect API Terraform

What is a Vault?

Vaults allow you to securely store and then reference secrets from within other entities. This ensures that secrets aren’t visible in plaintext throughout the platform, in places such as kong.conf, declarative configuration files, logs, or the UI.

For example, you could store a certificate and a key in a Vault, then reference them from a Certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure.

How do I add secrets to a Vault?

You can add secrets to Vaults in one of the following ways:

  • Environment variables
  • Konnect Config Store
  • Supported third-party backend vault

What can be stored as a secret?

You can store and reference the following as secrets in a Vault:

Konnect Config Store limitations:

  • 1: You can’t reference secrets stored in a Konnect Config Store Vault in kong.conf because Konnect resolves the secret after Kong Gateway connects to the Control Plane. For this same reason, you can’t use Konnect Config Store secrets directly in Lua code via the Kong PDK, for example.
  • 2: In Konnect, the Kong Gateway license is managed and stored by Konnect, and doesn’t need to be stored manually in any Vault.

Referenceable plugin fields

The following plugin fields can be stored and referenced as secrets:

Supported Vault backends

Each vault has its own required configuration. You can provide this configuration by creating a Vault entity, or by configuring specific environment variables before starting Kong Gateway.

For more information, choose a Vault below to see the specific configuration required.

Backend Kong Gateway OSS Kong Gateway Enterprise Konnect supported
Environment variable
Konnect Config Store
AWS Secrets Manager
Azure Key Vaults
Google Cloud Secret
HashiCorp Vault
CyberArk Conjur v3.11+

How do I reference secrets stored in a Vault?

When you want to use a secret stored in a Vault, you can reference the secret with a vault reference. You can use the vault reference in places such as kong.conf, declarative configuration files, logs, or in the UI.

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:

{vault://hcv/pg/username}
Copied to clipboard!

Would point to a secret object called pg inside a HashiCorp Vault, which may return the following value:

{
  "username": "john",
  "password": "doe"
}
Copied to clipboard!

Kong Gateway receives the payload and extracts the "username" value of "john" for the secret reference of {vault://hcv/pg/username}.

Vault references must be used for the whole referenced value. Imagine that you’re calling a upstream service with the authentication token ABC123:

Works Configuration Value Vault Value
Bearer {vault://hcv/myservice-auth-token} ABC123
{vault://hcv/myservice-auth-token} Bearer ABC123

Secret rotation in Vaults

By default, Kong Gateway automatically refreshes secrets once every minute in the background. You can also configure how often Kong Gateway refreshes secrets using the Vault entity configuration.

There are two types of refresh configuration available:

  • Refresh periodically using TTLs: For example, check for a new TLS certificate once per day.
  • Refresh on failure: For example, on a database authentication failure, check if the secrets were updated, and try again.

For more information, see Secret management.

Schema

The Vault entity can only be used once the database is initialized. Secrets for values that are used before the database is initialized can’t make use of the Vaults entity.

Vault provider-specific configuration parameters

When you set up a Vault, each provider has specific parameters that you can or must configure to integrate the Vault entity with a provider.

Set up a Vault

Store secrets as environment variables

You can store secrets as environment variables instead of configuring a Vault entity or third-party backend vault.

Use case

Environment variable example

Secret reference example

Single secret value export MY_SECRET_VALUE=example-secret {vault://env/my-secret-value}
Multiple secrets (flat JSON string) export PG_CREDS='{"username":"user", "password":"pass"}' {vault://env/pg-creds/username}

{vault://env/pg-creds/password}

FAQs

Did this doc help?

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!