Skip to main content
The External Secrets Operator (ESO) is the component that data plane failover uses to synchronize each Deployment’s Kubernetes secrets to and from your external secret backend — for example AWS Secrets Manager, GCP Secret Manager, or Hashicorp Vault — so that a Deployment’s secrets move with it between data plane clusters. Data plane failover has used ESO since APC 2.0, and APC 2.1 gives you more control over how ESO is granted access to Kubernetes.
The default ESO configuration (Mode 1) is available in every release that supports data plane failover, including APC 2.0. The hardened and isolated modes (Modes 2 and 3) and the other options described here — workload identity, self-managed CRDs, and pinned or disabled ServiceAccount token creation — require APC 2.1 or later.
By default, 2.1 closes the one significant gap from previous releases — it disables ESO’s unconditional ServiceAccount token creation — while otherwise keeping ESO’s standard chart RBAC, so upgrading requires no action for most installations. On top of that, 2.1 adds two opt-in modes that progressively tighten ESO’s Kubernetes access and identity, so you can match your organization’s security and compliance requirements. These changes ship as part of Data Plane Failover v2 and build on the data plane failover feature introduced in 2.0. This document explains what’s new and the modes you can choose from. For step-by-step setup, see Configure External Secrets Operator security. For the reference Kubernetes manifests, see External Secrets Operator security manifests reference.

​
What’s new in 2.1

  • Two opt-in modes for tighter ESO access: in addition to the default configuration, you can choose a hardened shared-identity mode or a customer-managed isolated-identity mode. See Choose a mode.
  • ServiceAccount token creation is off by default: the chart now disables ESO’s unconditional ServiceAccount token creation by default, closing the main gap from previous releases. The hardened and isolated modes go further, pinning token creation with Kubernetes resourceNames to a specific ServiceAccount. Hashicorp Vault backends are the exception and need it re-enabled — see Mode 1.
  • Workload identity support: you can authenticate ESO to your backend with workload identity such as AWS IAM Roles for Service Accounts (IRSA), GKE Workload Identity, or Vault Kubernetes auth, so no static credentials need to live in the cluster. Static credentials remain fully supported.
  • Customer-managed CRD installation: a chart value lets you install the ESO custom resource definitions (CRDs) yourself, for organizations where CRD installation is owned by a separate infrastructure team. See ESO CRD installation.

​
Backend authentication

Independent of the mode you choose, you authenticate ESO to your secret backend in one of two ways:
  • Static credentials. A Kubernetes Secret holding a cloud credential pair, as in previous releases.
  • Workload identity. AWS IRSA, GKE Workload Identity, or Vault Kubernetes auth, so no long-lived credentials are stored in the cluster.
Workload identity is the recommended option where your cloud supports it, but it isn’t required.

​
Choose a mode

APC supports three modes. Mode 1 is available in APC 2.0 and later; Modes 2 and 3 require APC 2.1 or later. A cluster runs entirely in one mode, and Deployments inherit the cluster’s mode.

​
Mode 1: Default shared identity

The default. ESO uses its standard chart-managed RBAC, with one change from previous releases: its unconditional ServiceAccount token creation is disabled by default, closing the main gap. All Deployments authenticate to the backend as one shared identity. No extra setup is required on upgrade, with one exception: if your backend is Hashicorp Vault, re-enable ESO’s ServiceAccount token creation (unpinned) with external-secrets.rbac.serviceAccountTokenCreate: true, because Vault’s Kubernetes auth needs ESO to mint a ServiceAccount token. You provision a single cluster-scoped ClusterSecretStore. See Secret store options.

​
Mode 2: Hardened shared identity

The same shared-identity model as Mode 1, with ESO’s Kubernetes access tightened. To use it, you:
  1. Set the two ESO sub-chart flags that disable its default RBAC and its ServiceAccount token-create rule.
  2. Apply the minimal ClusterRole and ClusterRoleBinding that Astronomer provides. These scope ESO’s cluster access and restrict ServiceAccount token creation, with resourceNames, to ESO’s own ServiceAccount in the astronomer namespace.
Mode 2 uses a shared secret store — either a ClusterSecretStore or a synced namespaced SecretStore. See Secret store options. Choose Mode 2 when you want a single shared backend identity but need ESO’s cluster access to be least-privilege and reviewed by your team.

​
Mode 3: Customer-managed isolated identity

Each Deployment gets its own backend identity, and you provision all of the required Kubernetes RBAC yourself. This mode builds on the namespace pools feature: you complete the standard namespace pools setup to pre-provision a fixed set of Deployment namespaces, then, in addition, pre-provision the ESO chain in each namespace — a per-namespace ServiceAccount (named after the pre-created namespace, since no Deployment exists yet), a namespaced SecretStore, and the per-namespace roles that grant ESO scoped access. The platform is installed without cluster-wide roles and can run with a limited-privilege user. You can substitute your own role definitions for the generated ones to match an internal RBAC standard. The SecretStore in every pool namespace must use the same name, which is the value set for global.dataPlaneFailover.externalSecretManagerName when you enable data plane failover per cluster. Only the name must match across namespaces. Each store’s contents — provider, region, and identity — can differ, which is what gives each Deployment its own backend identity.
Isolation boundaryKubernetes namespaces and RBAC are defense in depth. The authoritative isolation boundary is your backend policy: a per-Deployment IAM role or Vault policy that grants only that Deployment’s secret paths. If the backend policy is broad, ESO can read across Deployments regardless of namespace scoping.

​
Secret store options

Both shared-identity modes use a single secret store. Mode 1 uses a cluster-scoped ClusterSecretStore. Mode 2 can use either shape:
  • Cluster-scoped ClusterSecretStore. One store that every Deployment namespace references by name.
  • Namespaced SecretStore, synced by the platform. You create one SecretStore and its credentials Secret in the astronomer namespace with the astronomer.io/commander-sync annotation, and the platform syncs them into every Deployment namespace. This keeps a single shared backend identity while using namespaced stores instead of a cluster-wide one.
Both use the same shared backend identity, so they grant identical backend access. The difference is how the store is scoped in Kubernetes and which authentication methods it supports, not what it can reach. If your organization restricts cluster-scoped Kubernetes resources, choose the synced SecretStore — it keeps everything namespace-scoped while you still author and rotate a single store. The synced SecretStore supports static credentials only: if you need workload identity, use the ClusterSecretStore, which is also the simpler choice when cluster-scoped resources are acceptable. Mode 3 doesn’t use a shared store; each Deployment namespace has its own SecretStore.

​
ESO CRD installation

By default, the APC chart installs the ESO custom resource definitions. If CRD installation in your environment is owned by a separate infrastructure team, you can set the chart value that disables CRD creation and install the ESO CRDs yourself before installing the platform. This option is independent of the mode you choose and is most relevant to Modes 2 and 3. For the CRD bundle and command, see Install the ESO CRDs yourself.

​
How this interacts with data plane failover

  • A cluster runs entirely in one mode. Per-Deployment mixing within a cluster isn’t supported in 2.1.
  • In Mode 3, the objects you pre-provision — namespace, ServiceAccount, SecretStore, and roles — are preserved across a failover. The platform doesn’t delete the pool namespace during a move, and the pool slot is freed only when the Deployment is deleted.
  • At Deployment creation, and again on the destination cluster during a failover, the platform validates that the per-namespace ESO chain exists and reports any gaps.
  • For Mode 3, pre-provision the same chain, with matching namespace names, on every cluster a Deployment can fail over to, and make sure your backend trust spans those clusters.
  • For extra resiliency, you can run the ESO controller with multiple replicas and leader election, so it survives Pod failures and restarts. See Run ESO with multiple replicas.

​
Terminology