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 (OpenBao)

For development and testing, OpenBao (an open-source Vault fork) provides a lightweight secret backend that runs in-cluster. Install it in dev mode:

helm upgrade --install openbao oci://ghcr.io/openbao/charts/openbao \
    --namespace openbao \
    --create-namespace \
    --version 0.4.0 \
    --set server.image.tag=2.4.4 \
    --set injector.enabled=false \
    --set server.dev.enabled=true \
    --set server.dev.devRootToken=root \
    --wait --timeout 300s

After OpenBao is running, configure Kubernetes auth and create the ClusterSecretStore. See the getting started guide for the full setup steps.

To write secrets into OpenBao:

kubectl exec -n openbao openbao-0 -- sh -c '
  export BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root
  bao kv put secret/my-secret key=value
'

note

ESO must already be installed in the cluster before creating the ClusterSecretStore.

Alternative Backends

To use a different secret backend, create a ClusterSecretStore named default with your provider's configuration. All OpenChoreo planes reference this single store, so changing the backend is a single resource swap. See the ESO provider documentation for provider-specific setup.

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