# Vault Agent Secret Injection

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](https://github.com/hashicorp/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

## Related Documentation

- [Vault Documentation](./../../docs/VAULT.md)
- [Encryption](./../../docs/ENCRYPTION.md)
- [Environment Variables](./../../docs/ENVIRONMENT_VARIABLES.md)
