Yemaya integrates with HashiCorp Vault for secure secret management in production environments.
Overview#
Vault provides:
- Centralized secret storage
- Dynamic credentials
- Automatic secret rotation
- Comprehensive audit logging
- Fine-grained access control
Quick Start (Development)#
Start Vault in development mode:
bash
# Start Vault with other services
docker compose --profile vault up -d
# Vault is available at http://localhost:8200
# Dev token: yemaya-dev-token
Access the Vault UI at http://localhost:8200 and log in with token
yemaya-dev-token.
Architecture#
Secret Paths#
Yemaya uses the following secret paths under secret/yemaya/:
| Path | Description |
|---|---|
database |
Database credentials |
redis |
Redis connection info |
storage |
MinIO/S3 credentials |
auth/jwt |
JWT signing keys |
auth/session |
Session secrets |
oauth/* |
OAuth provider credentials |
ai/* |
AI provider API keys |
email |
SMTP credentials |
encryption |
Master encryption key |
Access Policies#
| Policy | Description | Use Case |
|---|---|---|
yemaya-api |
API service access | Web/API servers |
yemaya-workers |
Worker access | Background jobs |
yemaya-admin |
Full admin access | Operators |
yemaya-readonly |
Read-only metadata | Monitoring |
Authentication Methods#
1. Token Authentication (Development)#
typescript
import { VaultClient } from '@yemaya/core';
const vault = new VaultClient({
address: 'http://localhost:8200',
auth: { method: 'token', token: 'yemaya-dev-token' },
});
2. AppRole Authentication (Production)#
AppRole is recommended for service-to-service authentication.
typescript
const vault = new VaultClient({
address: 'https://vault.yemaya.io:8200',
auth: {
method: 'approle',
roleId: process.env.VAULT_ROLE_ID!,
secretId: process.env.VAULT_SECRET_ID!,
},
});
Setting Up AppRole#
bash
# Get Role ID (can be shared)
vault read auth/approle/role/yemaya-api/role-id
# Generate Secret ID (keep secret!)
vault write -f auth/approle/role/yemaya-api/secret-id
3. Kubernetes Authentication (K8s)#
For Kubernetes deployments:
typescript
const vault = new VaultClient({
address: 'https://vault.yemaya.io:8200',
auth: {
method: 'kubernetes',
role: 'yemaya-api',
},
});
Using the Vault Client#
Get Secrets#
typescript
import { createSecretsProvider, CachingSecretsProvider } from '@yemaya/core';
// Create provider (auto-detects Vault or falls back to env vars)
const secrets = createSecretsProvider();
// With caching
const cachedSecrets = new CachingSecretsProvider(secrets, {
defaultTTL: 300, // 5 minutes
backgroundRefresh: true,
});
// Get a secret
const dbSecret = await cachedSecrets.getSecret('yemaya/database');
console.log(dbSecret.url);
// Get a specific value
const jwtSecret = await cachedSecrets.getSecretValue(
'yemaya/auth/jwt',
'secret'
);
Write Secrets (Admin Only)#
typescript
const vault = new VaultClient({
address: 'http://localhost:8200',
auth: { method: 'token', token: adminToken },
});
await vault.putSecret('yemaya/ai/anthropic', {
api_key: 'sk-ant-...',
model: 'claude-3-5-sonnet-20241022',
});
List Secrets#
typescript
const keys = await vault.listSecrets('yemaya/');
// ['database', 'redis', 'storage', ...]
Environment Variables#
Configure Vault connection via environment:
| Variable | Description |
|---|---|
VAULT_ADDR |
Vault server address |
VAULT_TOKEN |
Token for auth |
VAULT_ROLE_ID |
AppRole role ID |
VAULT_SECRET_ID |
AppRole secret ID |
VAULT_K8S_ROLE |
Kubernetes auth role |
VAULT_NAMESPACE |
Vault namespace (Enterprise) |
Production Setup#
1. Configure Storage Backend#
For production, use a highly-available storage backend:
hcl
# infrastructure/vault/config/vault-prod.hcl
storage "postgresql" {
connection_url = "postgres://vault:password@postgres:5432/vault"
ha_enabled = true
}
Or use cloud storage:
- AWS:
storage "s3" { ... } - GCP:
storage "gcs" { ... } - Azure:
storage "azure" { ... }
2. Enable TLS#
hcl
listener "tcp" {
address = "0.0.0.0:8200"
tls_cert_file = "/vault/tls/vault.crt"
tls_key_file = "/vault/tls/vault.key"
}
3. Configure Auto-Unseal#
Use cloud KMS for automatic unsealing:
hcl
# AWS KMS
seal "awskms" {
region = "us-east-1"
kms_key_id = "alias/vault-unseal-key"
}
4. Enable Audit Logging#
bash
vault audit enable file file_path=/vault/logs/audit.log
5. Apply Policies#
bash
# Apply Yemaya policies
vault policy write yemaya-api /vault/policies/yemaya-api.hcl
vault policy write yemaya-workers /vault/policies/yemaya-workers.hcl
vault policy write yemaya-admin /vault/policies/yemaya-admin.hcl
6. Configure AppRole#
bash
# Enable AppRole auth
vault auth enable approle
# Create roles
vault write auth/approle/role/yemaya-api \
token_policies="yemaya-api" \
token_ttl=1h \
token_max_ttl=24h
vault write auth/approle/role/yemaya-workers \
token_policies="yemaya-workers" \
token_ttl=1h \
token_max_ttl=24h
Dynamic Database Credentials#
Vault can generate short-lived database credentials:
Setup#
bash
# Enable database secrets engine
vault secrets enable database
# Configure PostgreSQL connection
vault write database/config/yemaya-postgres \
plugin_name=postgresql-database-plugin \
connection_url="postgresql://{{username}}:{{password}}@postgres:5432/yemaya" \
allowed_roles="yemaya-api,yemaya-worker" \
username="vault" \
password="vault-password"
# Create roles
vault write database/roles/yemaya-api \
db_name=yemaya-postgres \
creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
default_ttl="1h" \
max_ttl="24h"
Usage#
typescript
// Get dynamic credentials
const creds = await vault.request('GET', '/v1/database/creds/yemaya-api');
// { username: 'v-approle-yemaya-api-...', password: '...', lease_id: '...' }
Secret Rotation#
Manual Rotation#
bash
# Rotate a secret
vault kv put secret/yemaya/auth/jwt \
secret=$(openssl rand -base64 48)
Automatic Rotation#
Configure TTLs on dynamic secrets:
bash
vault write auth/token/roles/yemaya-api \
allowed_policies="yemaya-api" \
period="1h" \
renewable=true
Monitoring#
Health Check#
typescript
const health = await vault.health();
// { initialized: true, sealed: false, standby: false, version: '1.15.0' }
Metrics#
Vault exposes Prometheus metrics at /v1/sys/metrics.
Security Best Practices#
- Never use dev mode in production - Use proper storage and unsealing
- Enable TLS - Always use HTTPS for Vault communication
- Use AppRole or K8s auth - Avoid long-lived tokens
- Enable audit logging - Required for compliance
- Rotate secrets regularly - Use short TTLs and dynamic credentials
- Limit access - Apply principle of least privilege
- Monitor access - Alert on unusual patterns
- Backup regularly - Include Vault in disaster recovery
Troubleshooting#
"Vault is sealed"#
bash
# Check seal status
vault status
# Unseal (manual mode)
vault operator unseal <key1>
vault operator unseal <key2>
vault operator unseal <key3>
"Permission denied"#
- Check token has required policy
- Verify policy includes the path
- Check policy syntax
"Connection refused"#
- Verify
VAULT_ADDRis correct - Check Vault is running:
vault status - Verify network connectivity