ADR 0046 - Secret Management (Framework 2.0)

Author

Gabriel Saratura

Owner

Schedar

Reviewers

Schedar

Date Created

Date Updated

Status

draft

Tags

framework,framework2,secrets,crossplane,vault,openbao
Summary

The decision selects Crossplane 2.x Connection Secret as connection credentials

Problem

Services need to securely store and distribute connection credentials (passwords, endpoints, TLS certificates) to Service Users in their claim namespaces.

Solutions

Option A: Crossplane Connection Secrets (Current)

Description:

Crossplane’s native connection secret mechanism. Composition functions use AddConnectionDetails() to export credentials, which Crossplane writes to the claim namespace.

Advantages:

  • Native Crossplane: Built-in mechanism, no additional dependencies

  • Proven Pattern: Existing appcat repository uses this, though architectural simplification is required

  • Automatic Propagation: Crossplane handles secret creation in composite namespace

  • Lifecycle Management: Secrets deleted when composite deleted

  • Simple Integration: Servala portal fetches secrets directly via K8s API

Disadvantages:

  • No Rotation: Secrets are static, no automatic rotation

  • No Centralization: Each service instance has separate secret

  • Limited Auditing: No built-in audit trail for secret access

  • Complexity: High complexity in handling connection secrets through managed resources

Option B: External Secrets Operator + Vault/OpenBao

Description:

Use External Secrets Operator to sync secrets from a centralized secret store (Vault / OpenBao) to Kubernetes secrets.

Architecture:

Composition Function creates secret A in claim namespace with static content such as username
        ↓
Creates ExternalSecret CR such as VaultDynamicSecret with reference to secret A
        ↓
External Secrets Operator generates password and certificates
        ↓
Syncs from Vault to secret A in claim namespace

Advantages:

  • Centralized Management: All secrets in one place (Vault/OpenBao)

  • Rotation Support: Can implement automatic password rotation

  • Auditing: Vault provides detailed audit logs

  • RBAC: Fine-grained access control policies

  • Encryption at Rest: Vault encrypts secrets

Disadvantages:

  • Additional Dependency: Requires Vault/OpenBao + External Secrets Operator

  • Additional Dependency: Static content has to be handled outside the operator

  • Complexity: More moving parts, harder to debug

  • Operational Overhead: (Vault/OpenBao) requires management, backup, HA setup

Decision

We use Crossplane Connection Secrets (continue current approach).

Rationale

  1. Proven Pattern: Existing appcat repository uses Crossplane secret management though major simplification in secret propagation is necessary.

  2. Simplicity: No additional dependencies. Crossplane handles lifecycle automatically.

  3. Service Credentials: Secrets are service connection details (host, port, password). These don’t require frequent rotation like API keys or tokens.

  4. Servala Integration: Servala portal already fetches secrets via K8s API. No changes needed.

Future Enhancement:

  • Phase 2: Investigate External Secrets Operator for centralized secret management

  • Implement rotation policies for long-lived instances

  • Add audit trail for secret access