Store the Kong Gateway database credentials with AWS Secrets Manager

Uses: Kong Gateway

Deployment Platform:

Prerequisites

AWS configuration

This tutorial requires:

An AWS subscription with access to AWS Secrets Manager and the following permissions:
- secretsmanager:CreateSecret
- secretsmanager:PutSecretValue
- secretsmanager:GetSecretValue
AWS CLI installed

You’ll also need the following authentication information to connect your AWS Secrets Manager with Kong Gateway:

Your access key ID
Your secret access key
Your session token
Your AWS region, us-east-1 in this example

For this example, you can get temporary credentials from the AWS portal.

Create environment variables to store these credentials:

export AWS_ACCESS_KEY_ID=your-aws-access-key-id
export AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
export AWS_SESSION_TOKEN=your-aws-session-token
export AWS_REGION="us-east-1"

Create a Docker network

First, create a Docker network:

docker network create kong-net

The Docker network will be used for communication between Kong Gateway and the database.

Run the database

Create the kong-database container for the PostgreSQL database:

docker run -d --name kong-database \
 --network=kong-net \
 -p 5432:5432 \
 -e "POSTGRES_USER=admin" \
 -e "POSTGRES_PASSWORD=password" \
 postgres:9.6

The username and password specified in this command are the PostgreSQL master credentials.

Create environment variables

Define the username and password to use to connect Kong Gateway to the database and store them in environment variables:

export KONG_PG_USER=kong
export KONG_PG_PASSWORD=KongPassword

Create a database user

Create a user in the PostgreSQL container, using the credentials defined in the previous step:

docker exec -it kong-database psql -U admin -c \
 "CREATE USER ${KONG_PG_USER} WITH PASSWORD '${KONG_PG_PASSWORD}'"

Create a database

Create a database named kong, with the user you created as the owner:

docker exec -it kong-database psql -U admin -c "CREATE DATABASE kong OWNER ${KONG_PG_USER};"

Create a secret in AWS Secrets Manager

Use the AWS CLI to create a new secret named kong-gateway-database containing the username and password you defined:

aws secretsmanager create-secret --name kong-gateway-database \
 --description "Kong GW Database credentials" \
 --secret-string '{"pg_user":"'${KONG_PG_USER}'","pg_password":"'${KONG_PG_PASSWORD}'"}'

Initialize the database

Use the kong migrations bootstrap command to initialize the database:

docker run --rm \
 --network=kong-net \
 -e "KONG_DATABASE=postgres" \
 -e "KONG_PG_HOST=kong-database" \
 -e KONG_PG_USER \
 -e KONG_PG_PASSWORD \
 kong/kong-gateway:latest kong migrations bootstrap

Note: kong migrations does not support secrets management, so this step passes the database credentials with environment variables.

Start Kong Gateway

Create the Kong Gateway container with your AWS credentials and the vault references in the environment:

docker run -d --name kong-gateway \
 --network=kong-net \
 -e "KONG_DATABASE=postgres" \
 -e "KONG_PG_HOST=kong-database" \
 -e AWS_ACCESS_KEY_ID \
 -e AWS_SECRET_ACCESS_KEY \
 -e AWS_REGION \
 -e AWS_SESSION_TOKEN \
 -e "KONG_PG_USER={vault://aws/kong-gateway-database/pg_user}" \
 -e "KONG_PG_PASSWORD={vault://aws/kong-gateway-database/pg_password}" \
 -e KONG_LICENSE_DATA \
 kong/kong-gateway:latest

This command returns the ID of the Kong Gateway container.

Validate

To verify that everything worked as expected, you can check its status with this command:

docker container ls

If the kong-gateway container is running, that means it successfully connected to the database using the credentials in the vault.

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

My secret in AWS Secret Manager has a / backslash in the secret name. How do I reference this secret in Kong Gateway?

The slash symbol (/) is a valid character for the secret name in AWS Secrets Manager. If you want to reference a secret name that starts with a slash or has two consecutive slashes, transform one of the slashes in the name into URL-encoded format. For example:

A secret named /secret/key should be referenced as {vault://aws/%2Fsecret/key}
A secret named secret/path//aaa/key should be referenced as {vault://aws/secret/path/%2Faaa/key}

Since Kong Gateway tries to resolve the secret reference as a valid URL, using a slash instead of a URL-encoded slash will result in unexpected secret name fetching.

I have secrets stored in multiple AWS Secret Manager regions, how do I reference those secrets in Kong Gateway?

You can create multiple Vault entities, one per region with the config.region parameter. You’d then reference the secret by the name of the Vault:

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