Secret Management

OpenChoreo integrates with External Secrets Operator (ESO) to synchronize secrets from external secret stores into Kubernetes. This integration allows you to:

• Bring your own secret store: Use any ESO-supported backend (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, and many more)
• Use existing External Secrets setup: If you already have ESO deployed, OpenChoreo can work with your existing ClusterSecretStore configurations
• Centralized secret management: Manage all secrets in your preferred external store and let ESO sync them to Kubernetes

Enabling External Secrets Operator

ESO is included as an optional dependency in the plane Helm charts. Enable it by setting external-secrets.enabled: true in your values:

Data Plane:

external-secrets:
  enabled: true

Build Plane (if needed):

external-secrets:
  enabled: true

Observability Plane (if needed):

external-secrets:
  enabled: true

Single vs. Multi-Cluster

For single-cluster deployments, you typically only need ESO enabled in one plane (usually the Data Plane). For multi-cluster deployments, enable ESO in each cluster where you need secret synchronization.

Using Your Existing External Secrets Setup

If you already have External Secrets Operator deployed in your cluster with a configured ClusterSecretStore, you can skip enabling ESO in the OpenChoreo charts and simply reference your existing store.

Configure your DataPlane to use your existing SecretStore:

apiVersion: openchoreo.dev/v1alpha1
kind: DataPlane
metadata:
  name: default
  namespace: my-organization
spec:
  secretStoreRef:
    name: your-existing-secret-store
  # ... other configuration

Configuring a ClusterSecretStore

To connect ESO to your secret backend, create a ClusterSecretStore resource. For provider-specific configuration (authentication methods, endpoints, etc.), refer to the official ESO provider documentation:

• HashiCorp Vault
• AWS Secrets Manager
• GCP Secret Manager
• Azure Key Vault
• All Supported Providers

Example structure:

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: my-secret-store
spec:
  provider:
    # Provider-specific configuration
    # See: https://external-secrets.io/latest/provider/

Development Setup (Fake Provider)

For development and testing, you can use the built-in fake provider which defines static secrets directly in your Helm values:

external-secrets:
  enabled: true

fakeSecretStore:
  enabled: true
  name: default
  secrets:
    - key: github-pat
      value: "development-token"
    - key: docker-username
      value: "dev-user"
    - key: docker-password
      value: "dev-password"

warning

The fake provider is for development only. Never use it in production environments.

Creating ExternalSecrets

Create ExternalSecret resources to sync specific secrets from your backend. For complete documentation on ExternalSecret configuration, see the ESO documentation.

Example:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: app-secrets
  namespace: my-app
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: my-secret-store
    kind: ClusterSecretStore
  target:
    name: app-secrets
    creationPolicy: Owner
  data:
    - secretKey: database-url
      remoteRef:
        key: my-app/database
        property: url

Platform Secrets

These secrets are used by OpenChoreo infrastructure components:

Secret	Purpose	Plane
backstage-backend-secret	Backstage session encryption	Control
thunder-client-secret	OAuth client secret	Control
cluster-gateway-ca	Root CA for plane communication	Control
cluster-agent-tls	Agent mTLS certificates	All
registry-credentials	Container registry auth	Build/Data

Troubleshooting

Check ExternalSecret Status

kubectl get externalsecret -A
kubectl describe externalsecret <name> -n <namespace>

Check ClusterSecretStore Status

kubectl get clustersecretstore
kubectl describe clustersecretstore <name>

Check ESO Logs

kubectl logs -n <plane-namespace> deployment/external-secrets

For detailed troubleshooting guidance, see the ESO troubleshooting documentation.

Next Steps

• Container Registry Configuration: Use External Secrets for registry credentials
• Deployment Topology: Configure SecretStore references in planes
• External Secrets Operator Documentation: Complete ESO reference