External Secrets Knowledge Patch

External Secrets Operator Compatibility

Use this skill when designing, upgrading, operating, or troubleshooting External Secrets Operator (ESO) resources, providers, generators, Helm deployments, and push workflows. Check the installed chart and controller versions before applying version-dependent guidance, and trust live CRDs and rendered manifests when they differ from examples.

Topic index

Breaking changes and migrations

Removed providers

Alibaba and Device42 were removed in 2.0.0 because they were unsupported and unmaintained. Migrate any stores that use them before upgrading.

Image registry migration

The chart default moved in 1.1.0 from oci.external-secrets.io/external-secrets/external-secrets to ghcr.io/external-secrets/external-secrets. Update pinned or overridden image repositories; the chart repository remains on GitHub Pages.

Flux OCI chart extraction

From 2.2.0, a Flux OCIRepository must select and extract the Helm chart content layer:

spec:
  url: oci://ghcr.io/external-secrets/charts/external-secrets
  layerSelector:
    mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip
    operation: extract

Removed template and generator behavior

• getHostByName was removed from template functions in 2.3.0. Replace templates that perform DNS lookups.
• The STSSessionToken generator lost JWT-token authentication in 0.19.0. Choose another supported authentication route.
• Kubernetes-provider pushes replace the complete remote Secret from 2.7.0; keys absent from the pushed Secret are removed instead of retained.
• Optional ExternalSecret strategy fields are no longer defaulted into the stored object in 2.9.0. Do not require omitted fields to be written back.

API transition

Provider examples use external-secrets.io/v1. Legacy beta-version serving became configurable in 1.3.0; treat it as a migration aid, not a reason to postpone manifest conversion.

Reconciliation quick reference

Refresh policies

• Periodic is the default. A zero refreshInterval performs the initial fetch and create but no later update.
• OnChange ignores the interval and reacts to ExternalSecret metadata or spec changes.
• CreatedOnce repairs a changed or deleted target while the same ExternalSecret survives. Recreating the resource resets status and can rewrite an existing target.
• For a generated credential intended to survive source deletion and reject replacement, combine refreshPolicy: CreatedOnce, creationPolicy: Orphan, and target.immutable: true.

Manual refresh

Use different annotation names:

kubectl annotate es my-es force-sync=$(date +%s) --overwrite
kubectl annotate ces my-ces external-secrets.io/force-sync=$(date +%s) --overwrite

Changing or deleting the cluster annotation propagates to owned resources. Read API and reconciliation for metadata, selectors, retry settings, status, dynamic targets, and sync windows.

Creation and store behavior

• CreateOrMerge is accepted as an ExternalSecret target creation policy from 2.8.0.
• SecretStore.refreshInterval accepts duration strings from 2.8.0.
• A store can be marked deprecated from 1.2.0.
• A SecretStore can report unknown status when its state cannot be determined.
• Stores without an explicit maintainer emit controller and admission warnings; the maintenance annotation suppresses only the controller event.

Push quick reference

Use exactly one selector source in a namespaced PushSecret: a Kubernetes Secret or generatorRef. Transform it with template or templateFrom, then map outgoing keys through data[].match. updatePolicy: Replace allows overwrites; deletionPolicy defaults to None, so set Delete when remote cleanup is required.

dataTo bulk expansion, introduced in the 2.3-datato batch, can select all source keys or a regexp-filtered subset. Each entry needs a storeRef that also appears in secretStoreRefs. Without remoteKey, matches become separate remote secrets; with remoteKey, they become one JSON object.

Expansion applies the template first, converts keys before matching and rewriting, and gives an explicit data entry precedence for the same original Kubernetes key. Invalid regexps, duplicate remote keys, and conflicting sources fail reconciliation; no matches is a successful no-op. Read PushSecret workflows before relying on deletion, fan-out, cross-namespace, or provider-specific behavior.

Helm and operations quick reference

Keep CRDs and controllers aligned

Disabling CRD creation does not disable its reconciler. Pair each disabled crds.create* value with the matching process* value. If the webhook is disabled, disable CRD conversion too, or the API server calls a missing endpoint.

crds:
  createPushSecret: false
  conversion:
    enabled: false
processPushSecret: false
webhook:
  create: false

Availability is mostly opt-in

The controller defaults to one replica; its liveness, readiness, and PDB are not enabled by default. Webhook and cert-controller readiness are enabled, but their liveness and PDB remain off. For HA, enable replicas and leader election and use a distinct leaderElectionID for each ESO deployment in a namespace. Lease timing is configurable from 2.8.0, and a lower-level --leader-election-id flag exists from 2.4.0.

Metrics, logs, and probes

• Secure metrics serving arrived in 0.20.0; metrics authentication and authorization through FilterProvider arrived in 2.5.0.
• The controller gained a liveness probe in 0.20.0, configurable readiness in 2.2.0, and cert-controller/webhook liveness in 2.4.0.
• Webhook startup probes are configurable from 2.8.0.
• Keeper exposes provider_api_calls_count from 2.6.0.
• Secret deletions and data-key changes are logged from 2.7.0.

Read Helm and operations for all chart values, probe details, RBAC gates, scheduling, and observability changes.

Security quick reference

Do not infer a hardened deployment from the restricted default pod security context. NetworkPolicies and metrics TLS/authentication are off by default, while broad ServiceAccount-token creation and role aggregation are on. Limit egress to DNS, the Kubernetes API, and required provider endpoints; constrain store access, remote-key prefixes, enabled providers, and generic-target permissions.

For namespace-only installs, set both scopedRBAC: true and scopedNamespace. Disable blanket token creation with rbac.serviceAccountTokenCreate: false, then grant serviceaccounts/token creation by resourceNames for each referenced ServiceAccount. Treat genericTargets.enabled as an explicit controller-privilege expansion.

Verify release images by immutable digest. Keyless signatures, SLSA provenance, and SPDX JSON SBOM attestations are available, but release artifacts and signatures are outside the compatibility guarantee. Read Security and support before making support, hardening, or provider-maturity assumptions.

Provider selection quick reference

Provider maturity does not imply capability parity. Confirm each provider's support for find, metadata, referent authentication, validation, push, and merge/delete operations. In particular:

• OpenBao has a dedicated provider from 2.7.0; older configurations can use Vault compatibility, but new configurations can use OpenBao trust, namespaces, userPass, or appRole directly.
• Vault supports Pod Identity, GCP Workload Identity, token caching with expiry validation, namespace-aware client caching, TLS roles, dynamic GET parameters, and push operations; load the provider reference for version details.
• AWS metadata synchronization occurs even when a secret value is unchanged, and explicit credentials no longer fall back to EC2 instance metadata.
• Kubernetes push replaces the whole Secret, while whole-Secret deletion and SecretExists are separately supported.
• A provider classified read-write can receive PushSecret; unsupported Conjur push and delete calls return explicit errors.

Use Cloud and Vault providers or Integration providers for the exact provider capability and authentication changes.

Templates and generators quick reference

Templates support custom delimiters, native values in value scope, templated dataFrom JSONPath, certSANs, hexadecimal conversion with hexdec, slice notation, mixed-case generic target paths, decoded templateFrom values, and template-defined finalizers. Source null-byte handling is configurable. Review Templates, generators, and CLI for generator-specific fields, removed behavior, and rendering commands.