Configure HashiCorp Vault as a vault backend

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

Kong Konnect

This is a Konnect tutorial. If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
- Control Plane Name: You can use an existing Control Plane or create a new one to use for this tutorial.
- Konnect Proxy URL: By default, a self-hosted Data Plane uses http://localhost:8000. You can set up Data Plane nodes for your Control Plane from the Gateway Manager in Konnect.

Set the personal access token, the Control Plane name, the Control Plane URL, and the Konnect proxy URL as environment variables:

 export DECK_KONNECT_TOKEN='YOUR KONNECT TOKEN'
 export DECK_KONNECT_CONTROL_PLANE_NAME='YOUR CONTROL PLANE NAME'
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='KONNECT PROXY URL'

Kong Gateway running

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 Ready

decK

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

HashiCorp Vault

This how-to requires you to have a dev mode or self-managed HashiCorp Vault. The following instructions will guide you through configuring a HashiCorp Vault in dev mode with the resources you need to integrate it with Kong Gateway.

Important: This tutorial uses the literal root string as your token, which should only be used in testing and development environments.

Install HashiCorp Vault.
In a terminal, start your Vault dev server with root as your token.
```
vault server -dev -dev-root-token-id root
```
In the output from the previous command, copy the VAULT_ADDR to export.
In a new terminal window, export your VAULT_ADDR as an environment variable.
Verify that your Vault is running correctly:
```
vault status
```
Authenticate with Vault:
```
vault login root
```
Verify that you are using the v2 secrets engine:
```
vault read sys/mounts/secret
```
The options key should have the map[version:2] value.

Create a secret in HashiCorp Vault

Write a secret to HashiCorp Vault:

vault kv put secret/customer/acme name="ACME Inc."

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'

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 -

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'

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}

 kong vault get {vault://hashicorp-vault/customer/acme/name}

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

Clean up HashiCorp Vault

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

pkill vault

Unset environment variables:

unset VAULT_ADDR

Destroy the Kong Gateway container

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

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.

FAQs

How do I rotate my secrets in HashiCorp Vault and how does Kong Gateway pick up the new secret values?

You can rotate your secret in HashiCorp Vault by creating a new secret version with the updated value. You’ll also want to configure the ttl settings in your Kong Gateway Vault entity so that Kong Gateway pulls the rotated secret periodically.

How does Kong Gateway retrieve secrets from HashiCorp Vault?

Kong Gateway retrieves secrets from HashiCorp Vault’s HTTP API through a two-step process: authentication and secret retrieval.

Step 1: Authentication

Depending on the authentication method defined in config.auth_method, Kong Gateway authenticates to HashiCorp Vault using one of the following methods:

If you’re using the token auth method, Kong Gateway uses the config.token as the client token.
If you’re using the kubernetes auth method, Kong Gateway uses the service account JWT token mounted in the pod (path defined in the config.kube_api_token_file) to call the login API for the Kubernetes auth path on the HashiCorp Vault server and retrieve a client token.
v3.4+ If you’re using the approle auth method, Kong Gateway uses the AppRole credentials to retrieve a client token. The AppRole role ID is configured by field config.approle_role_id, and the secret ID is configured by field config.approle_secret_id or config.approle_secret_id_file.
- If you set config.approle_response_wrapping to true, then the secret ID configured by config.approle_secret_id or config.approle_secret_id_file will be a response wrapping token, and Kong Gateway will call the unwrap API /v1/sys/wrapping/unwrap to unwrap the response wrapping token to fetch the real secret ID. Kong Gateway will use the AppRole role ID and secret ID to call the login API for the AppRole auth path on the HashiCorp Vault server and retrieve a client token.

By calling the login API, Kong Gateway will retrieve a client token and then use it in the next step as the value of X-Vault-Token header to retrieve a secret.

Step 2: Retrieving the secret

Kong Gateway uses the client token retrieved in the authentication step to call the Read Secret API and retrieve the secret value. The request varies depending on the secrets engine version you’re using. Kong Gateway will parse the response of the read secret API automatically and return the secret value.

Next Steps

Review the Vaults entity