Configure HashiCorp Vault as a vault backend

Uses: Kong Gateway decK
TL;DR

Install and run HashiCorp Vault in dev mode or self-managed. Write a secret to the Vault like vault kv put secret/customer/acme name="ACME Inc.". Save your HashiCorp Vault token, host, port, protocol, and KV secrets engine version and use them to configure a Kong Gateway Vault entity. Use {vault://hashicorp-vault/customer/acme/name} to reference the secret in any referenceable field.

Prerequisites

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

     export KONNECT_TOKEN='YOUR_KONNECT_PAT'
    
    Copied to clipboard!
  3. 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-output
    
    Copied to clipboard!

    This 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'
    
    Copied to clipboard!

    Copy and paste these into your terminal to configure your session.

Create a secret in HashiCorp Vault

Write a secret to HashiCorp Vault:

vault kv put secret/customer/acme name="ACME Inc."
Copied to clipboard!

Create decK environment variables

We’ll use decK environment variables for the host and token in the Kong Gateway Vault configuration. This is because these values typically vary between environments.

In this tutorial, we’re using host.docker.internal as our host instead of the localhost variable that HashiCorp Vault is using. This is because if you used the quick-start script Kong Gateway is running in a container and uses a different localhost.

Because we are running HashiCorp Vault in dev mode, we are using root for our token value.

export DECK_HCV_HOST="host.docker.internal"
export DECK_HCV_TOKEN="root"
Copied to clipboard!

Create a Vault entity for HashiCorp Vault

Using decK, create a Vault entity in the kong.yaml file with the required parameters for HashiCorp Vault:

echo '
_format_version: "3.0"
vaults:
  - name: hcv
    prefix: hashicorp-vault
    description: Storing secrets in HashiCorp Vault
    config:
      host: "${{ env "DECK_HCV_HOST" }}"
      token: "${{ env "DECK_HCV_TOKEN" }}"
      kv: v2
      mount: secret
      port: 8200
      protocol: http
' | deck gateway apply -
Copied to clipboard!

Validate

Since Konnect data plane container names can vary, set your container name as an environment variable:

export KONNECT_DP_CONTAINER='your-dp-container-name'
Copied to clipboard!

To validate that the secret was stored correctly in HashiCorp Vault, you can call a secret from your vault using the kong vault get command within the Data Plane container.

 kong vault get {vault://hashicorp-vault/customer/acme/name}
Copied to clipboard!

If the vault was configured correctly, this command should return the value of the secret. You can use {vault://hashicorp-vault/customer/acme/name} to reference the secret in any referenceable field.

Cleanup

Stop the HashiCorp Vault dev server process by running the following:

pkill vault
Copied to clipboard!

Unset environment variables:

unset VAULT_ADDR
Copied to clipboard!

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!