External Secrets Operator

https://external-secrets.io/latest
Admin
External Secrets Operator is a Kubernetes operator that integrates various external secret...
Tokens:338,186
Snippets:2,709
Trust Score:7.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### match Examples

Source: https://external-secrets.io/latest/api/pushsecret

Shows how to use `match` to select keys: all keys, keys starting with 'db-', or keys ending with '-key'.

```yaml
# Match all keys
dataTo:
  - storeRef:
      name: my-store

# Match keys starting with "db-"
dataTo:
  - storeRef:
      name: my-store
    match:
      regexp: "^db-.*"

# Match keys ending with "-key"
dataTo:
  - storeRef:
      name: my-store
    match:
      regexp: ".*-key$"

```

--------------------------------

### Basic dataTo Example

Source: https://external-secrets.io/latest/api/pushsecret

Shows a PushSecret with `dataTo` to push all keys starting with 'db-' to a specified store, with a rewrite to change the key prefix.

```yaml
apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-db-secrets
spec:
  secretStoreRefs:
    - name: aws-secret-store
  selector:
    secret:
      name: app-secrets
  dataTo:
    - storeRef:
        name: aws-secret-store
      match:
        regexp: "^db-.*"  # Push all keys starting with "db-"
      rewrite:
        - regexp:
            source: "^db-"
            target: "myapp/database/"  # db-host -> myapp/database/host

```

--------------------------------

### Helm: Install CRDs

Source: https://external-secrets.io/latest/guides/using-latest-image

Run make crds.install to install the CRDs before installing the Helm chart.

```makefile
make crds.install

```

--------------------------------

### Install chart from local build

Source: https://external-secrets.io/latest/introduction/getting-started

Builds the Helm chart locally and installs it from the local tarball. Uncomment the --set installCRDs=false line to disable automatic CRD management.

```bash
make helm.build

helm install external-secrets \
    ./bin/chart/external-secrets.tgz \
    -n external-secrets \
    --create-namespace \
  # --set installCRDs=false
```

--------------------------------

### QuayAccessToken example manifest

Source: https://external-secrets.io/latest/api/generator/quay

Example manifest for the QuayAccessToken generator, specifying the Quay registry URL, robot account, and service account reference.

```yaml
apiVersion: generators.external-secrets.io/v1alpha1
kind: QuayAccessToken
metadata:
  name: my-quay-token
  namespace: default
spec:
  url: "quay.io"
  robotAccount: "quay_user_or_org+robot_account_name"
  serviceAccountRef:
    name: "default"
    namespace: "default"

```

--------------------------------

### Example output of dataFrom secrets

Source: https://external-secrets.io/latest/provider/bitwarden-secrets-manager

Example output of the Kubernetes secret created by dataFrom, showing secrets keyed by their Bitwarden secret IDs.

```bash
$ kubectl get secret secret-to-be-created -o jsonpath='{.data}'|jq
{
"2989464a-03c2-4ced-9fe2-b34400aca42d": "bG9jYWxob3N0OjEyMzQ1",
"98c18ddb-314e-463c-97c3-b34400ac6593": "dWFzZXJuYW1lMQ==",
"c917a790-76bc-49ca-b303-b34400ac8035": "UGFzc1dvcmQx",
}

```

--------------------------------

### Provider secrets for path removal example

Source: https://external-secrets.io/latest/guides/datafrom-rewrite

Example secrets available in the provider that match the find pattern, showing the keys that will be rewritten.

```text
path/to/my/secrets/username
path/to/my/secrets/password

```

--------------------------------

### PushSecret template example

Source: https://external-secrets.io/latest/guides/templating

Example of a PushSecret resource using templating with engineVersion v2 and a data template that uppercases the token value.

```yaml
apiVersion: external-secrets.io/v1beta1
kind: PushSecret
metadata:
  name: template
spec:
  # ...
  template:
    engineVersion: v2
    data:
      token: "{{ .token | toString | upper }} was templated"
  data:
    - match:
        secretKey: token
        remoteRef:
          remoteKey: create-secret-name
          property: token

```

--------------------------------

### Build and serve documentation

Source: https://external-secrets.io/latest/contributing/devguide

Run a complete documentation build and serve it. The rendered assets are available under /site.

```bash
make docs
make docs.serve

```

--------------------------------

### Build documentation

Source: https://external-secrets.io/latest/contributing/devguide

Build the documentation using make.

```bash
make docs

```

--------------------------------

### VaultDynamicSecret manifest for GET method with query-string parameters

Source: https://external-secrets.io/latest/api/generator/vault

Example manifest for a VaultDynamicSecret using the GET method with query-string parameters. The `getParameters` field is a map of string slices sent as the query string on GET calls; it is ignored for non-GET methods. The `resultType` can be "Data", "Auth", or "Raw". The provider block uses Kubernetes authentication.

```yaml
apiVersion: generators.external-secrets.io/v1alpha1
kind: VaultDynamicSecret
metadata:
  name: "vault-get-example"
spec:
  path: "/kv/data/example"
  method: "GET"
  # Query string parameters for GET calls (each key may map to multiple values).
  # These are ignored for non-GET methods; use `parameters` for write bodies.
  getParameters:
    version:
    - "1"
  resultType: "Data"  # "Auth" and "Raw" are also available
  provider:
    # For production, always use "https" and ensure the additional TLS parameters are configured accordingly.
    server: "http://vault.default.svc.cluster.local:8200"
    auth:
      kubernetes:
        mountPath: "kubernetes"
        role: "external-secrets-operator"
        serviceAccountRef:
          name: "default"

```

--------------------------------

### Example bootstrap generator command with output

Source: https://external-secrets.io/latest/guides/using-esoctl-tool

Shows a complete example of bootstrapping a generator named `MyAwesomeGenerator`, including the command and its expected output. The output lists all created and updated files, and provides next steps for customization and building.

```bash
bin/esoctl bootstrap generator --name MyAwesomeGenerator --description "An awesome generator I want to add to ESO :)"

✓ Created CRD: /home/gusfcarvalho/Documents/repos/external-secrets/apis/generators/v1alpha1/types_myawesomegenerator.go
✓ Created implementation: /home/gusfcarvalho/Documents/repos/external-secrets/generators/v1/myawesomegenerator/myawesomegenerator.go
✓ Created test file: /home/gusfcarvalho/Documents/repos/external-secrets/generators/v1/myawesomegenerator/myawesomegenerator_test.go
✓ Created go.mod: /home/gusfcarvalho/Documents/repos/external-secrets/generators/v1/myawesomegenerator/go.mod
✓ Created go.sum: /home/gusfcarvalho/Documents/repos/external-secrets/generators/v1/myawesomegenerator/go.sum
✓ Updated register file: /home/gusfcarvalho/Documents/repos/external-secrets/pkg/register/generators.go
✓ Updated types_cluster.go
✓ Updated main go.mod
✓ Updated resolver file: /home/gusfcarvalho/Documents/repos/external-secrets/runtime/esutils/resolvers/generator.go
✓ Updated register.go
✓ Successfully bootstrapped generator: MyAwesomeGenerator

Next steps:
1. Review and customize: apis/generators/v1alpha1/types_myawesomegenerator.go
2. Implement the generator logic in: generators/v1/myawesomegenerator/myawesomegenerator.go
3. Run: go mod tidy
4. Run: make generate
5. Run: make manifests
6. Add tests for your generator

```

--------------------------------

### ClusterSecretStore RBAC example

Source: https://external-secrets.io/latest/provider/crd

YAML manifest for a ServiceAccount, ClusterRole, and ClusterRoleBinding granting get and list on widgets across all namespaces. Required when using ClusterSecretStore, especially with dataFrom.find.

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: crd-reader
  namespace: external-secrets
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: crd-reader
rules:
  - apiGroups: ["example.io"]
    resources: ["widgets"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: crd-reader
subjects:
  - kind: ServiceAccount
    name: crd-reader
    namespace: external-secrets
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: crd-reader

```

--------------------------------

### Serve documentation with live reload

Source: https://external-secrets.io/latest/contributing/devguide

Run the mkdocs server with livereload for documentation development.

```bash
make docs.serve

```

--------------------------------

### Get parameter from AWS Parameter Store using AWS CLI

Source: https://external-secrets.io/latest/provider/aws-parameter-store

Command to retrieve the synchronized parameter from AWS Parameter Store. Requires AWS CLI installed and logged in.

```bash
aws ssm get-parameter --name=my-first-parameter --region=us-east-1

```

--------------------------------

### Folder path examples with forward and backslashes

Source: https://external-secrets.io/latest/provider/devolutions-server

Shows how to reference an entry inside a folder using either forward slashes or backslashes as path separators. Both formats are accepted.

```text
folder/subfolder/entry-name
folder\subfolder\entry-name
```

--------------------------------

### SecretStore (namespace-scoped) RBAC example

Source: https://external-secrets.io/latest/provider/crd

YAML manifest for a namespace-scoped ServiceAccount, Role, and RoleBinding granting get and list on widgets in the default namespace. The list verb is only required when using dataFrom.find.

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: crd-reader
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: crd-reader
  namespace: default
rules:
  - apiGroups: ["example.io"]
    resources: ["widgets"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: crd-reader
  namespace: default
subjects:
  - kind: ServiceAccount
    name: crd-reader
    namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: crd-reader

```

--------------------------------

### Run esoctl template command

Source: https://external-secrets.io/latest/guides/using-esoctl-tool

Build the esoctl binary with `make build` in the `cmd/esoctl` folder, then run the template command with a templated object file and a secret data file.

```bash
bin/esoctl template --source-templated-object template-test/push-secret.yaml --source-secret-data-file template-test/secret.yaml

```

--------------------------------

### GithubAccessToken generator manifest

Source: https://external-secrets.io/latest/api/generator/github

Defines a GithubAccessToken generator that uses the GitHub App ID, installation ID, and private key secret to generate an access token. Optional fields include 'url', 'repositories', and 'permissions'. The comments reference the setup steps from the documentation.

```yaml
# 1. Register Github app https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app
#   `App ID: 123456` will be displayed after you create an app. Next on the bottom of the page, you'll find `Generate a private key` button.
# 2. Get privateKey https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys put it in e.g `github-app-pem` k8s secret
# 3. Set permissions for the app, e.g if you want to push OCI images to ghr set RW for packages https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app#choosing-permissions-for-rest-api-access
# 4. Install your Github app https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app
# 5. Get `installID` https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app#generating-an-installation-access-token (2)
---
apiVersion: generators.external-secrets.io/v1alpha1
kind: GithubAccessToken
metadata:
  name: github-auth-token
spec:
  appID: "0000000" # (1)
  installID: "00000000" # (5)
  url: "" # (Default https://api.github.com.)
  repositories: # Optional
    - "Hello-World"
  permissions: # Optional
    contents: read
  auth:
    privateKey:
      secretRef:
        name: github-app-pem # (2)
        key: key

```

--------------------------------

### Match multiple variables by name regex with dataFrom.find

Source: https://external-secrets.io/latest/provider/gitlab-variables

Uses dataFrom.find to sync multiple GitLab variables matching a name regexp. The example matches variables starting with 'PROD_' and optionally filters by environment_scope. Note: find.name is mandatory, find.tags only supports environment_scope, and find.path is not implemented.

```yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: gitlab-find-example
spec:
  refreshInterval: 1h0m0s
  secretStoreRef:
    kind: SecretStore
    name: gitlab-secret-store
  target:
    name: gitlab-secret-to-create
    creationPolicy: Owner
  dataFrom:
    - find:
        name:
          regexp: "^PROD_.*"            # required: regexp matched against variable names
        tags:
          environment_scope: production  # optional: also filter by environment scope

```

--------------------------------

### entrypoint.sh for Bitwarden CLI

Source: https://external-secrets.io/latest/examples/bitwarden

Logs in to Bitwarden using either API key or username/password, unlocks the vault, and starts `bw serve` on all hostnames. Requires environment variables `BW_HOST`, `BW_PASSWORD`, and optionally `BW_CLIENTID`/`BW_CLIENTSECRET` or `BW_USER`.

```bash
#!/usr/bin/env bash

set -e

bw config server ${BW_HOST}

if [ -n "$BW_CLIENTID" ] && [ -n "$BW_CLIENTSECRET" ]; then
    echo "Using apikey to log in"
    bw login --apikey --raw
    export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)
else
    echo "Using username and password to log in"
    export BW_SESSION=$(bw login ${BW_USER} --passwordenv BW_PASSWORD --raw)
fi

bw unlock --check

echo 'Running `bw server` on port 8087'
bw serve --hostname all

```

--------------------------------

### Create ExternalSecret for dockerconfigjson from existing Docker config

Source: https://external-secrets.io/latest/guides/common-k8s-secret-types

Creates an ExternalSecret that uses templating to populate a Kubernetes secret of type kubernetes.io/dockerconfigjson from a Google Cloud secret named docker-config-example. Requires prior setup of authentication and SecretStore as per the Google Cloud Secrets Manager guide.

```yaml
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: dk-cfg-example
spec:
  refreshInterval: 1h0m0s
  secretStoreRef:
    name: example
    kind: SecretStore
  target:
    template:
      type: kubernetes.io/dockerconfigjson
      data:
        .dockerconfigjson: "{{ .mysecret | toString }}"
    name: secret-to-be-created
    creationPolicy: Owner
  data:
  - secretKey: mysecret
    remoteRef:
      key: docker-config-example

```

--------------------------------

### storeRef Examples

Source: https://external-secrets.io/latest/api/pushsecret

Shows how to target a specific store by name or by label selector. Each `dataTo` entry requires a `storeRef`.

```yaml
dataTo:
  # Target a specific store by name
  - storeRef:
      name: aws-secret-store

  # Target stores by label
  - storeRef:
      labelSelector:
        matchLabels:
          env: production

```

--------------------------------

### Helm values to disable CRD installation

Source: https://external-secrets.io/latest/guides/security-best-practices

Helm values to disable CRD installation for cluster and namespaced resources. Note that disabling CRD installation does not automatically disable reconciliation.

```yaml
crds:
  createClusterExternalSecret: false
  createClusterSecretStore: false
  createSecretStore: false
  createPushSecret: false

```

--------------------------------

### Provider secrets for transform example

Source: https://external-secrets.io/latest/guides/datafrom-rewrite

Example secrets in the provider with keys that will be transformed.

```json
{
"foo-nut-bar": "HELLO1"
"foo-naz-bar": "HELLO2"
"foo-bar-baz": '{"john": "doe"}'
}

```

--------------------------------

### Provider secrets for merge example

Source: https://external-secrets.io/latest/guides/datafrom-rewrite

Example secrets in the provider that will be merged into a single Kubernetes Secret.

```json
{
    "path/to/secrets/object-storage-credentials": {
        "ACCESS_KEY": "XXXX",
        "SECRET_KEY": "YYYY"
    },
    "path/to/secrets/mongo-credentials": {
        "USERNAME": "XXXX",
        "PASSWORD": "YYYY"
    }
}

```

--------------------------------

### Example template-test directory tree

Source: https://external-secrets.io/latest/guides/using-esoctl-tool

Shows the expected file structure for the template-test directory containing push-secret.yaml and secret.yaml.

```text
❯ tree template-test/                                                                                                                                                                                                                   (base)
template-test/
├── push-secret.yaml
└── secret.yaml

1 directory, 2 files

```

--------------------------------

### Create a Kind cluster with ctlptl and connect to local registry

Source: https://external-secrets.io/latest/introduction/prerequisites

Uses ctlptl to create a Kind cluster named 'kind-kind' and connects it to the local registry 'kind-registry'. The cluster will use the registry at localhost:5000.

```bash
ctlptl create cluster kind --registry=kind-registry
```

--------------------------------

### Target Secret example

Source: https://external-secrets.io/latest/provider/nebius-mysterybox

Example of the target Kubernetes Secret produced when fetching a full secret from MysteryBox.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: <your-k8s-secret-name>
type: Opaque
data:
  <entry-key-1>: <base64-of-value-1>
  <entry-key-2>: <base64-of-value-2>

```

--------------------------------

### PushSecret Templating Example

Source: https://external-secrets.io/latest/guides/templating

Example of a PushSecret resource using templating to transform a secret value before it is pushed to the provider.

```APIDOC
## PushSecret Templating

### Description
PushSecret templating allows you to transform secret data before it is stored at the provider, using the same templating engine as ExternalSecrets.

### Example
```yaml
apiVersion: external-secrets.io/v1beta1
kind: PushSecret
metadata:
  name: template
spec:
  # ...
  template:
    engineVersion: v2
    data:
      token: "{{ .token | toString | upper }} was templated"
  data:
    - match:
        secretKey: token
        remoteRef:
          remoteKey: create-secret-name
          property: token
```
```

--------------------------------

### conversionStrategy Example

Source: https://external-secrets.io/latest/api/pushsecret

Shows setting `conversionStrategy` to `ReverseUnicode` for converting key names before matching and rewriting.

```yaml
dataTo:
  - storeRef:
      name: my-store
    conversionStrategy: ReverseUnicode

```

--------------------------------

### Provider secrets for invalid character removal example

Source: https://external-secrets.io/latest/guides/datafrom-rewrite

Example secrets with keys containing invalid characters that will be replaced.

```json
{
    "development": {
        "foo/bar": "1111",
        "foo$baz": "2222"
    }
}

```

--------------------------------

### Manual: Build Docker image

Source: https://external-secrets.io/latest/guides/using-latest-image

Build the Docker image using the standalone Dockerfile and tag it as my-org/external-secrets:latest.

```bash
docker build -f Dockerfile.standalone -t my-org/external-secrets:latest .

```

--------------------------------

### Verify Docker can run without sudo

Source: https://external-secrets.io/latest/introduction/prerequisites

Runs the hello-world container to verify that Docker works without sudo. If the command succeeds without errors, the configuration is successful.

```bash
docker run hello-world
```

--------------------------------

### Install Helm chart with custom controllerClass

Source: https://external-secrets.io/latest/guides/controller-class

Installs the external-secrets Helm chart with a custom controller class named 'custom'.

```bash
helm install custom-external-secrets external-secrets/external-secrets --set controllerClass=custom

```

--------------------------------

### Run tests and lint

Source: https://external-secrets.io/latest/contributing/devguide

Run the project's tests and lint the code.

```bash
make test
make lint

```
Tokens:
Raw