> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# External Secrets Operator security

The External Secrets Operator (ESO) is the component that [data plane failover](/docs/astro-private-cloud/v-2-x/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.

<Note>
  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.
</Note>

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](/docs/astro-private-cloud/v-2-x/configure-external-secrets-operator-security). For the reference Kubernetes manifests, see [External Secrets Operator security manifests reference](/docs/astro-private-cloud/v-2-x/external-secrets-operator-security-manifests).

## 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](#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](#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                                          | Mode 2: Hardened shared identity                                                                                                                                             | Mode 3: Customer-managed isolated identity                                                     |
| ----------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Backend identity**    | One shared identity                                                      | One shared identity                                                                                                                                                          | A separate identity per Deployment                                                             |
| **ESO Kubernetes RBAC** | Chart default, created automatically, with token creation off by default | You disable the chart's ESO RBAC and token-create, then apply Astronomer's minimal `ClusterRole` and `ClusterRoleBinding` with token creation pinned to ESO's ServiceAccount | You pre-provision all per-namespace roles                                                      |
| **Secret store**        | `ClusterSecretStore`                                                     | `ClusterSecretStore`, or a namespaced `SecretStore` synced by the platform                                                                                                   | A per-namespace `SecretStore` in each Deployment namespace                                     |
| **Namespace pools**     | Not required                                                             | Not required                                                                                                                                                                 | Required                                                                                       |
| **Extra setup**         | None                                                                     | Two chart flags plus applying the provided manifests                                                                                                                         | Pre-provision namespaces, per-namespace RBAC, and per-namespace stores                         |
| **Best for**            | Existing installs and the simplest setup                                 | A single shared identity with tightened, reviewable ESO cluster access                                                                                                       | Per-Deployment identity isolation, or clusters that require you to provision all RBAC yourself |

### 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](#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](#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](/docs/astro-private-cloud/v-2-x/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.

<Warning>
  **Isolation boundary**

  Kubernetes 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.
</Warning>

## 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.

|                            | `ClusterSecretStore`                                                                         | Synced `SecretStore`                                                                                                             |
| -------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Object scope**           | A single cluster-scoped object                                                               | A namespaced object in each Deployment namespace, created and kept in sync by the platform                                       |
| **Backend authentication** | Static credentials or workload identity (IRSA, GKE Workload Identity, Vault Kubernetes auth) | Static credentials only                                                                                                          |
| **RBAC to manage it**      | Requires cluster-scoped permissions                                                          | Namespace-scoped only — no cluster-scoped secret-store object exists                                                             |
| **Setup and upkeep**       | Lowest: one object, created once                                                             | You author one store in the `astronomer` namespace, and the platform replicates it to each Deployment namespace                  |
| **Choose when**            | Cluster-scoped resources are acceptable and you want the simplest setup                      | Your security or compliance policy limits or reviews cluster-scoped objects, or you want the secret store governed per namespace |

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](/docs/astro-private-cloud/v-2-x/external-secrets-operator-security-manifests#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](/docs/astro-private-cloud/v-2-x/configure-external-secrets-operator-security#run-eso-with-multiple-replicas).

## Terminology

| Term                                 | Meaning                                                                                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| External Secrets Operator (ESO)      | The Kubernetes operator that syncs secrets between the cluster and an external secret backend.                                                                    |
| `ClusterSecretStore` / `SecretStore` | ESO custom resources that describe where to connect and which identity to authenticate as. `ClusterSecretStore` is cluster-scoped; `SecretStore` is namespaced.   |
| Namespace pools                      | An APC feature (`global.namespaceManagement.namespacePools`) that pre-provisions a fixed set of Deployment namespaces. Mode 3 is built on it.                     |
| Workload identity                    | Authenticating to a cloud or Vault without static credentials (AWS IRSA, GKE Workload Identity, Vault Kubernetes auth).                                           |
| `<release-name>`                     | The Helm release name you install the Astronomer chart with (for example `astronomer`). It prefixes the ESO ServiceAccount and RBAC object names in these guides. |

## Related documentation

* [Configure External Secrets Operator security](/docs/astro-private-cloud/v-2-x/configure-external-secrets-operator-security)
* [External Secrets Operator security manifests reference](/docs/astro-private-cloud/v-2-x/external-secrets-operator-security-manifests)
* [Data plane failover](/docs/astro-private-cloud/v-2-x/data-plane-failover)
* [Enable data plane failover](/docs/astro-private-cloud/v-2-x/enable-data-plane-failover)
* [Configure a Kubernetes namespace pool](/docs/astro-private-cloud/v-2-x/namespace-pools)