You are browsing documentation for an outdated version. See the latest documentation here.

HashiCorp Vault

HashiCorp Vault can be configured with environment variables or with a Vault entity.

Configuration via environment variables

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

Static Vault token authentication:

export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
export KONG_VAULT_HCV_HOST=<hostname>
export KONG_VAULT_HCV_PORT=<portnumber>
export KONG_VAULT_HCV_MOUNT=<mountpoint>
export KONG_VAULT_HCV_KV=<v1|v2>
export KONG_VAULT_HCV_AUTH_METHOD=token
export KONG_VAULT_HCV_TOKEN=<tokenstring>

Kubernetes service account role authentication:

export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
export KONG_VAULT_HCV_HOST=<hostname>
export KONG_VAULT_HCV_PORT=<portnumber>
export KONG_VAULT_HCV_MOUNT=<mountpoint>
export KONG_VAULT_HCV_KV=<v1|v2>
export KONG_VAULT_HCV_AUTH_METHOD=kubernetes
export KONG_VAULT_HCV_KUBE_ROLE=<rolename>

You can also store this information in an entity.

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.

curl -i -X PUT http://HOSTNAME:8001/vaults/hashicorp-vault \
  --data name="hcv" \
  --data description="Storing secrets in HashiCorp Vault" \
  --data config.protocol="https" \
  --data config.host="localhost" \
  --data config.port="8200" \
  --data config.mount="secret" \
  --data config.kv="v2" \
  --data config.token="<token>"

{
    "config": {
        "host": "localhost",
        "kv": "v2",
        "mount": "secret",
        "port": 8200,
        "protocol": "https",
        "token": "<token>"
    },
    "created_at": 1645008893,
    "description": "Storing secrets in HashiCorp Vault",
    "id": "0b43d867-05db-4bed-8aed-0fccb6667837",
    "name": "hcv",
    "prefix": "hashicorp-vault",
    "tags": null,
    "updated_at": 1645008893
}

_format_version: "3.0"
vaults:
- config:
    host: localhost
    kv: v2
    mount: secret
    port: 8200
    protocol: https
    token: <token>
  description: Storing secrets in HashiCorp Vault
  name: hcv
  prefix: hashicorp-vault

Examples

For example, if you’ve configured a HashiCorp Vault with a path of secret/hello and a key=value pair of foo=world:

vault kv put secret/hello foo=world

Key                Value
---                -----
created_time       2022-01-15T01:40:03.740833Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Access these secrets like this:

{vault://hcv/hello/foo}

Or, if you configured an entity:

{vault://hashicorp-vault/hello/foo}

If you have configured a secret value in multiple versions:

# Requires kv2 engine enabled
vault kv patch secret/hello foo=world2

======= Metadata =======
Key                Value
---                -----
created_time       2022-01-16T01:40:03.740833Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

Access an older version of the secret like this:

# For version 1
{vault://hcv/hello/foo#1}

# For version 2
{vault://hcv/hello/foo#2}

# Do not specify version number for the latest version
{vault://hcv/hello/foo}

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 a HashiCorp vault in Kong Gateway:

Common options: