Configure HashiCorp Vault as a vault backend with AWS EC2 authentication

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 = 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
   

   Copied!
2. In your previous terminal, set the Vault address:

   export VAULT_ADDR="http://localhost:8200"
   

   Copied!
3. Initialize the Vault:

   vault operator init -key-shares=1 -key-threshold=1
   

   Copied!

   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'
   

   Copied!
4. Unseal your Vault:

   vault operator unseal $HCV_UNSEAL_KEY
   

   Copied!
5. Log in to your Vault:

   vault login $DECK_HCV_TOKEN
   

   Copied!
6. Write the policy to access secrets:

   vault policy write rw-secrets ./vault/rw-secrets.hcl
   

   Copied!
7. Enable AWS authentication:

   vault auth enable aws
   

   Copied!
8. 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"
   

   Copied!
9. Enable the K/V secrets engine:

   vault secrets enable -path=kong kv
   

   Copied!
10. Create a secret:

    vault kv put kong/headers/request header="x-kong:test"
    

    Copied!
11. Confirm you can retrieve the secret through Vault:

    vault kv get kong/headers/request
    

    Copied!

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 AWS_AUTH_ROLE=kong-role

Create a Vault entity with the required parameters for HashiCorp Vault AWS EC2 authentication:

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

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.