Eve library

HashiCorp Vault Integration

Guide

Revision 1

On this page

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#

  1. Never use dev mode in production - Use proper storage and unsealing
  2. Enable TLS - Always use HTTPS for Vault communication
  3. Use AppRole or K8s auth - Avoid long-lived tokens
  4. Enable audit logging - Required for compliance
  5. Rotate secrets regularly - Use short TTLs and dynamic credentials
  6. Limit access - Apply principle of least privilege
  7. Monitor access - Alert on unusual patterns
  8. 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_ADDR is correct
  • Check Vault is running: vault status
  • Verify network connectivity