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.
esi-cli provides two primary mechanisms for making secrets available to your applications: environment variable injection and file injection. The availability and behavior of these mechanisms can depend on the chosen mode of operation.

​
Environment Variable Injection

This mechanism is primarily associated with init mode (--mode=init). Secrets are injected as environment variables, making them directly accessible to the application process executed by esi-cli via the --binary-path flag. There are two main ways to control environment variable injection:
  1. Via --external-secrets Flag:
    • When you provide a comma-separated list of ExternalSecret names to the --external-secrets flag (e.g., --external-secrets=my-db-config,my-api-keys):
    • esi-cli fetches the data from the Kubernetes Secret resources that are managed by these ExternalSecrets.
    • All key-value pairs from these secrets are converted into environment variables.
    • Naming Convention: Secret keys are typically transformed into standard environment variable names: they are converted to uppercase, and any non-alphanumeric characters are replaced with underscores (_). For example, a secret key database-url would become the environment variable DATABASE_URL.
  2. Via --inject-on-env Flag:
    • This flag offers more granular control over which specific secret keys are injected and what their resulting environment variable names will be.
    • The format is a comma-separated list of mappings: ENV_VAR_NAME=secretName.key (e.g., --inject-on-env=API_TOKEN=backend-credentials.apiToken,DB_USER=db-access.username).
    • This allows you to pick specific keys from different ExternalSecrets (referenced by secretName) and assign them to custom environment variable names.
    • Override Behavior: If an environment variable name defined via --inject-on-env conflicts with one that would be generated from --external-secrets, the mapping from --inject-on-env takes precedence.
Environment variables are set up in the environment of the esi-cli process itself before it uses syscall.Exec to run the target binary specified by --binary-path. This means the target binary inherits these environment variables directly.

​
File Injection

This mechanism allows esi-cli to write secret data into files. It is the primary mechanism for daemon mode (--mode=daemon) and can also be used in init mode. File injection is controlled by the --inject-on-file flag.
  • Mapping Format: The flag accepts a comma-separated list of mappings, where each mapping defines a target file path and the secret data to write to it:
    • /path/to/target/file=secretName.key: Injects the value of a specific key from the Kubernetes Secret managed by secretName into the target file. The raw content of the secret key’s value is written to the file.
    • /path/to/target/file=secretName: Injects all data from the Kubernetes Secret managed by secretName into the target file. The data is written in YAML format.
  • Directory Creation: esi-cli will automatically create any necessary parent directories for the specified target file paths if they do not already exist. This simplifies deployment as you don’t need to pre-create directory structures for secret files.
    • This behavior is based on the MEMORY item: Updated HandleFileInjection in pkg/engine/file/file.go to automatically create parent directories...
  • Data Encoding: esi-cli writes the raw byte data from the Kubernetes Secret directly to files. It does not perform base64 decoding itself, assuming the data in the Secret is already in the desired final form (or, for full secrets, it structures the raw data as YAML).
    • This behavior is based on the MEMORY item: The USER modified pkg/engine/file/file.go to remove all explicit base64 decoding logic...
In init mode, file injection specified by --inject-on-file typically occurs before environment variables are set up and before the main application binary is executed. This ensures files are present when the application starts.
Example Mappings for --inject-on-file:
  • --inject-on-file=/etc/app/config/api.token=app-tokens.api,/var/run/secrets/db.yaml=db-credentials
    • This would write the value of the api key from the app-tokens secret to /etc/app/config/api.token.
    • It would also write all data from the db-credentials secret as a YAML file to /var/run/secrets/db.yaml.
By understanding these injection mechanisms, you can effectively configure esi-cli to deliver secrets to your applications in the most suitable format and at the right stage of their lifecycle.