Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.0.x
  • Home icon
  • Kong Gateway
  • Kong Enterprise
  • Secrets Management
  • Backends
  • HashiCorp Vault
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Configuration via environment variables
  • Configuration via vaults entity
  • Examples
  • Vault configuration options
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.

Admin API
Declarative configuration
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>"

Result:

{
    "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
}

Secrets management is supported in decK 1.16 and later.

Add the following snippet to your declarative configuration file:

_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}

Vault configuration options

Use the following configuration options to configure the vaults entity through any of the supported tools:

  • Admin API
  • Declarative configuration

Configuration options for a HashiCorp vault in Kong Gateway:

Parameter Field name Description
vaults.config.protocol config-protocol (Kong Manager)
Protocol (Konnect)
The protocol to connect with. Accepts one of http or https.
vaults.config.host config-host (Kong Manager)
Host (Konnect)
The hostname of your HashiCorp vault.
vaults.config.port config-port (Kong Manager)
Port (Konnect)
The port number of your HashiCorp vault.
vaults.config.mount config-mount (Kong Manager)
Mount (Konnect)
The mount point.
vaults.config.kv config-kv (Kong Manager)
Kv (Konnect)
The secrets engine version. Accepts v1 or v2.
vaults.config.token config-token (Kong Manager)
Token (Konnect)
A token string.
vaults.config.ttl TTL Time-to-live (in seconds) of a secret from the vault when it’s cached. The special value of 0 means “no rotation” and it’s the default. When using non-zero values, it is recommended that they’re at least 1 minute.
vaults.config.neg_ttl Negative TTL Time-to-live (in seconds) of a vault miss (no secret). Negatively cached secrets will remain valid until neg_ttl is reached, after which Kong will attempt to refresh the secret again. The default value for neg_ttl is 0, meaning no negative caching occurs.
vaults.config.resurrect_ttl Resurrect TTL Time (in seconds) for how long secrets will remain in use after they are expired (config.ttl is over). This is useful when a vault becomes unreachable, or when a secret is deleted from the Vault and isn’t replaced immediately. On this both cases, the Gateway will keep trying to refresh the secret for resurrect_ttl seconds. After that, it will stop trying to refresh. We recommend assigning a sufficiently high value to this configuration option to ensure a seamless transition in case there are unexpected issues with the Vault. The default value for resurrect_ttl is 1e8 seconds, which is about 3 years.

Common options:

Parameter Field name Description
vaults.description
optional
Description An optional description for your vault.
vaults.name Name The type of vault. Accepts one of: env, gcp, aws, or hcv. Set hcv for HashiCorp Vault.
vaults.prefix Prefix The reference prefix. You need this prefix to access secrets stored in this vault. For example, {vault://hcv-vault/<some-secret>}.
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023