helm-external-secrets/docs/api/externalsecret.md

The ExternalSecret describes what data should be fetched, how the data should be transformed and saved as a Kind=Secret:

• tells the operator what secrets should be synced by using spec.data to explicitly sync individual keys or use spec.dataFrom to get all values from the external API.
• you can specify how the secret should look like by specifying a spec.target.template

Template

When the controller reconciles the ExternalSecret it will use the spec.template as a blueprint to construct a new Kind=Secret. You can use golang templates to define the blueprint and use template functions to transform secret values. You can also pull in ConfigMaps that contain golang-template data using templateFrom. See advanced templating for details.

Update behavior with 3 different refresh policies

You can control how and when the ExternalSecret is refreshed by setting the spec.refreshPolicy field. If not specified, the default behavior is Periodic.

CreatedOnce

With refreshPolicy: CreatedOnce, the controller will:

• Create the Kind=Secret only if it does not exist yet
• Never update the Kind=Secret afterwards if the source data changes
• Update/ Recreate the Kind=Secret if it gets changed/Deleted
• Useful for immutable credentials or when you want to manage updates manually

Example:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: example
spec:
  refreshPolicy: CreatedOnce
  # other fields...

Periodic

With refreshPolicy: Periodic (the default behavior), the controller will:

• Create the Kind=Secret if it doesn't exist
• Update the Kind=Secret regularly based on the spec.refreshInterval duration
• When spec.refreshInterval is set to zero, it will only create the secret once and not update it afterward
• When spec.refreshInterval is set to a value greater than zero, the controller will update the Kind=Secret at the specified interval or when the ExternalSecret specification changes

Example:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: example
spec:
  refreshPolicy: Periodic
  refreshInterval: 1h0m0s  # Update every hour
  # other fields...

OnChange

With refreshPolicy: OnChange, the controller will:

• Create the Kind=Secret if it doesn't exist
• Update the Kind=Secret only when the ExternalSecret's metadata or specification changes
• This policy is independent of the refreshInterval value
• Useful when you want to manually control when the secret is updated, by modifying the ExternalSecret resource

Example:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: example
spec:
  refreshPolicy: OnChange
  # other fields...

Manual Refresh

If supported by the configured refreshPolicy, you can manually trigger a refresh of the Kind=Secret by updating the annotations of the ExternalSecret:

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

Features

Individual features are described in the Guides section:

• Find many secrets / Extract from structured data
• Templating
• Using Generators
• Secret Ownership and Deletion
• Key Rewriting
• Decoding Strategy

Example

Take a look at an annotated example to understand the design behind the ExternalSecret.

{% include 'full-external-secret.yaml' %}