Skip to main content
The External Secrets Enterprise Edition is product suite is a premium product. It requires a specific subscription. Contact us for more information.
This section provides practical examples of how to annotate your Pods to use the ESI Pod Webhook for secret injection.

​
Example 1: Basic Environment Variable Injection

Inject all key-value pairs from the my-app-db-config ExternalSecret as environment variables into the my-app-container. 
apiVersion: v1
kind: Pod
metadata:
  name: my-app-env-vars
  namespace: default
  annotations:
    secretless.externalsecrets.com/externalsecret: "my-app-db-config" # Name of your ExternalSecret
    secretless.externalsecrets.com/env-vars: "true"                   # Enable environment variable injection
    # secretless.externalsecrets.com/image-pull-secrets: "my-registry-secret" # Optional: if esi-cli image is private
spec:
  containers:
  - name: my-app-container
    image: myapplication:latest
    command: ["/app/run.sh"]
    # Environment variables from 'my-app-db-config' will be available here
    # e.g., DB_USER, DB_PASSWORD (assuming keys in ExternalSecret are 'db-user', 'db-password')
Explanation:
  • The webhook sees env-vars: "true".
  • It injects an init container running esi-cli --mode=init.
  • esi-cli fetches data from the my-app-db-config ExternalSecret.
  • The application my-app-container starts with these secrets as environment variables.

​
Example 2: Basic File-Based Secret Injection

Inject all key-value pairs from the my-app-tls-certs ExternalSecret into the /secrets/secrets.json file, accessible by my-secure-app-container. 
apiVersion: v1
kind: Pod
metadata:
  name: my-app-file-secrets
  namespace: default
  annotations:
    secretless.externalsecrets.com/externalsecret: "my-app-tls-certs" # Name of your ExternalSecret
    secretless.externalsecrets.com/file-secrets: "true"                 # Enable file-based injection
spec:
  containers:
  - name: my-secure-app-container
    image: mysecureapp:latest
    command: ["/app/server", "--config=/secrets/secrets.json"]
    volumeMounts:
    - name: secretless-secrets # This name is automatically assigned by the webhook
      mountPath: /secrets
      readOnly: true # Application should typically read only
    # The application can now read /secrets/secrets.json
    # This file will contain a JSON object of all secrets from 'my-app-tls-certs'.
Explanation:
  • The webhook sees file-secrets: "true".
  • It injects a sidecar container running esi-cli --mode=daemon.
  • It also creates an emptyDir volume (named secretless-secrets by default) and mounts it to both the sidecar and your application container(s) at /secrets.
  • esi-cli in the sidecar writes the fetched secrets to /secrets/secrets.json.
  • The sidecar continues running and can refresh secrets.json if the ExternalSecret changes (application needs to support reloading).

​
Example 3: Environment Variables with esi-cli Federation

Fetch a specific secret (API_TOKEN) using esi-cli’s federation capabilities from a federated ESI server and inject it as an environment variable. 
apiVersion: v1
kind: Pod
metadata:
  name: my-federated-app
  namespace: finance
  annotations:
    secretless.externalsecrets.com/externalsecret: "placeholder-es" # Still required, but actual source is federated
    secretless.externalsecrets.com/env-vars: "true"
    secretless.externalsecrets.com/federated-server-url: "https://esi-federation.corp.example.com"
    secretless.externalsecrets.com/federated-store: "central-vault-prod"
    # This uses esi-cli's --inject-on-env to map a specific federated secret key
    secretless.externalsecrets.com/inject-on-env: "API_TOKEN=remote-secret-name.api-key"
spec:
  serviceAccountName: finance-app-sa # Ensure this SA has a token esi-cli can use
  containers:
  - name: data-processor
    image: dataproxy:v2.1
    # The API_TOKEN environment variable will be available here
The secretless.externalsecrets.com/externalsecret annotation is still technically required by the webhook to trigger its logic, even if the primary secret source is federated. You can point it to a minimal or placeholder ExternalSecret in the pod’s namespace.
Explanation:
  • env-vars: "true" enables the init container with esi-cli.
  • The federated-server-url and federated-store annotations configure esi-cli to talk to the federation server.
  • inject-on-env: "API_TOKEN=remote-secret-name.api-key" tells esi-cli to fetch api-key from remote-secret-name (via the federated store) and expose it as API_TOKEN.

​
Example 4: Both Environment and File Injection

While less common, you might want some secrets as environment variables and the full set as a file. 
apiVersion: v1
kind: Pod
metadata:
  name: my-flexible-app
  namespace: default
  annotations:
    secretless.externalsecrets.com/externalsecret: "app-comprehensive-secrets"
    secretless.externalsecrets.com/env-vars: "true"      # Inject env vars via init container
    secretless.externalsecrets.com/file-secrets: "true"  # Inject files via sidecar
    # Use esi-cli's --inject-on-env to pick specific env vars
    secretless.externalsecrets.com/inject-on-env: "PRIMARY_DB_HOST=db.host,PRIMARY_DB_PORT=db.port"
spec:
  containers:
  - name: main-app
    image: myflexibleapp:latest
    # PRIMARY_DB_HOST and PRIMARY_DB_PORT will be available as env vars.
    # The full set of secrets from 'app-comprehensive-secrets' will be in /secrets/secrets.json.
Explanation:
  • The webhook will add an init container (for env-vars and inject-on-env) AND a sidecar container (for file-secrets).
  • The init container will use esi-cli to set PRIMARY_DB_HOST and PRIMARY_DB_PORT.
  • The sidecar will provide /secrets/secrets.json with all data from app-comprehensive-secrets.
These examples cover common use cases. Remember to consult the Pod Annotations documentation for a full list of options and the esi-cli documentation for details on its specific flags and behaviors when using passthrough annotations.