Home / How-to Guides
Edit
Report

Configure HashiCorp Vault as a vault backend with GCP workload identity

Uses: Kong Gateway Admin API
Incompatible with
konnect
Related Documentation
Gateway Documentation
Tags
#secrets-management #security #hashicorp-vault
Related Resources
Secrets management
Configure HashiCorp Vault as a vault backend
Configure HashiCorp Vault as a vault backend with GCP service account authentication
Configure HashiCorp Vault as a vault backend with AWS IAM authentication
Configure HashiCorp Vault as a vault backend with AWS EC2 authentication
Store Keyring data in a HashiCorp Vault
HashiCorp Google Cloud auth method reference
Minimum Version
Kong Gateway - 3.14
TL;DR

Run Kong Gateway on a GCE instance with a service account attached. Enable the GCP auth method in HashiCorp Vault and create a GCE role bound to your Kong Gateway service account.

Then in Kong Gateway, configure a Vault entity with the following:

  • Set config.auth_method to gcp_gce
  • Set config.gcp_auth_role to the Vault role name. The GCE instance identity token is provided automatically by the instance metadata service, no credential files are required.

Prerequisites

GCE instance with service account

To complete this tutorial, Kong Gateway must be running on a GCE (Google Compute Engine) instance with a service account that Kong Gateway will use to authenticate to HashiCorp Vault.

  1. Enable the following GCP APIs in your project:
    • iam.googleapis.com
    • compute.googleapis.com
  2. Export the bound project, zone, and labels for your GCE instance: 
    export GCP_PROJECT='YOUR GCP PROJECT'
export GCE_ZONE='YOUR GCE INSTANCE ZONE'
export GCE_LABEL='YOUR GCE INSTANCE LABELS'
  3. Create a service account to attach to your GCE instance with the “Compute Viewer” and “View Service Accounts” permissions.
  4. Export the service account email attached to your GCE instance: 
    export GCE_SERVICE_ACCOUNT="kong@YOUR-PROJECT.iam.gserviceaccount.com"
  5. Attach the service account to your GCE instance.

If Kong Gateway isn’t running on a GCE instance, use GCP service account authentication instead.

HashiCorp Vault

You need HashiCorp Vault installed on your VM.

The steps in this how to assume that HashiCorp Vault and Kong Gateway are installed on the same VM. Production instances will often install HashiCorp Vault and Kong Gateway on separate VMS. If this is the case, see the HashiCorp Vault GCP authentication documentation for the configuration changes you’ll need to make.

Configure HashiCorp Vault

Before you can configure the Vault entity in Kong Gateway, you must configure HashiCorp Vault to authenticate clients using GCE instance identity tokens and store a secret.

Create configuration files

First, create the primary configuration file config.hcl for HashiCorp Vault in the ./vault directory:

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

storage "file" {
  path = "./vault/data"
}

ui = true

Then, create the HashiCorp Vault policy file rw-secrets.hcl in the ./vault directory:

path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Configure the Vault and store a secret

  1. In a new terminal, start HashiCorp Vault: 
    vault server -config=./vault/config.hcl
  2. In your previous terminal, set the Vault address: 
    export VAULT_ADDR="http://localhost:8200"
  3. Initialize the Vault: 
    vault operator init -key-shares=1 -key-threshold=1

    This outputs your unseal key and initial root token. Export them as environment variables:

    export HCV_UNSEAL_KEY='YOUR-UNSEAL-KEY'
export DECK_HCV_TOKEN='YOUR-INITIAL-ROOT-TOKEN'
  4. Unseal your Vault: 
    vault operator unseal $HCV_UNSEAL_KEY
  5. Log in to your Vault: 
    vault login $DECK_HCV_TOKEN
  6. Write the policy to access secrets: 
    vault policy write rw-secrets ./vault/rw-secrets.hcl
  7. Enable GCP authentication: 
    vault auth enable gcp
  8. Create a GCE role that binds to Kong Gateway’s GCP service account: 
    vault write auth/gcp/role/kong-role \
  type="gce" \
  bound_projects="$GCP_PROJECT" \
  bound_zones="$GCE_ZONE" \
  bound_labels="$GCE_LABEL" \
  bound_service_accounts="$GCE_SERVICE_ACCOUNT" \
  token_policies="rw-secrets"
  9. Enable the K/V secrets engine: 
    vault secrets enable -path=kong kv
  10. Create a secret: 
    vault kv put kong/headers/request header="x-kong:test"
  11. Confirm you can retrieve the secret through Vault: 
    vault kv get kong/headers/request

Set environment variables

Find the internal IP for your VM:

hostname -I

Export the following environment variables before creating the Vault entity:

export HCV_HOST="YOUR VM INTERNAL IP"
export GCP_AUTH_ROLE=kong-role

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 GCP workload identity authentication: 

curl -X POST "http://localhost:8001/vaults" \
     --no-progress-meter --fail-with-body  \
     -H "Content-Type: application/json" \
     --json '{
       "name": "hcv",
       "prefix": "hashicorp-vault",
       "description": "Storing secrets in HashiCorp Vault",
       "config": {
         "host": "'$HCV_HOST'",
         "kv": "v1",
         "mount": "kong",
         "port": 8200,
         "protocol": "http",
         "auth_method": "gcp_gce",
         "gcp_auth_role": "'$GCP_AUTH_ROLE'",
         "gcp_login_path": "/v1/auth/gcp/login"
       }
     }'

Validate

To validate that the secret was stored correctly in HashiCorp Vault, call a secret from your vault using the kong vault get command.

sudo -E kong vault get {vault://hashicorp-vault/headers/request/header}

If the vault was configured correctly, this command returns the value of the secret. You can use {vault://hashicorp-vault/headers/request/header} to reference the secret in any referenceable field.

For more information about supported secret types, see What can be stored as a secret.

Cleanup

Clean up HashiCorp Vault

Stop the HashiCorp Vault process by running the following:

pkill vault

Unset environment variables:

unset VAULT_ADDR
unset VAULT_GCP_CREDENTIALS_FILE

Destroy the Kong Gateway container

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

FAQs

What if Kong Gateway is not running on a GCE instance?

The gcp_gce auth method requires Kong Gateway to run on a GCE instance. It relies on the GCE instance metadata service to provide the identity token automatically. If Kong Gateway isn’t on GCE, use GCP service account authentication (gcp_iam) instead, which works from any environment.

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.

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:

  • Using environment variables, set at Kong Gateway startup
  • Using parameters in kong.conf, set at Kong Gateway startup

See the Vault reference for your provider for the available parameters and their format in each method.

Next Steps

Review the Vaults entity
What can be stored as a secret?
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

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!
Contribute

Still need help?

Ask in our Slack Community
Contact Support