Create a directory for your secret files on the data plane, then configure a Vault entity with name: fs and config.prefix set to that directory path.
Reference secrets using {vault://fs-vault/my-secret.txt} for plain text files, or {vault://fs-vault/creds.json/password} to extract a specific key from a JSON file.
This is a Konnect tutorial and requires a Konnect personal access token.
Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Export your token to an environment variable:
export KONNECT_TOKEN='YOUR_KONNECT_PAT'Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:
curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN \
--deck-outputThis sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:
export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
export KONNECT_PROXY_URL='http://localhost:8000'Copy and paste these into your terminal to configure your session.
This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.
Export your license to an environment variable:
export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'Run the quickstart script:
curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA Once Kong Gateway is ready, you will see the following message:
Kong Gateway ReadyTo complete this tutorial, install decK. We recommend keeping decK up to date with the latest version (1.64.0).
decK is a CLI tool for managing Kong Gateway declaratively with state files.
This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance.
You can check your current decK version with deck version.
Create a directory for your secrets on the Kong Gateway data plane and add at least one secret file.
For example, if using the quickstart Docker container:
Create the directory:
docker exec kong-quickstart-gateway mkdir -p /tmp/kong/secretsCreate a test secret:
docker exec kong-quickstart-gateway /bin/sh -c 'echo -n "my-secret-value" > /tmp/kong/secrets/my-secret.txt'Export the directory path as an environment variable for use with decK:
Since Konnect data plane container names can vary, set your container name as an environment variable:
export KONNECT_DP_CONTAINER='your-dp-container-name'Create the directory:
docker exec $KONNECT_DP_CONTAINER mkdir -p /tmp/kong/secretsCreate a test secret:
docker exec $KONNECT_DP_CONTAINER /bin/sh -c 'echo -n "my-secret-value" > /tmp/kong/secrets/my-secret.txt'Export the directory path as an environment variable for use with decK:
export DECK_FS_PREFIX="/tmp/kong/secrets"export DECK_FS_PREFIX="/tmp/kong/secrets"Using decK, create a Vault entity that points to your secrets directory:
echo '
_format_version: "3.0"
vaults:
- name: fs
prefix: fs-vault
description: Storing secrets in local files
config:
prefix: "${{ env "DECK_FS_PREFIX" }}"
' | deck gateway apply -To validate that the Vault can read your secret, call it using the kong vault get command within the data plane container:
docker exec $KONNECT_DP_CONTAINER kong vault get {vault://fs-vault/my-secret.txt}docker exec kong-quickstart-gateway kong vault get {vault://fs-vault/my-secret.txt}If the vault was configured correctly, this command returns the contents of the file.
You can now reference any file in the secrets directory from any referenceable field using {vault://fs-vault/example-filename}.
For JSON files, you can extract a specific key by appending it to the path. For example, if /tmp/kong/secrets/creds.json contains {"username":"user","password":"pass"}, reference individual values like {vault://fs-vault/creds.json/password}.
For more information about supported secret types, see What can be stored as a secret.
curl -Ls https://get.konghq.com/quickstart | bash -s -- -dIf 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.
How do I rotate secrets in the file system vault, and how does Kong Gateway pick up the new values?
Update the file contents on disk. Configure the ttl setting in your Kong Gateway Vault entity so that Kong Gateway re-reads the file periodically.
Can the file system vault read secrets from subdirectories?
Yes. Reference the path relative to config.prefix.
For example, if your prefix is /tmp/kong/secrets and your secret is at /tmp/kong/secrets/db/password.txt, reference it as {vault://fs-vault/db/password.txt}.
Can I configure Vault in a different way without using the Vault entity directly?
Yes, you can also configure a Vault in one of the following ways:
kong.conf, set at Kong Gateway startupSee the Vault reference for your provider for the available parameters and their format in each method.