This directory contains configuration for using HashiCorp Vault Agent to inject secrets into containers at runtime.
Overview#
Vault Agent is a daemon that runs alongside your application to:
- Authenticate with Vault automatically
- Render secrets to files using templates
- Automatically re-render when secrets change
- Renew authentication tokens
Files#
config.hcl- Vault Agent configurationtemplates/- Consul Template files for rendering secretscredentials/- AppRole credentials (not committed to git)Dockerfile- Docker image for Vault Agent
Setup#
1. Generate AppRole Credentials#
bash
# Start Vault (if not running)
docker compose --profile vault up -d
# Get the role ID (can be shared, not secret)
docker exec yemaya-vault vault read -field=role_id \
auth/approle/role/yemaya-api/role-id > docker/vault-agent/credentials/role-id
# Get the secret ID (keep this secure!)
docker exec yemaya-vault vault write -f -field=secret_id \
auth/approle/role/yemaya-api/secret-id > docker/vault-agent/credentials/secret-id
# Set proper permissions
chmod 600 docker/vault-agent/credentials/*
2. Start with Vault Agent#
bash
docker compose -f docker-compose.yml -f docker-compose.vault-agent.yml up -d
Templates#
Templates use Consul Template syntax:
hcl
{{- with secret "secret/data/yemaya/database" -}}
DATABASE_URL={{ .Data.data.url }}
{{- end }}
Available Templates#
| Template | Output | Description |
|---|---|---|
database.env.tpl |
/vault/secrets/database.env |
Database credentials |
redis.env.tpl |
/vault/secrets/redis.env |
Redis credentials |
api-keys.env.tpl |
/vault/secrets/api-keys.env |
AI provider API keys |
app.env.tpl |
/vault/secrets/app.env |
All application secrets |
Using Secrets in Containers#
Option 1: Source Environment File#
yaml
services:
api:
entrypoint: ['/bin/sh', '-c']
command:
- |
source /vault/secrets/app.env
exec node dist/index.js
volumes:
- vault_secrets:/vault/secrets:ro
Option 2: Use Environment File Directive#
yaml
services:
api:
env_file:
- /vault/secrets/app.env
volumes:
- vault_secrets:/vault/secrets:ro
Kubernetes Integration#
For Kubernetes, use the Vault Agent Injector or CSI provider:
Vault Agent Injector#
yaml
apiVersion: v1
kind: Pod
metadata:
name: yemaya-api
annotations:
vault.hashicorp.com/agent-inject: 'true'
vault.hashicorp.com/role: 'yemaya-api'
vault.hashicorp.com/agent-inject-secret-app.env: 'secret/data/yemaya/database'
vault.hashicorp.com/agent-inject-template-app.env: |
{{ with secret "secret/data/yemaya/database" -}}
DATABASE_URL={{ .Data.data.url }}
{{- end }}
spec:
containers:
- name: api
image: yemaya/api:latest
Vault CSI Provider#
yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
name: yemaya-secrets
spec:
provider: vault
parameters:
roleName: yemaya-api
vaultAddress: https://vault.yemaya.io:8200
objects: |
- objectName: "database"
secretPath: "secret/data/yemaya/database"
secretKey: "url"
Troubleshooting#
Secrets not rendering#
-
Check Vault Agent logs:
bashdocker logs yemaya-vault-agent -
Verify AppRole credentials:
bashcat docker/vault-agent/credentials/role-id # Should contain the role ID -
Test authentication manually:
bashdocker exec yemaya-vault vault write auth/approle/login \ role_id=$(cat docker/vault-agent/credentials/role-id) \ secret_id=$(cat docker/vault-agent/credentials/secret-id)
Permission denied errors#
-
Check policy assignment:
bashdocker exec yemaya-vault vault token lookup -
Verify the token has the required policy:
bashdocker exec yemaya-vault vault policy read yemaya-api
Template rendering errors#
-
Test template rendering:
bashdocker exec yemaya-vault-agent cat /vault/secrets/app.env -
Check for missing secrets:
bashdocker exec yemaya-vault vault kv list secret/yemaya/
Security Best Practices#
- Never commit credentials - Add
credentials/to.gitignore - Use short TTLs - Configure token TTL to 1 hour or less
- Rotate secret IDs - Regenerate secret IDs regularly
- Mount secrets read-only - Use
:rovolume mounts - Use tmpfs for secrets - In production, mount secrets to tmpfs
- Restrict file permissions - Use mode 0600 for sensitive files