External Secrets Knowledge Patch

External Secrets Operator Knowledge Patch

Use this skill when designing, reviewing, upgrading, or troubleshooting External Secrets Operator (ESO) resources, providers, Helm installations, push workflows, generators, and templates.

How to use this skill

1. Identify the installed chart, controller, and CRD versions from the project.
2. Read the reference matching the resource or provider being changed.
3. Treat manifests, rendered charts, CRDs, controller flags, and observed status as the source of truth when they differ from this guidance.
4. Review breaking behavior and security implications before an upgrade.
5. Validate the rendered Kubernetes resources and provider-side effects.

Reference index

Breaking changes and migration checks

Removed providers

Alibaba and Device42 were removed in 2.0.0 because they were unsupported and unmaintained. Migrate every store that uses either provider before upgrading.

Removed template and generator behavior

• getHostByName is no longer available to templates. Replace DNS lookups with explicit data supplied to the template.
• The STSSessionToken generator no longer supports JWT-token authentication. Select another supported authentication path.
• Kubernetes-provider pushes replace the whole destination Secret; they do not merge with keys already present remotely.

Image registry migration

The default controller image moved 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 itself remains on GitHub Pages.

API assumptions to remove

• Use apiVersion: external-secrets.io/v1 in provider examples and current ExternalSecret manifests.
• Do not rely on omitted optional strategy fields being defaulted back into an ExternalSecret object.
• ClusterExternalSecret.spec.namespaceSelectors is the plural, ORed selector list. The singular selector and explicit namespaces field are deprecated.
• target.template.metadata replaces implicit metadata copying. Empty label or annotation maps intentionally suppress copying.
• Invalid ExternalSecretRewrite, generator reference types, and namespaced secretRef values are rejected earlier by validation.

ExternalSecret quick reference

Refresh policy

• Periodic is the default.
• With Periodic, a zero refreshInterval performs the initial fetch and create but does not update later.
• OnChange ignores the interval and responds only to metadata or spec changes.
• CreatedOnce repairs a changed or deleted target while its status survives; recreating the ExternalSecret resets that status and may overwrite the target.
• For a generated credential that must survive deletion and never be replaced, combine refreshPolicy: CreatedOnce, creationPolicy: Orphan, and an immutable target.

Manual refresh

Use the correct annotation for the object:

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-scoped annotation propagates to owned ExternalSecret objects. A manual refresh works only when the selected policy supports refreshing.

Creation and synchronization

• CreateOrMerge is accepted as a target creation policy.
• SecretStore.refreshInterval accepts duration strings.
• Sync windows can gate periodic ExternalSecret refreshes.
• Dynamic targets allow a source to choose its target at reconciliation time.
• objectMeta and ownerReferences propagate to target resources.
• A configurable source null-byte policy controls handling of embedded nulls.

Cluster fan-out

Each ExternalSecret created by a ClusterExternalSecret independently polls its provider. For many namespaces, fetch once into a dedicated namespace and replicate through a Kubernetes-provider ClusterSecretStore to reduce upstream calls.

Namespace selector entries are ORed. A collision with an existing ExternalSecret is a failed namespace; it is not taken over.

PushSecret quick reference

Input and lifecycle

A namespaced PushSecret selects exactly one source: a Kubernetes Secret or a generatorRef. It may apply template and templateFrom, then maps outgoing keys through data[].match.

• updatePolicy: Replace permits overwrites.
• deletionPolicy defaults to None; use Delete for provider cleanup.
• A referenced SecretStore receives a finalizer when deletion policy requires remote cleanup.
• Inspect the generated PushSecret status for provider synchronization failures; ClusterPushSecret readiness reports child provisioning, not the provider write result.

Bulk expansion with dataTo

spec.dataTo expands all or regexp-selected keys from the selected Kubernetes Secret. Each entry needs a storeRef, and the store must also appear in secretStoreRefs.

• Without remoteKey, each match becomes a separate remote secret or variable.
• With remoteKey, all matches become one JSON object and rewrites do not apply.
• Template output precedes expansion; conversion precedes matching and rewrite.
• Explicit spec.data wins for the same original, unconverted source key.
• Invalid regexps and duplicate remote keys fail; no matches is a successful no-op.
• IfNotExists applies to each expanded target, and Delete tracks all of them for cleanup.

Read Push workflows before depending on a provider's write, merge, existence-check, or deletion behavior; capabilities vary by provider.

Helm and operational quick reference

CRDs and controllers

CRD creation, reconciliation, and conversion are separate switches. Pair every disabled crds.create* value with the corresponding process* value. If the webhook is disabled, disable CRD conversion too, or the API server will call a missing conversion endpoint.

Namespace scope and RBAC

scopedRBAC: true with scopedNamespace creates a namespace-only installation and implicitly disables cluster-scoped controllers. When scopedNamespace is omitted, it defaults to the Helm release namespace.

Provider authentication through serviceAccountRef needs TokenRequest access. Disable the broad token-creation rule with rbac.serviceAccountTokenCreate: false, then grant serviceaccounts/token creation only for the referenced accounts by resourceNames.

genericTargets.enabled expands controller authority to ConfigMaps and every configured extra API resource. Review each API group, verb, encryption rule, and admission policy before enabling it.

Health, metrics, and availability

• Controller, cert-controller, and webhook liveness probes are configurable; readiness and webhook startup probes are also configurable.
• Metrics can use secure serving plus FilterProvider authentication and authorization, but TLS and authentication are not secure-by-default chart assumptions.
• The controller defaults to one replica; availability controls such as extra replicas, probes, and PodDisruptionBudgets must be enabled deliberately.
• Give independent deployments in the same namespace distinct leader-election IDs; lease timing and store requeue timing are configurable.
• PDB percentage and explicit zero values render correctly.

Network and pod security

Restricted pod security defaults do not make the chart a complete hardened deployment. NetworkPolicy is optional, and default role aggregation and token permissions require review. Limit egress to DNS, the Kubernetes API, and the selected provider endpoints; restrict ClusterSecretStore references and deny unused providers where policy tooling allows it.

Provider selection quick reference

Provider maturity and individual capabilities are separate questions. Before choosing a provider, verify store validation, find, extraction, metadata, referent authentication, push, merge, and delete support independently.

Notable current choices include dedicated OpenBao support, AWS Certificate Manager, Barbican, Cloud.ru Secret Manager, Devolutions Server, Nebius MysteryBox, OVHcloud, Volcengine, and BeyondTrust WorkloadCredentials. Custom builds can use provider build tags to exclude providers that are not needed.

For provider-specific authentication, lookup, path, replication, metadata, cache, error, or write semantics, load the appropriate provider reference before editing a store.

Verification checklist

• Confirm the installed controller, chart, and CRDs agree.
• Render Helm output and inspect RBAC, probes, PDBs, Services, webhook configuration, conversion, NetworkPolicy, scheduler, and RuntimeClass.
• Validate namespace boundaries for stores, referents, provider credentials, and cluster-scoped fan-out.
• Check update and deletion policies against the provider's actual write and delete capabilities.
• Inspect ExternalSecret, PushSecret, and store conditions and events; provider errors are not always equivalent to missing secrets.
• Test metadata-only updates, target recreation, key removal, replication, and cleanup in a non-production namespace before rollout.
• Verify release images by immutable digest and validate their signature, provenance, and SBOM attestations when artifact identity matters.