Eve library

Vault Agent Secret Injection

Other

Revision 1

On this page

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:

  1. Authenticate with Vault automatically
  2. Render secrets to files using templates
  3. Automatically re-render when secrets change
  4. Renew authentication tokens

Files#

  • config.hcl - Vault Agent configuration
  • templates/ - Consul Template files for rendering secrets
  • credentials/ - 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#

  1. Check Vault Agent logs:

    bash
    docker logs yemaya-vault-agent
    
  2. Verify AppRole credentials:

    bash
    cat docker/vault-agent/credentials/role-id
    # Should contain the role ID
    
  3. Test authentication manually:

    bash
    docker 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#

  1. Check policy assignment:

    bash
    docker exec yemaya-vault vault token lookup
    
  2. Verify the token has the required policy:

    bash
    docker exec yemaya-vault vault policy read yemaya-api
    

Template rendering errors#

  1. Test template rendering:

    bash
    docker exec yemaya-vault-agent cat /vault/secrets/app.env
    
  2. Check for missing secrets:

    bash
    docker exec yemaya-vault vault kv list secret/yemaya/
    

Security Best Practices#

  1. Never commit credentials - Add credentials/ to .gitignore
  2. Use short TTLs - Configure token TTL to 1 hour or less
  3. Rotate secret IDs - Regenerate secret IDs regularly
  4. Mount secrets read-only - Use :ro volume mounts
  5. Use tmpfs for secrets - In production, mount secrets to tmpfs
  6. Restrict file permissions - Use mode 0600 for sensitive files