Advanced Templating v1

Warning

Templating Engine v1 is deprecated and will be removed in the future. Please migrate to engine v2 and take a look at our upgrade guide for changes.

With External Secrets Operator you can transform the data from the external secret provider before it is stored as Kind=Secret. You can do this with the Spec.Target.Template.

Each data value is interpreted as a Go template. Please note that referencing a non-existing key in the template will raise an error, instead of being suppressed.

Examples

You can use templates to inject your secrets into a configuration file that you mount into your pod:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: template
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: secretstore-sample
    kind: SecretStore
  target:
    name: secret-to-be-created

    # v2 is the default engineVersion in external-secrets.io/v1beta1
    # v1 is the default engineVersion in external-secrets.io/v1alpha1 (deprecated)
    engineVersion: v1

    # this is how the Kind=Secret will look like
    template:
      type: kubernetes.io/tls
      data:
        # multiline string
        config: |
          datasources:
          - name: Graphite
            type: graphite
            access: proxy
            url: http://localhost:8080
            password: "{{ .password | toString }}" # <-- convert []byte to string
            user: "{{ .user | toString }}"         # <-- convert []byte to string

  data:
  - secretKey: user
    remoteRef:
      key: /grafana/user
  - secretKey: password
    remoteRef:
      key: /grafana/password

You can also use pre-defined functions to extract data from your secrets. Here: extract key/cert from a pkcs12 archive and store it as PEM.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: template
spec:
  # ...
  target:
    template:
      type: kubernetes.io/tls
      engineVersion: v2
      data:
        tls.crt: "{{ .mysecret | pkcs12cert }}"
        tls.key: "{{ .mysecret | pkcs12key }}"

        # if needed unlock the pkcs12 with the password
        tls.crt: "{{ .mysecret | pkcs12certPass "my-password" }}"

TemplateFrom

You do not have to define your templates inline in an ExternalSecret but you can pull ConfigMaps or other Secrets that contain a template. Consider the following example:

# define your template in a config map
apiVersion: v1
kind: ConfigMap
metadata:
  name: grafana-config-tpl
data:
  config.yaml: |
    datasources:
      - name: Graphite
        type: graphite
        access: proxy
        url: http://localhost:8080
        password: "{{ .password | toString }}" # <-- convert []byte to string
        user: "{{ .user | toString }}"         # <-- convert []byte to string
---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: my-template-example
spec:
  # ...
  target:
    name: secret-to-be-created
    template:
      templateFrom:
      - configMap:
          # name of the configmap to pull in
          name: grafana-config-tpl
          # here you define the keys that should be used as template
          items:
          - key: config.yaml
  data:
  - secretKey: user
    remoteRef:
      key: /grafana/user
  - secretKey: password
    remoteRef:
      key: /grafana/password

Helper functions

We provide a bunch of convenience functions that help you transform your secrets. A secret value is a []byte.

Function	Description	Input	Output
pkcs12key	extracts the private key from a pkcs12 archive	`[]byte`	`[]byte`
pkcs12keyPass	extracts the private key from a pkcs12 archive using the provided password	password `string`, data `[]byte`	`[]byte`
pkcs12cert	extracts the certificate from a pkcs12 archive	`[]byte`	`[]byte`
pkcs12certPass	extracts the certificate from a pkcs12 archive using the provided password	password `string`, data `[]byte`	`[]byte`
pemPrivateKey	PEM encodes the provided bytes as private key	`[]byte`	`string`
pemCertificate	PEM encodes the provided bytes as certificate	`[]byte`	`string`
jwkPublicKeyPem	takes an json-serialized JWK as `[]byte` and returns an PEM block of type `PUBLIC KEY` that contains the public key (see here) for details	`[]byte`	`string`
jwkPrivateKeyPem	takes an json-serialized JWK as `[]byte` and returns an PEM block of type `PRIVATE KEY` that contains the private key in PKCS #8 format (see here) for details	`[]byte`	`string`
base64decode	decodes the provided bytes as base64	`[]byte`	`[]byte`
base64encode	encodes the provided bytes as base64	`[]byte`	`[]byte`
fromJSON	parses the bytes as JSON so you can access individual properties	`[]byte`	`any`
toJSON	encodes the provided object as json string	`any`	`string`
toString	converts bytes to string	`[]byte`	`string`
toBytes	converts string to bytes	`string`	`[]byte`
upper	converts all characters to their upper case	`string`	`string`
lower	converts all character to their lower case	`string`	`string`