AWS Secrets Manager

AWS Secrets Manager can be configured in multiple ways. The current version of Kong Gateway’s implementation only supports configuring AWS Secrets Manager via environment variables.

You can further customize the vault object by configuring a vaults entity in Kong Gateway.

AWS Secrets Manager configuration

Configure the following environment variables on your Kong Gateway data plane:

export AWS_ACCESS_KEY_ID=<access_key_id>
export AWS_SECRET_ACCESS_KEY=<secrets_access_key>
export AWS_REGION=<aws-region>
export AWS_SESSION_TOKEN=<token>

The region used by default with references can also be specified with the following environment variable on your control plane:

export KONG_VAULT_AWS_REGION=<aws-region>

Examples

For example, an AWS Secrets Manager Secret with the name secret-name may have multiple key=value pairs:

{
  "foo": "bar",
  "snip": "snap"
}

Access these secrets from secret-name like this:

{vault://aws/secret-name/foo}
{vault://aws/secret-name/snip}

Configuration via vaults entity

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.

Admin API

Declarative configuration

curl -i -X PUT http://HOSTNAME:8001/vaults/aws-sm-vault  \
  --data name=aws \
  --data description="Storing secrets in AWS Secrets Manager" \
  --data config.region="us-east-1"

Result:

{
    "config": {
        "region": "us-east-1"
    },
    "created_at": 1644942689,
    "description": "Storing secrets in AWS Secrets Manager",
    "id": "2911e119-ee1f-42af-a114-67061c3831e5",
    "name": "aws",
    "prefix": "aws-sm-vault",
    "tags": null,
    "updated_at": 1644942689
}

Secrets management is supported in decK 1.16 and later.

Add the following snippet into your declarative configuration file:

_format_version: "3.0"
vaults:
- config:
    region: us-east-1
  description: Storing secrets in AWS Secrets Manager
  name: aws
  prefix: aws-sm-vault

With the Vault entity in place, you can now reference the secrets. This allows you to drop the AWS_REGION environment variable.

{vault://aws-sm-vault/secret-name/foo}
{vault://aws-sm-vault/secret-name/snip}

Secrets in different regions

You can create multiple entities, which lets you have secrets in different regions:

curl -X PUT http://HOSTNAME:8001/vaults/aws-eu-central-vault -d name=aws -d config.region="eu-central-1"
curl -X PUT http://HOSTNAME:8001/vaults/aws-us-west-vault -d name=aws -d config.region="us-west-1"

This lets you source secrets from different regions:

{vault://aws-eu-central-vault/secret-name/foo}
{vault://aws-us-west-vault/secret-name/snip}

Vault configuration options

Use the following configuration options to configure the vaults entity through any of the supported tools:

Admin API
Declarative configuration
Kong Manager
Konnect

Configuration options for an AWS Secrets Manager vault in Kong Gateway:

Parameter	Field name	Description
`vaults.config.region`	AWS region	The AWS region your vault is located in.
`vaults.config.ttl`	TTL	Time-to-live (in seconds) of a secret from the vault when it’s cached. The special value of 0 means “no rotation” and it’s the default. When using non-zero values, it is recommended that they’re at least 1 minute.
`vaults.config.neg_ttl`	Negative TTL	Time-to-live (in seconds) of a vault miss (no secret). Negatively cached secrets will remain valid until `neg_ttl` is reached, after which Kong will attempt to refresh the secret again. The default value for `neg_ttl` is 0, meaning no negative caching occurs.
`vaults.config.resurrect_ttl`	Resurrect TTL	Time (in seconds) for how long secrets will remain in use after they are expired (`config.ttl` is over). This is useful when a vault becomes unreachable, or when a secret is deleted from the Vault and isn’t replaced immediately. On this both cases, the Gateway will keep trying to refresh the secret for `resurrect_ttl` seconds. After that, it will stop trying to refresh. We recommend assigning a sufficiently high value to this configuration option to ensure a seamless transition in case there are unexpected issues with the Vault. The default value for `resurrect_ttl` is 1e8 seconds, which is about 3 years.

Common options:

Parameter	Field name	Description
`vaults.description` optional	Description	An optional description for your vault.
`vaults.name`	Name	The type of vault. Accepts one of: `env`, `gcp`, `aws`, or `hcv`. Set `aws` for AWS Secrets Manager.
`vaults.prefix`	Prefix	The reference prefix. You need this prefix to access secrets stored in this vault. For example, `{vault://aws-sm-vault/<some-secret>}`.