Skip to content

Reference: ExternalSecret CRD

An ExternalSecret tells the External Secrets Operator which values to fetch from a secret store and how to write them into a Kubernetes Secret in your namespace. The operator keeps the Secret in sync with the store according to the refresh policy you choose.

  • apiVersion: external-secrets.io/v1
  • kind: ExternalSecret
  • Scope: Namespaced
  • Short name: es (for example, kubectl get es)

This page documents External Secrets Operator v2.15.0. In this version, external-secrets.io/v1beta1 is no longer served, so the Kubernetes API rejects manifests that use it. Use external-secrets.io/v1.

Example

The following manifest fetches one value with data, all key-value pairs of a second secret with dataFrom, and renders a Secret with an extra connection string built by a template.

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: my-application-credentials
  namespace: <your-namespace>
spec:
  # The ClusterSecretStore that connects to the shared OpenBao store
  secretStoreRef:
    kind: ClusterSecretStore
    name: openbao

  refreshPolicy: Periodic
  refreshInterval: 15m

  data:
    # Fetch a single property from a secret
    - secretKey: api-key
      remoteRef:
        key: k8s/<cluster-name>/<your-namespace>/my-app-secret
        property: api-key

  dataFrom:
    # Fetch every key-value pair from a secret
    - extract:
        key: k8s/<cluster-name>/<your-namespace>/database

  target:
    name: my-application-credentials
    creationPolicy: Owner
    deletionPolicy: Retain
    template:
      type: Opaque
      # Keep the fetched keys and add the templated ones
      mergePolicy: Merge
      metadata:
        labels:
          app.kubernetes.io/name: my-application
      data:
        DATABASE_URL: "postgres://{{ .username }}:{{ .password }}@{{ .host }}:5432/app"

The database secret in this example must contain the keys username, password and host. If you manage this manifest with Helm, escape the {{ }} expressions so that Helm does not render them. See the upstream templating guide.

Specification (spec)

Field Type Description
secretStoreRef object Optional. The store to fetch data from. See spec.secretStoreRef. Required unless every entry in data and dataFrom sets its own sourceRef.
data []object Optional. Individual values to fetch, each written to one key in the target Secret. See spec.data.
dataFrom []object Optional. Fetch many values at once, by extracting all properties of one secret or by finding secrets by name or tag. Entries are merged in the order you list them. See spec.dataFrom.
target object Optional. The Secret to create and how to build it. Default: creationPolicy: Owner, deletionPolicy: Retain. See spec.target.
refreshPolicy string Optional. When the operator syncs the Secret. One of Periodic, OnChange, CreatedOnce. Behaves as Periodic when unset. See Refresh Policies.
refreshInterval string Optional. How often to fetch the values again, as a Go duration (ns, us, ms, s, m, h), for example 10m or 1h0m0s. Only used with Periodic. 0s fetches once and never updates. Default: 1h0m0s.
syncWindows object Optional. Restricts when periodic refreshes may run. See spec.syncWindows.

You must set at least one of data or dataFrom. When both are set, keys from data take precedence over keys from dataFrom. Each secretKey in data must be unique.

spec.secretStoreRef

Field Type Description
kind string Optional. SecretStore or ClusterSecretStore. Default: SecretStore. Set it to ClusterSecretStore to use the platform store.
name string Optional. The name of the store.

The same object is used by sourceRef.storeRef in data and dataFrom.

spec.data

Each entry maps one remote value to one key in the target Secret.

Field Type Description
secretKey string Required. The key in the Kubernetes Secret. 1-253 characters, matching ^[-._a-zA-Z0-9]+$.
remoteRef object Required. The remote value to fetch. See spec.data[].remoteRef.
sourceRef object Optional. Overrides spec.secretStoreRef for this entry. Set exactly one of storeRef (same fields as spec.secretStoreRef) or generatorRef (deprecated here, see Deprecated Fields).

spec.data[].remoteRef

Field Type Description
key string Required. The path of the secret in the provider, for example k8s/<cluster-name>/<your-namespace>/my-app-secret.
property string Optional. A single property of the secret, if the value is a map. With OpenBao, this is a gjson expression, so foo.nested.bar selects a nested value. When empty, the whole secret is returned as JSON.
version string Optional. A specific version of the secret, if the provider supports versions.
decodingStrategy string Optional. How to decode the fetched value. One of None, Base64, Base64URL, Auto. Default: None. See Decoding Strategies.
conversionStrategy string Optional. How to convert key names. One of Default, Unicode. Default: Default. See Conversion Strategies.
metadataPolicy string Optional. Fetch returns the secret's metadata (tags or labels) instead of its value. One of None, Fetch. Default: None. With OpenBao, this requires the KV version 2 engine.
nullBytePolicy string Optional. Fail stops the sync if the value contains NUL bytes. One of Ignore, Fail. When unset, NUL bytes are allowed.

spec.dataFrom

Each entry fetches a set of key-value pairs. Set one of extract, find or sourceRef.generatorRef per entry. You can combine extract or find with sourceRef.storeRef to read from a different store.

Field Type Description
extract object Optional. Fetch one secret and write each of its properties as a separate key. See spec.dataFrom[].extract.
find object Optional. Fetch every secret that matches a name pattern or a set of tags. See spec.dataFrom[].find.
rewrite []object Optional. Rename the fetched keys before they are written. Operations apply in order, each to the output of the previous one. See spec.dataFrom[].rewrite.
sourceRef object Optional. Set exactly one of storeRef (same fields as spec.secretStoreRef) or generatorRef (see spec.dataFrom[].sourceRef.generatorRef).

spec.dataFrom[].extract

Field Type Description
key string Required. The path of the secret in the provider.
property string Optional. Extract the properties of a nested map instead of the top level.
version string Optional. A specific version of the secret, if the provider supports versions.
decodingStrategy string Optional. One of None, Base64, Base64URL, Auto. Default: None.
conversionStrategy string Optional. One of Default, Unicode. Default: Default.
metadataPolicy string Optional. One of None, Fetch. Default: None.
nullBytePolicy string Optional. One of Ignore, Fail. When unset, NUL bytes are allowed.

spec.dataFrom[].find

find writes each matching secret as one key in the target Secret. The key is the secret's path, with characters that are not valid in a Secret key replaced by _. With OpenBao, the search is recursive and you can match on name or on custom_metadata tags.

Field Type Description
path string Optional. The root path to search from. Narrow the search with this field to reduce load and shorten the resulting key names.
name.regexp string Optional. A regular expression that the secret name must match.
tags map[string]string Optional. Tags that a secret must all have to match.
decodingStrategy string Optional. One of None, Base64, Base64URL, Auto. Default: None. Applies to the whole secret value.
conversionStrategy string Optional. One of Default, Unicode. Default: Default.
nullBytePolicy string Optional. One of Ignore, Fail. When unset, NUL bytes are allowed.

spec.dataFrom[].rewrite

Each item sets exactly one of regexp, transform or merge. Keys that no operation matches keep their original name. Rewrites run before the conversion strategy is applied.

Field Type Description
regexp.source string Required for regexp. A Go (RE2) regular expression to match against each key.
regexp.target string Required for regexp. The replacement, which can use capture groups such as $1.
transform.template string Required for transform. A Go template that produces the new key. {{ .value }} is the current key name. You can use the template helper functions.
merge.strategy string Optional. Extract parses every value as JSON and moves its key-value pairs to the top level. JSON parses every value as JSON and merges the pairs into a single key named by into. Default: Extract.
merge.into string Optional. The target key for the JSON strategy. Required when strategy is JSON, ignored otherwise.
merge.conflictPolicy string Optional. What happens when two values contain the same key. One of Error, Ignore. Default: Error.
merge.priority []string Optional. Keys to process last, in the listed order, so their values win conflicts. Other keys are processed in alphabetical order.
merge.priorityPolicy string Optional. What happens when a key in priority does not exist. One of Strict (fail), IgnoreNotFound. Default: Strict.

The following entry extracts all properties of a secret and turns names such as api-key into environment variable style names such as APP_API_KEY:

dataFrom:
  - extract:
      key: k8s/<cluster-name>/<your-namespace>/my-app-secret
    rewrite:
      - regexp:
          source: "-"
          target: "_"
      - transform:
          template: "APP_{{ .value | upper }}"

spec.dataFrom[].sourceRef.generatorRef

A generator creates values, such as a random password, instead of reading them from a store. When sourceRef points to a generator, you cannot use extract or find in the same entry.

Field Type Description
kind string Required. The generator kind. One of ACRAccessToken, BeyondtrustWorkloadCredentialsDynamicSecret, ClusterGenerator, CloudsmithAccessToken, ECRAuthorizationToken, Fake, GCRAccessToken, GithubAccessToken, GitlabDeployToken, Grafana, MFA, Password, QuayAccessToken, SSHKey, STSSessionToken, UUID, VaultDynamicSecret, Webhook.
name string Required. The name of the generator resource in your namespace.
apiVersion string Optional. The API version of the generator. Default: generators.external-secrets.io/v1alpha1.

spec.target

Field Type Description
name string Optional. The name of the Secret to manage. Default: the metadata.name of the ExternalSecret.
creationPolicy string Optional. How the operator creates and owns the Secret. One of Owner, Orphan, Merge, CreateOrMerge, None. Default: Owner. See Creation Policies.
deletionPolicy string Optional. What happens to the Secret when the secrets are deleted in the provider. One of Retain, Delete, Merge. Default: Retain. See Deletion Policies.
immutable boolean Optional. Marks the Secret as immutable. Once the Secret exists, the operator never rewrites its data. A deleted Secret is still recreated.
template object Optional. A blueprint for the Secret. See spec.target.template.
manifest object Optional. Creates a resource of another kind, such as a ConfigMap, instead of a Secret. Set apiVersion and kind (both required). This is an alpha feature that the operator only allows when it runs with the --unsafe-allow-generic-targets flag.

spec.target.template

The template uses Go templates. Every key that data and dataFrom fetched is available as {{ .<key> }}. Use {{ index . "my-key" }} for keys that contain dashes. Referencing a key that does not exist fails the sync. Each rendered value must be smaller than 1 MiB.

Field Type Description
type string Optional. The Secret type, for example Opaque, kubernetes.io/tls or kubernetes.io/dockerconfigjson. The operator rejects bootstrap.kubernetes.io/token, and rejects kubernetes.io/service-account-token when the template sets the service account annotation.
data map[string]string Optional. Keys of the Secret, with templated values.
templateFrom []object Optional. Templates loaded from a ConfigMap, a Secret or a literal. See spec.target.template.templateFrom.
metadata.labels map[string]string Optional. Labels to set on the Secret.
metadata.annotations map[string]string Optional. Annotations to set on the Secret.
metadata.finalizers []string Optional. Finalizers to set on the Secret.
mergePolicy string Optional. Replace writes only the templated keys. Merge also writes the fetched keys, and the templated keys win on conflict. Default: Replace.
engineVersion string Optional. The template engine version. Only v2 is allowed. Default: v2.

spec.target.template.templateFrom

Each item sets one of configMap, secret or literal.

Field Type Description
configMap.name string Required for configMap. A ConfigMap in the same namespace that holds templates.
configMap.items []object Required for configMap. The keys to use. Each item has key (required) and templateAs.
secret.name string Required for secret. A Secret in the same namespace that holds templates.
secret.items []object Required for secret. Same structure as configMap.items.
items[].key string Required. The key in the ConfigMap or Secret that holds the template.
items[].templateAs string Optional. Values renders the template as the value of a key with the same name. KeysAndValues renders the template as a set of key: value lines. Default: Values.
literal string Optional. An inline template that renders to key: value pairs, so you can template key names as well as values.
target string Optional. Where to write the result. For a Secret, one of Data, Annotations, Labels. When spec.target.manifest is set, this can be a path such as spec.database.config. Default: Data.
valuesDecodingStrategy string Optional. Decode the rendered values. One of None, Base64, Base64URL, Auto. Default: None.

spec.syncWindows

Sync windows restrict when periodic refreshes may run. They are evaluated in UTC and only apply to the Periodic refresh policy. The operator still checks at every refreshInterval, so set refreshInterval shorter than the shortest window duration or a window can pass without a sync.

Field Type Description
kind string Required. allow permits syncs only while a window is open. deny blocks syncs while a window is open.
windows []object Required. At least one window.
windows[].schedule string Required. A 5-field cron expression in UTC, or a shorthand such as @daily or @every 1h. Marks the start of each window.
windows[].duration string Required. How long the window stays open after each start, for example 8h.

The operator ignores a window with a schedule it cannot parse, so a typo does not block syncs permanently.

syncWindows:
  kind: deny
  windows:
    - schedule: "0 2 * * 6"  # Saturdays at 02:00 UTC
      duration: 2h

Behavior

Refresh Policies

Policy Behavior
Periodic Creates the Secret and updates it every refreshInterval and whenever the ExternalSecret changes. With refreshInterval: 0s, it behaves like CreatedOnce.
OnChange Creates the Secret and updates it only when the ExternalSecret metadata or spec changes. Ignores refreshInterval.
CreatedOnce Syncs once on the first reconcile of the ExternalSecret and never refreshes. Deleting and recreating the ExternalSecret triggers a new sync. Combine with target.immutable: true to keep the first value.

To force a sync with Periodic or OnChange, change an annotation on the ExternalSecret:

kubectl annotate es my-application-credentials force-sync=$(date +%s) --overwrite

Creation Policies

Policy Behavior
Owner Creates the Secret with an ownerReference to the ExternalSecret. Kubernetes deletes the Secret when you delete the ExternalSecret. Fails if a Secret with the same name is owned by something else.
Orphan Creates and updates the Secret without an ownerReference. The Secret remains when you delete the ExternalSecret. Manual edits to the Secret are overwritten on the next sync.
Merge Does not create the Secret. Merges the fetched keys into an existing Secret and waits until it exists.
CreateOrMerge Creates the Secret if it is missing, otherwise merges the fetched keys into it. Does not set an ownerReference.
None Does not create or update the Secret.

Deletion Policies

The deletion policy applies when the secrets no longer exist in the provider. The operator detects this on the next sync.

Policy Behavior
Retain Keeps the Secret. The ExternalSecret reports SecretSyncedError.
Delete Deletes the Secret once all its provider secrets are gone. Only works with creationPolicy: Owner.
Merge Removes the missing keys from the Secret but keeps the Secret itself.

The operator rejects these combinations:

  • deletionPolicy: Delete with creationPolicy Merge, CreateOrMerge or None.
  • deletionPolicy: Merge with creationPolicy: None.

Decoding Strategies

Strategy Behavior
None Writes the value as fetched.
Base64 Decodes the value as standard Base64. Fails if the value is not valid Base64.
Base64URL Decodes the value as URL-safe Base64. Fails if the value is not valid.
Auto Tries Base64 and Base64URL, and falls back to None. Plain values whose length is divisible by 4, such as 1234, can be decoded by mistake.

Conversion Strategies

Default replaces characters that are not valid in a Secret key with _. Unicode replaces them with _UXXXX_, where XXXX is the character's Unicode code point, which avoids most key collisions. For example, a/c becomes a_U2215_c instead of a_c.

Deprecated Fields

  • spec.data[].sourceRef.generatorRef is not implemented for data and will be removed. Use spec.dataFrom[].sourceRef.generatorRef instead.

Status (status)

Field Type Description
conditions []object The Ready condition shows whether the last sync succeeded. Its reason is, for example, SecretSynced, SecretSyncedError, SecretMissing or SecretOwnedByOther, and its message explains errors.
refreshTime string When the operator last fetched the values and updated the Secret.
syncedResourceVersion string The version of the ExternalSecret that was last synced.
binding.name string The name of the generated Secret, for Service Binding consumers.

kubectl get es shows the store, refresh interval, status, ready state and last sync time. Use kubectl describe es <name> to see the condition message and events.

The ClusterSecretStore

You do not create a store yourself. The platform provides a ClusterSecretStore named openbao that connects to the shared OpenBao secrets store. Reference it from spec.secretStoreRef with kind: ClusterSecretStore and name: openbao.

Platform Notes

  • Store your secrets in the OpenBao KV secrets engine under k8s/<cluster-name>/<your-namespace>/, and use that path in key.
  • The path determines the access policy that applies to the secret. See Secret Path Policies.
  • We install, configure and maintain the External Secrets Operator for you.

Further Reading