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

Installing External Secrets Operator

ESO must be installed as a standalone prerequisite before installing any OpenChoreo plane charts. Install it in its own namespace:

helm upgrade --install external-secrets oci://ghcr.io/external-secrets/charts/external-secrets \
    --namespace external-secrets \
    --create-namespace \
    --version 1.3.2 \
    --set installCRDs=true

Wait for ESO to be ready:

kubectl wait --for=condition=available deployment/external-secrets -n external-secrets --timeout=180s

Multi-Cluster

For multi-cluster deployments, install 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-namespace
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:

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

note

ESO must already be installed in the cluster for the fake provider to work.

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 external-secrets deployment/external-secrets

For detailed troubleshooting guidance, see the ESO troubleshooting documentation.

Next Steps

• Deployment Topology: Configure SecretStore references in planes
• External Secrets Operator Documentation: Complete ESO reference