Skip to content

DEPRECATED — 2026-05-02. Migrated to docs/adr/security/IAM/IAM-0005-external-secrets-operator.md per ADR-0047. This file is retained for cross-reference continuity only.

ADR-0042 External Secrets Operator with Infisical Provider

Field Value
ID ADR-0042
Date 2026-04-27
Status Accepted
Deciders Ben Peries
Epic E2 Platform Security & Hardening (WI-258)
WI WI-367

Context

k3s workloads need access to platform secrets (API keys, credentials, TLS material) stored in Infisical. Without a bridge between Infisical and Kubernetes, operators must either:

  1. Manually create kubectl create secret objects (not auditable, drift-prone), or
  2. Mount Infisical SDK into every container image (couples apps to secrets backend), or
  3. Use the native Infisical Kubernetes Operator (vendor lock-in, single-backend).

The platform already runs Infisical as its single secrets source of truth (ADR-0002). A Kubernetes-native abstraction is needed that: syncs Infisical secrets into native Kubernetes Secrets objects, decouples workloads from the secrets backend, and positions the platform for future multi-backend scenarios (Azure Key Vault, GCP Secret Manager).

Decision

Install External Secrets Operator (ESO) v2.4.0 into the external-secrets namespace as the Kubernetes secrets bridge. Configure a ClusterSecretStore named infisical-archon-platform backed by Infisical via the ESO Infisical provider.

ESO is chosen over the native Infisical Kubernetes Operator.

Options Considered

Option A: Native Infisical Kubernetes Operator (rejected)

  • Infisical-maintained operator that syncs secrets directly.
  • Vendor lock-in: changing backends requires replacing the operator and all CRDs.
  • No CNCF backing; operator lifecycle tied to Infisical's release cadence.
  • Would require a different operator for future Azure KV or GCP SM integration.

Option B: External Secrets Operator with Infisical provider (selected)

  • CNCF sandbox project; broad ecosystem adoption and multi-backend support.
  • Single operator abstracts Infisical, Azure Key Vault, GCP Secret Manager, HashiCorp Vault, and others.
  • Workloads reference ExternalSecret CRDs that are backend-agnostic.
  • Decouples application manifests from secrets infrastructure.
  • Slightly more YAML per workload (SecretStore ref + target mapping), but manageable.

Option C: Direct Infisical CLI sidecar injection

  • Too complex per workload; no central management; not auditable at cluster level.
  • Rejected.

Rationale

ESO aligns with the platform's portfolio positioning goals (ADR-0025 multi-cloud Terraform, CNCF ecosystem alignment). A single operator handles current Infisical workloads and provides a clear migration path if the secrets backend ever changes. The Infisical operator would require a full replacement of all InfisicalSecret CRDs if the backend changed.

The extra abstraction layer (ExternalSecret CRD + ClusterSecretStore) is acceptable overhead given the long-term vendor neutrality benefit.

Consequences

  • ESO controller, cert-controller, and webhook run in external-secrets namespace (3 pods, low footprint).
  • All secrets consumed by k3s workloads MUST be created via ExternalSecret CRDs referencing infisical-archon-platform ClusterSecretStore (or a future alternative store).
  • A Machine Identity eso-archon-platform must exist in Infisical with read-only access to the archon-platform project, prod environment.
  • The bootstrap secret infisical-eso-creds (clientId + clientSecret) is a one-time manual step; it MUST NOT be committed to any repository.
  • Infisical's self-signed TLS cert requires a caProvider ConfigMap (infisical-ca in external-secrets namespace). This will be superseded when a proper CA-signed cert is deployed on Infisical (WI-248 scope).
  • ESO is the foundation for Group 4 (cert-manager Cloudflare token) and Group 5 (workload basicAuth credentials).

Implementation

See runbook: docs/platform/secrets/eso-setup-runbook.md

Manifests committed to archon-platform:

  • kubernetes/external-secrets/clustersecretstore-infisical.yaml -- ClusterSecretStore
  • kubernetes/external-secrets/configmap-infisical-ca.yaml -- CA cert for TLS trust

References

  • ESO Documentation
  • ESO Infisical Provider
  • ADR-0002: Infisical for Secrets Management
  • ADR-0025: Multi-Cloud Terraform Strategy
  • WI-366: Feature - Kubernetes Secrets Infrastructure - ESO
  • WI-367: Task - Install ESO and configure ClusterSecretStore with Infisical provider