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/v1kind: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.
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:
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: DeletewithcreationPolicyMerge,CreateOrMergeorNone.deletionPolicy: MergewithcreationPolicy: 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.generatorRefis not implemented fordataand will be removed. Usespec.dataFrom[].sourceRef.generatorRefinstead.
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 inkey. - 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¶
- Getting Started with Secrets
- Upstream:
ExternalSecretAPI - Upstream: Lifecycle, creation and deletion policies
- Upstream: Fetching multiple secrets with
find - Upstream: Rewriting keys in
dataFrom - Upstream: Templating
- Upstream: Decoding strategies
- Upstream: HashiCorp Vault provider
- Upstream:
ExternalSecretCRD at v2.15.0