The External Secrets Enterprise is product suite is a premium product. It requires a specific subscription. Contact us for more information.
esi-cli can fetch secrets not only from ExternalSecret resources within the local Kubernetes cluster but also from a centralized ESI Federation server. This allows for managing secrets across multiple clusters or environments from a single point of control. To use esi-cli in federation mode, you primarily need to specify the URL of the ESI Federation server using the --federated-server-url flag. Several other flags help configure how esi-cli interacts with the federation server.

​
Enabling Federation Mode

Setting the --federated-server-url flag is the key to activating federation mode. Once set, esi-cli will direct its secret fetching requests to this URL instead of querying the local Kubernetes API for ExternalSecret resources directly for those federated requests.
When operating in federation mode, esi-cli still requires a valid Kubernetes environment (e.g., to access the service account token for authentication), but the source of truth for the requested secrets shifts to the ESI Federation server.

​
Key Federation Flags

These flags are specifically used to configure esi-cli’s interaction with an ESI Federation server. Refer to the main Command-Line Flags page for their default values and general notes.
  • --federated-server-url="<url>"
    • Required for federation mode.
    • Specifies the complete URL of the ESI Federation server (e.g., https://esi-federation.example.com).
  • --federated-store="<store_name>"
    • Specifies the name of a SecretStore or ClusterSecretStore that is configured and accessible on the ESI Federation server.
    • The federation server will use this store to fetch the actual secret data from its backend (e.g., Vault, AWS Secrets Manager).
  • --federated-generators="<generator_name>"
    • Specifies the name of a generator configuration to use on the ESI Federation server.
    • This is used when you need the federation server to generate secrets dynamically (e.g., dynamic database credentials, signed tokens).
    Typically, you will use either --federated-store (to fetch existing secrets) or --federated-generators (to request dynamically generated secrets), or sometimes both, depending on the ESI Federation server’s capabilities and your needs.
  • --federated-token="<path_to_token_file>"
    • Path to the Kubernetes service account token file.
    • esi-cli uses this token to authenticate itself to the ESI Federation server. The service account associated with this token must be authorized by the federation server to request secrets.
    • Defaults to /var/run/secrets/kubernetes.io/serviceaccount/token.
  • --federated-ca-crt="<path_to_ca_bundle>"
    • Path to the CA certificate bundle file.
    • Used to verify the TLS certificate of the ESI Federation server. This is crucial if the federation server uses TLS certificates signed by a custom CA or are self-signed.
    • Defaults to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.

​
How Federation Works with esi-cli

  1. Request Initiation: esi-cli (e.g., in an init container) starts up.
  2. Authentication: It reads the service account token specified by --federated-token.
  3. Secure Connection: It establishes a TLS connection to the --federated-server-url, optionally verifying the server’s certificate against the --federated-ca-crt.
  4. Secret Request: esi-cli sends a request to the federation server, including the token for authentication and specifying the desired secrets via --inject-on-env or --inject-on-file mappings. These mappings are interpreted by the federation server in conjunction with --federated-store or --federated-generators.
    • For example, if using --inject-on-env=API_KEY=my-remote-secret.api-token and --federated-store=central-vault, esi-cli asks the federation server to retrieve api-token from the my-remote-secret (which the federation server resolves via central-vault).
  5. Secret Delivery: The federation server processes the request, fetches/generates the secret, and returns it to esi-cli.
  6. Injection: esi-cli then injects the received secret data as environment variables or files, just as it would with locally sourced secrets.

​
Example: Init Mode with Federation

Fetch a secret named token from a federated secret (details resolved by the federation server via central-vault) and inject it as the environment variable FED_API_TOKEN. Then, execute the /app/my-client application. 
esi-cli --mode=init \
  --namespace=app-ns \
  --inject-on-env=FED_API_TOKEN=federated-secret-name.token-key \
  --binary-path=/app/my-client \
  --federated-server-url="https://esi-federation.corp.example.com" \
  --federated-store="central-vault" \
  --federated-token="/var/run/secrets/tokens/federation-client-token" # Optional: if not using default SA token
Explanation:
  • --mode=init: esi-cli will set up the environment and execute /app/my-client.
  • --inject-on-env=FED_API_TOKEN=federated-secret-name.token-key: Instructs esi-cli to request token-key from a secret identified as federated-secret-name by the federation server, and make it available as the FED_API_TOKEN environment variable.
  • --binary-path=/app/my-client: The application to run after injection.
  • --federated-server-url: Specifies the ESI Federation server.
  • --federated-store="central-vault": Tells the federation server to use its central-vault configuration to find federated-secret-name.
  • --federated-token: (Optional in this example) If the pod’s default service account token is not the one authorized for federation, or if a specific token with fewer privileges is desired, its path can be provided.
The actual names like federated-secret-name.token-key and central-vault are interpreted by the ESI Federation server. Ensure these correspond to valid configurations on your federation server.
Using esi-cli with ESI Federation provides a powerful way to decouple secret consumption from specific clusters, enhancing security and manageability in distributed environments.