Skip to main content

​
Secrets Management

Proper secrets management is crucial for secure AgentArea deployments. This guide covers various secret storage solutions, best practices, and integration patterns for both development and production environments.

​
🔐 Secrets Overview

AgentArea requires various types of secrets for secure operation:

Database Credentials

PostgreSQL connection strings, usernames, and passwords

API Keys & Tokens

JWT secrets, OpenAI API keys, third-party service tokens

Infrastructure Secrets

TLS certificates, SSH keys, cloud provider credentials

Application Secrets

Encryption keys, webhook secrets, session keys

​
🏗️ Secret Storage Solutions

​
Local Development

  • Environment Files
  • Local Secret Manager
Simple .env files for local development
# .env.local
DATABASE_URL=postgresql://user:pass@localhost:5432/agentarea
JWT_SECRET_KEY=your-local-secret-key
OPENAI_API_KEY=sk-your-openai-key
REDIS_URL=redis://localhost:6379

# Load in application
export $(cat .env.local | xargs)
Never commit .env files to version control. Add to .gitignore immediately.

​
Production Solutions

  • HashiCorp Vault
  • AWS Secrets Manager
  • Azure Key Vault
  • Google Secret Manager
Enterprise-grade secret management
# vault-config.yml
vault:
  server: "https://vault.company.com"
  auth_method: "kubernetes"
  role: "agentarea-prod"
  secrets_path: "secret/agentarea"

secrets:
  database:
    path: "secret/agentarea/database"
    keys: ["url", "username", "password"]
  api_keys:
    path: "secret/agentarea/api-keys"
    keys: ["openai", "jwt_secret"]

# Python Vault integration
import hvac

def get_vault_secrets():
    client = hvac.Client(url='https://vault.company.com')
    
    # Kubernetes auth
    with open('/var/run/secrets/kubernetes.io/serviceaccount/token') as f:
        jwt = f.read()
    
    client.auth.kubernetes.login(
        role='agentarea-prod',
        jwt=jwt
    )
    
    # Read secrets
    db_secrets = client.secrets.kv.v2.read_secret_version(
        path='agentarea/database'
    )['data']['data']
    
    return {
        'DATABASE_URL': db_secrets['url'],
        'JWT_SECRET_KEY': db_secrets['jwt_secret']
    }

​
🐳 Docker Integration

​
Docker Secrets

  • Docker Compose Secrets
  • External Secret Files
  • Runtime Secret Loading
# docker-compose.yml
version: '3.8'

secrets:
  db_password:
    file: ./secrets/db_password.txt
  jwt_secret:
    file: ./secrets/jwt_secret.txt
  openai_key:
    external: true
    name: agentarea_openai_key

services:
  agentarea-api:
    image: agentarea/api:latest
    secrets:
      - db_password
      - jwt_secret
      - openai_key
    environment:
      - DATABASE_URL_FILE=/run/secrets/db_password
      - JWT_SECRET_KEY_FILE=/run/secrets/jwt_secret
      - OPENAI_API_KEY_FILE=/run/secrets/openai_key

​
☸️ Kubernetes Integration

​
Native Kubernetes Secrets

  • Secret Creation
  • Pod Configuration
  • External Secrets Operator
# Create secrets from literals
kubectl create secret generic agentarea-secrets \
  --from-literal=database-url="postgresql://user:pass@host:5432/db" \
  --from-literal=jwt-secret="your-jwt-secret" \
  --from-literal=openai-key="sk-your-key"

# Create secrets from files
kubectl create secret generic agentarea-tls \
  --from-file=tls.crt=./certs/tls.crt \
  --from-file=tls.key=./certs/tls.key

# Create secrets from env file
kubectl create secret generic agentarea-env \
  --from-env-file=.env.production

​
🔄 Secret Rotation

​
Automated Rotation

​
🛡️ Security Best Practices

​
Secret Lifecycle Management

Generation

  • Use cryptographically secure random generators
  • Enforce minimum complexity requirements
  • Generate unique secrets per environment
  • Document secret purposes and ownership

Storage

  • Never store secrets in code or configs
  • Use encryption at rest and in transit
  • Implement proper access controls
  • Audit secret access and modifications

Distribution

  • Use secure channels for secret delivery
  • Implement just-in-time access patterns
  • Minimize secret exposure time
  • Use short-lived tokens when possible

Rotation

  • Implement regular rotation schedules
  • Automate rotation where possible
  • Test rotation procedures regularly
  • Have rollback procedures ready

​
Access Control

  • RBAC Policies
  • Vault Policies
  • IAM Policies
# Kubernetes RBAC for secrets
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: agentarea-secrets-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "list"]
  resourceNames: ["agentarea-secrets"]

---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: agentarea-secrets-binding
subjects:
- kind: ServiceAccount
  name: agentarea-api
roleRef:
  kind: Role
  name: agentarea-secrets-reader
  apiGroup: rbac.authorization.k8s.io

​
📊 Monitoring & Auditing

​
Secret Access Monitoring

​
🚨 Incident Response

​
Secret Compromise Response

1

Immediate Actions

  1. Identify scope - Determine which secrets are compromised
  2. Revoke access - Immediately disable compromised credentials
  3. Rotate secrets - Generate new secrets for affected systems
  4. Update applications - Deploy new secrets to running systems
2

Investigation

  1. Audit logs - Review access logs for unauthorized usage
  2. Timeline analysis - Determine when compromise occurred
  3. Impact assessment - Identify affected systems and data
  4. Root cause - Understand how the compromise happened
3

Recovery

  1. System validation - Ensure all systems are using new secrets
  2. Monitoring - Enhanced monitoring for suspicious activity
  3. Documentation - Update incident documentation
  4. Process improvement - Strengthen security procedures

​
Emergency Procedures

# Emergency secret rotation script
#!/bin/bash
set -e

echo "🚨 EMERGENCY SECRET ROTATION"
echo "This will rotate ALL AgentArea secrets"
read -p "Are you sure? (yes/NO): " confirm

if [ "$confirm" != "yes" ]; then
    echo "Aborted"
    exit 1
fi

# Rotate database password
./scripts/rotate_db_password.py

# Rotate JWT secret
./scripts/rotate_jwt_secret.sh

# Rotate API keys
./scripts/rotate_api_keys.sh

# Update Kubernetes secrets
kubectl delete secret agentarea-secrets
kubectl create secret generic agentarea-secrets \
  --from-literal=database-url="$(vault kv get -field=url secret/agentarea/database)" \
  --from-literal=jwt-secret="$(vault kv get -field=jwt_secret secret/agentarea/auth)"

# Rolling restart
kubectl rollout restart deployment/agentarea-api
kubectl rollout restart deployment/agentarea-frontend

echo "✅ Emergency rotation complete"
Security is a shared responsibility. Regular secret rotation, proper access controls, and monitoring are essential for maintaining a secure AgentArea deployment. Always follow the principle of least privilege and implement defense-in-depth strategies.
⌘I