curl -X POST "http://localhost:8001/vaults" \
--no-progress-meter --fail-with-body \
--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": "aws_ec2",
"aws_auth_role": "'$AWS_AUTH_ROLE'",
"aws_auth_nonce": "'$AWS_AUTH_NONCE'"
}
}'Configure HashiCorp Vault as a vault backend with AWS EC2 authentication
Incompatible with
konnect
Related Documentation
Related Resources
Minimum Version
Kong Gateway - 3.14
TL;DR
Run Kong Gateway on an EC2 instance with an instance profile attached. Enable the AWS auth method in HashiCorp Vault and create an EC2 role bound to the instance’s AMI ID.
Then in Kong Gateway, configure a Vault entity with the following:
- Set
config.auth_methodset toaws_ec2. - Set
config.aws_auth_roleto the Vault role name. - Set
config.aws_auth_nonceto a unique nonce string. The EC2 instance identity document is provided automatically by the instance metadata service, no AWS credentials are required on Kong Gateway’s side.
Prerequisites
EC2 instance with instance profile
Kong Gateway must be running on an EC2 instance with an instance profile attached. The EC2 instance identity document is automatically provided by the instance metadata service, no additional IAM permissions are required on Kong Gateway’s side.
Note the AMI ID of your EC2 instance and export it:
export KONG_EC2_AMI_ID="ami-0abcdef1234567890"Generate a unique nonce string. This nonce is stored with the Vault token and validated on subsequent logins to prevent replay attacks:
export AWS_AUTH_NONCE="$(openssl rand -hex 16)"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 AWS 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 EC2 instance identity documents 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 = trueThen, 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
- In a new terminal, start HashiCorp Vault:
vault server -config=./vault/config.hcl - In your previous terminal, set the Vault address:
export VAULT_ADDR="http://localhost:8200" - Initialize the Vault:
vault operator init -key-shares=1 -key-threshold=1This 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' - Unseal your Vault:
vault operator unseal $HCV_UNSEAL_KEY - Log in to your Vault:
vault login $DECK_HCV_TOKEN - Write the policy to access secrets:
vault policy write rw-secrets ./vault/rw-secrets.hcl - Enable AWS authentication:
vault auth enable aws - Create an EC2 role that binds to your Kong Gateway instance’s AMI ID:
vault write auth/aws/role/kong-role \ auth_type=ec2 \ bound_ami_id="$KONG_EC2_AMI_ID" \ token_policies="rw-secrets" - Enable the K/V secrets engine:
vault secrets enable -path=kong kv - Create a secret:
vault kv put kong/headers/request header="x-kong:test" - 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 -IExport the following environment variables before creating the Vault entity:
export HCV_HOST="YOUR VM INTERNAL IP"
export AWS_AUTH_ROLE=kong-roleCreate a Vault entity for HashiCorp Vault
Create a Vault entity with the required parameters for HashiCorp Vault AWS EC2 authentication:
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 vaultUnset environment variables:
unset VAULT_ADDR
unset KONG_EC2_AMI_ID
unset AWS_AUTH_NONCEDestroy the Kong Gateway container
curl -Ls https://get.konghq.com/quickstart | bash -s -- -dFAQs
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.