Configuration Overview

The ESI Pod Webhook is configured primarily through annotations added to the metadata section of your Pods. These annotations instruct the webhook on how and what secrets to inject.

​

Core Annotations

These are the fundamental annotations to control basic secret injection.

​

externalsecret

• Annotation: secretless.externalsecrets.com/externalsecret: "<your-externalsecret-name>"
• Required: Yes, for any injection to occur.
• Description: Specifies the name of the ExternalSecret resource from which to fetch secrets. This ExternalSecret must exist in the same namespace as the Pod being annotated.
• Example:
  Copy

  Ask AI

  metadata:
    annotations:
      secretless.externalsecrets.com/externalsecret: "my-app-db-credentials"
  

​

env-vars

• Annotation: secretless.externalsecrets.com/env-vars: "true" | "false"
• Default: "false" (if not specified)
• Description: Enables or disables the injection of secrets as environment variables.
  • If set to "true", the webhook injects an init container into the Pod. This init container runs esi-cli --mode=init, which fetches secrets from the specified ExternalSecret, exports them as environment variables, and then executes your application container’s original command.
  • Secret keys are typically converted to uppercase environment variable names, with non-alphanumeric characters replaced by underscores (e.g., my-db-password becomes MY_DB_PASSWORD). Refer to the esi-cli documentation for precise conversion rules.
• Example:
  Copy

  Ask AI

  metadata:
    annotations:
      secretless.externalsecrets.com/externalsecret: "my-app-config"
      secretless.externalsecrets.com/env-vars: "true"
  

​

file-secrets

• Annotation: secretless.externalsecrets.com/file-secrets: "true" | "false"
• Default: "false" (if not specified)
• Description: Enables or disables the injection of secrets as files.
  • If set to "true", the webhook injects a sidecar container into the Pod. This sidecar runs esi-cli --mode=daemon.
  • esi-cli fetches secrets from the ExternalSecret and writes them to a single file: /secrets/secrets.json (in JSON format). This file is located in an in-memory volume shared with your application container(s).
  • Your application container(s) will have this volume automatically mounted at /secrets.
  • The path and format (/secrets/secrets.json) are currently fixed and not customizable via annotations.
  • The sidecar’s daemon mode allows for potential background refreshing of this file if the ExternalSecret changes. Your application would need to be capable of reloading configuration from this file if it needs to pick up changes dynamically.
• Example:
  Copy

  Ask AI

  metadata:
    annotations:
      secretless.externalsecrets.com/externalsecret: "my-app-certs"
      secretless.externalsecrets.com/file-secrets: "true"
  

​

skip

• Annotation: secretless.externalsecrets.com/skip: "true" | "false"
• Default: "false" (if not specified)
• Description: If set to "true", the ESI Pod Webhook will ignore this Pod entirely, and no inspection or injection will occur. This is useful for:
  • Explicitly disabling injection on specific Pods.
  • System Pods or critical infrastructure Pods where webhook intervention is undesired.
  • The ESI Pod Webhook’s own deployment (it’s typically annotated with skip: "true" by default).
• Example:
  Copy

  Ask AI

  metadata:
    annotations:
      secretless.externalsecrets.com/skip: "true"
  

​

Auxiliary Annotations

These annotations provide additional control or support for the injection process.

​

image-pull-secrets

• Annotation: secretless.externalsecrets.com/image-pull-secrets: "<your-image-pull-secret-name>"
• Optional: Yes
• Description: Specifies the name of an existing Kubernetes Secret of type kubernetes.io/dockerconfigjson (an image pull secret) to be added to the Pod’s spec.imagePullSecrets array. This is useful if the esi-cli init or sidecar container images (which are configured globally for the webhook deployment) are hosted in a private container registry that requires authentication.
• Example:
  Copy

  Ask AI

  metadata:
    annotations:
      secretless.externalsecrets.com/externalsecret: "some-secret"
      secretless.externalsecrets.com/env-vars: "true"
      secretless.externalsecrets.com/image-pull-secrets: "my-private-registry-creds"
  

​

Advanced: esi-cli Passthrough Annotations

These annotations allow you to pass specific command-line arguments directly to the esi-cli tool when it’s run by the init container (i.e., for environment variable injection). They provide finer-grained control over esi-cli’s behavior, especially for features like federation.

​

federated-server-url

• Annotation: secretless.externalsecrets.com/federated-server-url: "<url_of_federation_server>"
• Maps to esi-cli flag: --federated-server-url
• Description: Specifies the URL of an ESI Federation server from which to fetch secrets.
• Requires: env-vars: "true".

​

inject-on-env (Passthrough for esi-cli)

• Annotation: secretless.externalsecrets.com/inject-on-env: "<env_map_string_for_esi_cli>"
• Maps to esi-cli flag: --inject-on-env
• Description: Provides a specific mapping string for esi-cli to control how secrets are named or selected when injected as environment variables. The format of <env_map_string_for_esi_cli> is determined by esi-cli’s own parsing rules (e.g., ENV_VAR_NAME=secretKey,OTHER_VAR=anotherKey).
  While secretless.externalsecrets.com/env-vars: "true" enables general environment variable injection (all keys from the ExternalSecret’s data), this annotation allows for more precise control via esi-cli’s --inject-on-env flag, potentially overriding or refining the default behavior.
• Requires: env-vars: "true".

​

federated-generator

• Annotation: secretless.externalsecrets.com/federated-generator: "<generator_config_string_for_esi_cli>"
• Maps to esi-cli flag: --federated-generators
• Description: Specifies generator configurations for esi-cli when fetching secrets from a federated ESI server.
• Requires: env-vars: "true" and likely federated-server-url.

​

federated-store

• Annotation: secretless.externalsecrets.com/federated-store: "<store_config_string_for_esi_cli>"
• Maps to esi-cli flag: --federated-store
• Description: Specifies store configurations for esi-cli when fetching secrets from a federated ESI server.
• Requires: env-vars: "true" and likely federated-server-url.

​

Webhook Global Configuration (Deployment Arguments)

While not pod annotations, the ESI Pod Webhook Deployment itself accepts arguments that globally configure the behavior of injected containers. These are set once when deploying the webhook:

• --tls-cert=<path>: Path to the webhook’s TLS certificate file (default: /etc/webhook/certs/tls.crt).
• --tls-key=<path>: Path to the webhook’s TLS private key file (default: /etc/webhook/certs/tls.key).
• --port=<port>: Port for the webhook server (default: 8443).
• --init-image=<image_uri>: The container image to use for the init container (e.g., your-registry/esi-cli:latest).
• --sidecar-image=<image_uri>: The container image to use for the sidecar container (e.g., your-registry/esi-cli:latest).
• --image-pull-policy=<policy>: Image pull policy (e.g., IfNotPresent, Always) for injected containers.

These global settings define the default images and operational parameters for the containers the webhook injects. Refer to the webhook’s deployment manifest for current values.

​

Next Steps

• See Usage Examples for practical applications of these annotations.
• If you encounter issues, refer to the Troubleshooting guide.