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.
Once a Federation Server is operational, clients need to be configured to communicate with it to fetch secrets. The primary clients for ESI Federation are esi-cli and other External Secrets Enterprise Edition instances.

​
esi-cli as a Federation Client

esi-cli is designed to seamlessly integrate with an ESI Federation Server. It uses specific command-line flags to direct its secret requests to the federation server instead of looking for ExternalSecret resources in the local Kubernetes cluster. Key Flags for esi-cli Federation Mode:
  • --federated-server-url="<URL>"
    • Required to enable federation mode.
    • Specifies the full HTTP(S) URL of the ESI Federation Server (e.g., https://esi-federation.example.com).
  • --federated-store="<store_name>"
    • The name of the ClusterSecretStore (defined on the Federation Server) that esi-cli should request secrets from.
    • When used, esi-cli implicitly targets the /secretstore/:secretStoreName/... API endpoint on the server.
  • --federated-generators="<generator_name>"
    • The name of the Generator (defined on the Federation Server) that esi-cli should use to generate secrets.
    • When used, esi-cli implicitly targets the /generators/:generatorNamespace/:generatorKind/:generatorName/... API endpoint on the server. The namespace and kind are often inferred or configured alongside the generator name on the server or client.
  • --federated-token="<path_to_token_file>"
    • Specifies the file path to the Kubernetes Service Account (SA) token that esi-cli will use to authenticate itself to the Federation Server.
    • Defaults to /var/run/secrets/kubernetes.io/serviceaccount/token (the default projected SA token in a pod).
    • The Service Account associated with this token must be authorized on the Federation Server via an Authorization CR.
  • --federated-ca-crt="<path_to_ca_bundle>"
    • Specifies the file path to the CA certificate bundle.
    • This CA bundle is used by esi-cli to verify the TLS certificate of the Federation Server. It’s also sent to the Federation Server, which uses it to securely fetch the JWKS (public keys) from the client cluster’s token issuer to validate the client’s SA token.
    • Defaults to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.
How esi-cli uses these flags: When these flags are provided, esi-cli:
  1. Reads the SA token from --federated-token.
  2. Reads the CA certificate from --federated-ca-crt.
  3. Constructs a request to the appropriate endpoint on the --federated-server-url.
  4. Includes the SA token in the Authorization: Bearer <token> header.
  5. Includes the client’s CA certificate (base64 encoded) in the request body, typically as {"ca.crt": "<base64_encoded_ca_cert>"}. This allows the Federation Server to trust the client cluster’s OIDC discovery endpoint for JWKS.
  6. Receives secret data and injects it as environment variables (--inject-on-env, --external-secrets) or files (--inject-on-file) as per other esi-cli configurations.
Refer to the esi-cli documentation for more detailed examples of esi-cli with federation.

​
ESE as a Federation Client

An External Secrets Enterprise Edition instance, typically running in a different Kubernetes cluster, can also act as a client to a central ESI Federation Server. This allows a distributed ESE setup where one ESE instance (the client) offloads the actual secret fetching from backend stores to another ESE instance (the Federation Server). Configuration Method: This is generally achieved by creating a special type of SecretStore or ClusterSecretStore on the client ESE instance. This custom store resource would encapsulate the necessary configuration to connect and authenticate to the remote Federation Server. Conceptual FederationStore (Example Kind): While the exact CRD specification might vary, a hypothetical FederationStore on the client ESE instance could look like this: 
apiVersion: external-secrets.io/v1beta1 # Or a similar API group for custom stores
kind: FederationStore # This is a conceptual kind name
metadata:
  name: central-federation-server
  namespace: external-secrets # Or where your client ESE is running
spec:
  provider:
    type: Federation # Indicates this store connects to an ESI Federation Server
    url: https://esi-federation.example.com # URL of the Federation Server
    # Credentials for the client ESE to authenticate to the Federation Server
    auth:
      serviceAccountRef:
        name: federation-client-sa # SA in the client ESE's cluster
        namespace: external-secrets
        # The token and ca.crt from this SA would be used
    # Optionally, specify which remote store on the Federation Server to target by default
    remoteStoreRef:
      name: vault-backend-on-federation-server
Usage: Once such a FederationStore is defined on the client ESE instance:
  1. You would create ExternalSecret resources on the client cluster that reference this FederationStore (e.g., storeRef.name: central-federation-server).
  2. The client ESE controller, when processing these ExternalSecrets, would use the details from the FederationStore to:
    • Authenticate to the specified Federation Server URL using the configured client-side Service Account token.
    • Request the secret data (e.g., by passing through the ExternalSecret’s dataFrom or data fields, which would be interpreted by the Federation Server in context of its own stores like vault-backend-on-federation-server).
  3. The client ESE then creates the local Kubernetes Secret as usual, but populated with data received from the Federation Server.
The precise implementation details and CRD for configuring an ESE instance as a federation client (e.g., the FederationStore kind) should be referred to in the specific ESE version documentation. The concept remains: abstracting the connection to the Federation Server within a store definition.
This client-server model allows for flexible and secure secret distribution architectures, catering to various organizational needs and security postures.