ExternalSecret
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 usespec.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
The Kind=Secret
is updated when:
- the
spec.refreshInterval
has passed and is not0
- the
ExternalSecret
'slabels
orannotations
are changed - the
ExternalSecret
'sspec
has been changed
You can trigger a secret refresh by using kubectl or any other kubernetes api client:
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
.
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: "hello-world"
# labels and annotations are copied over to the
# secret that will be created
labels:
acme.org/owned-by: "q-team"
annotations:
acme.org/sha: 1234
spec:
# Optional, SecretStoreRef defines the default SecretStore to use when fetching the secret data.
secretStoreRef:
name: aws-store
kind: SecretStore # or ClusterSecretStore
# RefreshInterval is the amount of time before the values reading again from the SecretStore provider
# Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h" (from time.ParseDuration)
# May be set to zero to fetch and create it once
refreshInterval: "1h"
# the target describes the secret that shall be created
# there can only be one target per ExternalSecret
target:
# The secret name of the resource
# Defaults to .metadata.name of the ExternalSecret
# It is immutable
name: application-config
# Enum with values: 'Owner', 'Merge', or 'None'
# Default value of 'Owner'
# Owner creates the secret and sets .metadata.ownerReferences of the resource
# Merge does not create the secret, but merges in the data fields to the secret
# None does not create a secret (future use with injector)
creationPolicy: 'Merge'
# DeletionPolicy defines how/when to delete the Secret in Kubernetes
# if the provider secret gets deleted.
# Valid values are Delete, Merge, Retain
deletionPolicy: "Retain"
# Specify a blueprint for the resulting Kind=Secret
template:
type: kubernetes.io/dockerconfigjson # or TLS...
metadata:
annotations: {}
labels: {}
# Use inline templates to construct your desired config file that contains your secret
data:
config.yml: |
database:
connection: postgres://{{ .username }}:{{ .password }}@{{ .database_host }}:5432/payments
# Uses an existing template from configmap
# Secret is fetched, merged and templated within the referenced configMap data
# It does not update the configmap, it creates a secret with: data["alertmanager.yml"] = ...result...
templateFrom:
- configMap:
name: application-config-tmpl
items:
- key: config.yml
# Data defines the connection between the Kubernetes Secret keys and the Provider data
data:
- secretKey: username
remoteRef:
key: database-credentials
version: v1
property: username
decodingStrategy: None # can be None, Base64, Base64URL or Auto
# define the source of the secret. Can be a SecretStore or a Generator kind
sourceRef:
# point to a SecretStore that should be used to fetch a secret.
# must be defined if no spec.secretStoreRef is defined.
storeRef:
name: aws-secretstore
kind: ClusterSecretStore
# point to a generator resource that provides the secret value
generatorRef:
apiVersion: generators.external-secrets.io/v1alpha1
kind: Password
name: db-password
# Used to fetch all properties from the Provider key
# If multiple dataFrom are specified, secrets are merged in the specified order
dataFrom:
- extract:
key: database-credentials
version: v1
property: data
conversionStrategy: Default
decodingStrategy: Auto
rewrite:
- regexp:
source: "exp-(.*?)-ression"
target: "rewriting-${1}-with-groups"
- find:
path: path-to-filter
source: "exp-(.*?)-ression"
target: "rewriting-${1}-with-groups"
name:
regexp: ".*foobar.*"
tags:
foo: bar
conversionStrategy: Unicode
decodingStrategy: Base64
rewrite:
- regexp:
source: "foo"
target: "bar"
status:
# refreshTime is the time and date the external secret was fetched and
# the target secret updated
refreshTime: "2019-08-12T12:33:02Z"
# Standard condition schema
conditions:
# ExternalSecret ready condition indicates the secret is ready for use.
# This is defined as:
# - The target secret exists
# - The target secret has been refreshed within the last refreshInterval
# - The target secret content is up-to-date based on any target templates
- type: Ready
status: "True" # False if last refresh was not successful
reason: "SecretSynced"
message: "Secret was synced"
lastTransitionTime: "2019-08-12T12:33:02Z"