Status
Back to Developer Docs

Configuration & Secrets Management

Comprehensive guide to configuration management and secrets handling in Blueberry IDP

Overview

Blueberry IDP uses a layered approach to configuration and secrets management, combining Google Secret Manager, Kubernetes secrets, and various configuration methods to provide secure and flexible configuration options.

Secrets Management Architecture

Complete secrets management flow showing how secrets are created, stored, and accessed across the platform.

Secrets Management Architecture Diagram

Configuration Categories

🔐 Authentication Secrets

  • GitLab tokens: Personal access tokens for repository access
  • OAuth secrets: Client secrets for authentication providers
  • API tokens: Platform-generated tokens for programmatic access
  • Firebase keys: Authentication and database access keys

🔗 Integration Secrets

  • Webhook tokens: Validation tokens for GitLab webhooks
  • Slack URLs: Webhook URLs for notifications
  • Registry credentials: Container registry access tokens
  • Database passwords: Redis and other database credentials

Secret Storage Layers

Google Secret Manager (Primary)

Central secrets repository with automatic encryption, versioning, and access control.

  • • All sensitive configuration stored here
  • • Automatic encryption at rest and in transit
  • • Fine-grained IAM access controls
  • • Version history and rotation support

Kubernetes Secrets (Runtime)

Secrets mounted directly into pods for application runtime access.

  • • Synchronized from Google Secret Manager
  • • Namespace-isolated for security
  • • Mounted as environment variables or files
  • • Automatic updates via External Secrets Operator

Application Configuration

Runtime configuration loading with multiple access methods.

  • • Environment variables for simple configuration
  • • ConfigMaps for non-sensitive settings
  • • Lazy loading from Secret Manager API
  • • Caching for performance optimization

Security Features

🔑 Workload Identity

  • No stored service account keys
  • Automatic credential rotation
  • Kubernetes service account binding
  • Fine-grained IAM permissions

🛡️ Access Control

  • Least privilege access model
  • Namespace-based isolation
  • Role-based access control (RBAC)
  • Audit logging for all access

🔄 Lifecycle Management

  • Automatic secret rotation
  • Version history tracking
  • Graceful secret updates
  • Terraform-managed provisioning

Configuration Methods

1. Environment Variables

Direct configuration via environment variables in containers:

env:
  - name: PROJECT_ID
    value: "development-454916"
  - name: FIREBASE_API_KEY
    valueFrom:
      secretKeyRef:
        name: firebase-config
        key: api-key

2. Kubernetes Mounts

Secrets mounted as files in the container filesystem:

volumeMounts:
  - name: secrets-volume
    mountPath: /etc/secrets
    readOnly: true
volumes:
  - name: secrets-volume
    secret:
      secretName: app-secrets

3. Runtime Loading

Lazy loading secrets from Google Secret Manager at runtime:

from google.cloud import secretmanager

async def get_secret(secret_name: str) -> str:
    client = secretmanager.SecretManagerServiceClient()
    name = f"projects/{PROJECT_ID}/secrets/{secret_name}/versions/latest"
    response = client.access_secret_version(request={"name": name})
    return response.payload.data.decode("UTF-8")

Best Practices

✅ Do

  • Use Google Secret Manager for all sensitive data
  • Implement proper secret rotation policies
  • Use namespace isolation for multi-tenant secrets
  • Monitor secret access patterns
  • Use Workload Identity instead of service account keys
  • Implement proper error handling for secret access

❌ Don't

  • Store secrets in environment variables in source code
  • Use the same secret across multiple environments
  • Grant broad secret access permissions
  • Skip secret rotation for long-running services
  • Log or expose secrets in error messages
  • Use hardcoded secrets in configuration files

Troubleshooting

Secret Access Errors

Common issues and solutions:

  • • Check Workload Identity binding between K8s SA and GCP SA
  • • Verify IAM permissions for secret access
  • • Ensure External Secrets Operator is running
  • • Check secret names and versions

Configuration Loading Issues

Debugging configuration problems:

  • • Check pod logs for secret mount errors
  • • Verify ConfigMap and Secret resources exist
  • • Test Secret Manager API access manually
  • • Review application configuration parsing

Secure configuration management is critical for platform security and reliability.