Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions docs/enterprise/audit/destinations/quickstart.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
title: Quickstart
description: Configure a destination for audit triggers
icon: 'rocket'
---

<Note>
The External Secrets Inc. Audit & Compliance product suite is a premium product.
It requires a specific subscription. Contact us for more information.
</Note>

<Note>
To follow this guide, ensure the [Audit Listener is installed and configured](/docs/enterprise/audit/installation).
</Note>

This guide will walk you through creating a Destination that receives audit events triggered by policies, such as a Webhook.

## Create a Destination

1. Navigate to the Destinations section in the left sidebar.
2. Click "Create New Destination".
3. Fill in the following fields:

- Name: A human-readable label (e.g., `Reloader Webhook`)
- Identifier: A unique ID (e.g., `reloader-webhook`)
- Type: Select `Webhook` from the dropdown

4. In the Configuration section, provide:

- URL: The endpoint that should receive the audit events
Example: `http://reloader-controller-manager-webhook.external-secrets-reloader`
- CA Bundle: *(Optional)* Include if using HTTPS with a custom certificate
- Auth method: Choose the appropriate authentication method (e.g., `NONE`, `BASIC`, or `TOKEN`)
- Event Format: Select `CLOUD_EVENTS` to send audit payloads in CloudEvents format

5. Click "Create" to finalize the destination.

You should now see your new destination listed and ready to be assigned to audit policies.

---

### 📌 What's Next?

After creating a destination:

- [Create or edit a policy](/docs/enterprise/audit/policies/quickstart) to send events to this destination. You can read how to do it in the policy's [Add Triggers to the Policy](/docs/enterprise/audit/policies/quickstart#add-triggers-to-the-policy) section.

> Destinations can be reused across multiple policies.
12 changes: 6 additions & 6 deletions docs/enterprise/audit/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
alt="Add a New Audit Listener"
/>
* Click `Install Listener` button within the UI.
* Select the Kubernets Installation Method. A `curl` command will appear to download and apply kubernetes manifests to the cluster.

Check warning on line 29 in docs/enterprise/audit/installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/installation.mdx#L29

Did you really mean 'Kubernets'?

<img
className="block dark:hidden"
Expand Down Expand Up @@ -70,7 +70,7 @@
/>
* Click `Install Listener` button within the UI
* Select the Bash Installation Method. A `curl` command will appear to download and install binaries within a VM.
This script will also install all the needed systemd entries.

Check warning on line 73 in docs/enterprise/audit/installation.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/installation.mdx#L73

Did you really mean 'systemd'?

<img
className="block dark:hidden"
Expand All @@ -89,9 +89,9 @@
## Next

* Create a Provider:
* [Create a Hashicorp Vault Provider](/docs/audit/listener/providers/hashicorp-vault)
* [Create a AWS Secrets Manager Provider](/docs/audit/listener/providers/aws-secrets-manager)
* [Create a AWS Parameter Store Provider](/docs/audit/listener/providers/aws-parameter-store)
* [Create a Azure Key Vault Provider](/docs/audit/listener/providers/azure-key-vault)
* [Create a GCP Secret Manager Provider](/docs/audit/listener/providers/gcp-secret-manager)
* [Create your first policy](/docs/audit/policies/quickstart)
* [Create a Hashicorp Vault Provider](/docs/enterprise/audit/listener/providers/hashicorp-vault)
* [Create a AWS Secrets Manager Provider](/docs/enterprise/audit/listener/providers/aws-secrets-manager)
* [Create a AWS Parameter Store Provider](/docs/enterprise/audit/listener/providers/aws-parameter-store)
* [Create a Azure Key Vault Provider](/docs/enterprise/audit/listener/providers/azure-key-vault)
* [Create a GCP Secret Manager Provider](/docs/enterprise/audit/listener/providers/gcp-secret-manager)
* [Create your first policy](/docs/enterprise/audit/policies/quickstart)
6 changes: 3 additions & 3 deletions docs/enterprise/audit/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -82,16 +82,16 @@
This is the main component responsible to do the heavy work for audit and compliance.
It is responsible to connect to each provider (see providers section to know more about how each provider is connected) and to generate events & policy compliance according to events.

It is also responsible to keep track on accessors, duplication, and rotation across configured providers.

Check warning on line 85 in docs/enterprise/audit/introduction.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/introduction.mdx#L85

Did you really mean 'accessors'?

The Audit Listener is responsible to process events from these providers and calculates results in the fashion of metrics.

These results do not contain any sensitive data (only metadata of the results on the activities performed by the listener).

These metrics are available directly to the end user (via a prometheus endpoint) and transmitted directly to the audit dashboard.

Check warning on line 91 in docs/enterprise/audit/introduction.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/introduction.mdx#L91

Did you really mean 'prometheus'?

## Next Steps

* [Install the Audit Listener within your premises](./docs/audit/installation)
* [Create your first policy](./docs/audit/guides/policies/quickstart)
* [Create your first provider](./docs/audit/guides/providers/quickstart)
* [Install the Audit Listener within your premises](/docs/enterprise/audit/installation)
* [Create your first destination](/docs/enterprise/audit/destinations/quickstart)
* [Create your first policy](/docs/enterprise/audit/policies/quickstart)
2 changes: 1 addition & 1 deletion docs/enterprise/audit/listener/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
</Note>

## Audit Listener
Audit Listener is the component responsible for receiving audit logs from external providers and process them into consumable, actionable KPIs.

Check warning on line 13 in docs/enterprise/audit/listener/introduction.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/listener/introduction.mdx#L13

Did you really mean 'KPIs'?

It is also responsible to calculate policies and generate metrics accordingly.

Expand All @@ -30,7 +30,7 @@
### Extension with Policies

The Audit Listener also supports extending its behavior by allowing it to compute policies on different events.
To understand more how policies work, check [Policies](/docs/audit/policies/quickstart).
To understand more how policies work, check [Policies](/docs/enterprise/audit/policies/quickstart).

Once a new policy is created, the listener will start computing it and store the following information:
* Which policies a given secret is non compliant to at a given point in time
Expand Down
2 changes: 1 addition & 1 deletion docs/enterprise/audit/policies/policy-execution-types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The exception is the `Results` policy type, which is evaluated after the secret

Every event message has a `OriginalPayload` field that contains the original event message sent from the provider.
From this message, it is possible to create policy logic that depends on specific provider information (such as audit log dates, authorization fields, or generic policy parsing).
Check [Provider Session](/docs/audit/providers/quickstart) to get more information on each `OriginalPayload` format.
Check [Provider Session](/docs/enterprise/audit/listener/introduction) to get more information on each `OriginalPayload` format.

### Policy Execution Types

Expand Down
27 changes: 25 additions & 2 deletions docs/enterprise/audit/policies/quickstart.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Quickstart
description: Create a policy using Rego language

Check warning on line 3 in docs/enterprise/audit/policies/quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/policies/quickstart.mdx#L3

Did you really mean 'Rego'?
icon: 'rocket'
---

Expand All @@ -10,9 +10,9 @@
</Note>

<Note>
In order to follow this guide, be sure to already have the [Audit Listener installed and configured](./docs/audit/quickstart).
In order to follow this guide, be sure to already have the [Audit Listener installed and configured](/docs/enterprise/audit/installation).
</Note>
This guide will help you create a policy using Rego language within the External Secrets Dashboard.

Check warning on line 15 in docs/enterprise/audit/policies/quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/audit/policies/quickstart.mdx#L15

Did you really mean 'Rego'?

## Create a Policy
1. Navigate to the Policies section in the left sidebar
Expand Down Expand Up @@ -40,7 +40,30 @@

Change the Sample `ActorIdentifier` field to `"my-credentials"`, and check that the rule is now valid and would result in a compliant state.

Submit the Rule.
Submit the Rule or add a trigger to it.

### Add Triggers to the Policy

Triggers define when the result of a policy evaluation should generate a notification and send it to a [destination](/docs/enterprise/audit/destinations/quickstart).

To add a trigger:

1. Navigate to the Triggers tab of the policy creation form.
2. Click "Add Trigger".
3. Fill in the following fields:

- Destination: Select one or more existing destinations (e.g., `reloader-webhook`)
- Condition: Choose when the trigger should fire. Options include:
- `EvaluatedNonCompliant`: Fires every time the policy is evaluated as non-compliant
- `EvaluatedCompliant`: Fires every time the policy is evaluated as compliant
- `UpdatedToNonCompliant`: Fires only when the status transitions from compliant to non-compliant
- `UpdatedToCompliant`: Fires only when the status transitions from non-compliant to compliant
- Wait for Cycles: (Optional) Number of evaluation cycles to wait before sending the event.
- For example, setting `waitForCycles = 3` with `EvaluatedNonCompliant` means the policy must be non-compliant for 3 consecutive evaluations before the destination is notified.

You can add multiple triggers with different conditions and destinations.

Once configured, Submit to finalize your policy with its associated triggers.

## Assigning a Policy to a Provider

Expand Down
12 changes: 6 additions & 6 deletions docs/enterprise/externalsecrets/esi-cli/federation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ To use `esi-cli` in federation mode, you primarily need to specify the URL of th

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.

<Callout type="info">
<Info>
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.
</Callout>
</Info>

## Key Federation Flags

Expand All @@ -38,9 +38,9 @@ These flags are specifically used to configure `esi-cli`'s interaction with an E
* 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).

<Callout type="note">
<Note>
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.
</Callout>
</Note>

* `--federated-token="<path_to_token_file>"`
* Path to the Kubernetes service account token file.
Expand Down Expand Up @@ -85,8 +85,8 @@ esi-cli --mode=init \
* `--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.

<Callout type="important">
<Warning>
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.
</Callout>
</Warning>

Using `esi-cli` with ESI Federation provides a powerful way to decouple secret consumption from specific clusters, enhancing security and manageability in distributed environments.
8 changes: 4 additions & 4 deletions docs/enterprise/externalsecrets/esi-cli/flags.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
| Flag | Description | Default Value | Required By/Notes |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--mode` | Specifies the operation mode for `esi-cli`. | (none) | **Required**. Must be `init` or `daemon`. See [Modes of Operation](./modes) for details. |
| `--namespace` | The Kubernetes namespace where `esi-cli` should look for `ExternalSecret` resources. | Value of the `KUBERNETES_NAMESPACE` environment variable, or `"default"` if not set. | Relevant when not using federation. |

Check warning on line 22 in docs/enterprise/externalsecrets/esi-cli/flags.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/esi-cli/flags.mdx#L22

Did you really mean 'namespace'?
| `--external-secrets` | A comma-separated list of `ExternalSecret` names to process. `esi-cli` will fetch all data from the Kubernetes `Secret` resources managed by these `ExternalSecret`s. | `""` (empty string) | In `init` mode, this data is typically injected as environment variables. |
| `--inject-on-env` | A comma-separated list of specific environment variable injections. The format for each injection is `ENV_VAR_NAME=secretName.key`. | `""` | Primarily used in `init` mode. Allows precise mapping of secret keys to environment variable names. Overrides general env vars from `--external-secrets` if names conflict. |
| `--inject-on-file` | A comma-separated list of file injections. The format is `/path/to/target/file=secretName.key` or `/path/to/target/file=secretName`. | `""` | Used in both `init` and `daemon` modes. If `.key` is omitted (e.g., `/path/to/secret.yaml=mySecret`), the full secret data is written as a YAML file. `esi-cli` automatically creates parent directories if they don't exist. |
Expand All @@ -31,9 +31,9 @@

These flags are used when `esi-cli` is configured to fetch secrets from a central ESI Federation server, rather than directly from `ExternalSecret` resources in the local Kubernetes cluster.

<Callout type="info">
<Info>
Using `--federated-server-url` enables federation mode. When in federation mode, flags like `--namespace` and `--external-secrets` (referring to local Kubernetes resources) are typically not the primary source of secrets, though `--namespace` might still be used for resolving local service account tokens if paths are not absolute.
</Callout>
</Info>

| Flag | Description | Default Value | Notes |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -43,8 +43,8 @@
| `--federated-token` | The file path to the Kubernetes service account token that `esi-cli` will use to authenticate with the federated ESI server. | `/var/run/secrets/kubernetes.io/serviceaccount/token` | The service account associated with this token must be authorized by the ESI Federation server. |
| `--federated-ca-crt` | The file path to the CA certificate bundle used to verify the TLS certificate of the federated ESI server. | `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` | Essential for secure communication if the federation server uses a custom CA or self-signed certificates. |

<Callout type="warning">
<Warning>
When using federation, either `--federated-store` or `--federated-generators` (or both, depending on the federation server's setup and the desired secrets) is typically required along with `--federated-server-url`.
</Callout>
</Warning>

For more context on how these flags are used, refer to the [Modes of Operation](./modes), [Injection Mechanisms](./injection-mechanisms), [Federation](./federation), and [Usage Examples](./usage-examples) pages.
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ There are two main ways to control environment variable injection:
* This allows you to pick specific keys from different `ExternalSecret`s (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.

<Callout type="info">
<Info>
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.
</Callout>
</Info>

## File Injection

Expand All @@ -50,9 +50,9 @@ File injection is controlled by the `--inject-on-file` flag.
* **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...`

<Callout type="note">
<Note>
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.
</Callout>
</Note>

**Example Mappings for `--inject-on-file`**:

Expand Down
8 changes: 4 additions & 4 deletions docs/enterprise/externalsecrets/esi-cli/modes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,9 @@
--args="--your-app-flags=true, --config-file=/app/config/settings.yaml"
```

<Callout type="info">
<Info>
The `--binary-path` flag is **required** when using `--mode=init`.
</Callout>
</Info>

## `daemon` Mode (`--mode=daemon`)

Expand All @@ -77,7 +77,7 @@
* **Long-Lived Process**: Unlike `init` mode, `esi-cli` in `daemon` mode runs as a long-lived process. It does **not** execute another binary.
* **Secret Refreshing & Watching**:
* **Local Kubernetes Mode**: When fetching secrets directly from `ExternalSecret` resources in the same cluster (i.e., not using federation), `esi-cli` can watch for changes to these `ExternalSecret` resources. If a change is detected, it re-fetches the secrets and updates the target files.
* **Federation Mode / Fallback**: It uses a periodic refresh interval, defined by `--daemon-refresh-interval` (defaulting to 2 minutes), to periodically re-fetch secrets and update files. This is the primary refresh mechanism when using ESI Federation and also serves as a fallback resync mechanism in local mode.

Check warning on line 80 in docs/enterprise/externalsecrets/esi-cli/modes.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/esi-cli/modes.mdx#L80

Did you really mean 'resync'?

**Primary Use Case:**
To provide secrets as files to a running application, with the capability for those files to be automatically updated if the underlying secrets change in the source (either Kubernetes `ExternalSecret` or a federated ESI server).
Expand Down Expand Up @@ -143,8 +143,8 @@
--daemon-refresh-interval=5m
```

<Callout type="warning">
<Warning>
Applications consuming files written by `esi-cli` in `daemon` mode should be capable of detecting changes to these files and reloading their configuration if they need to pick up updated secret values dynamically.
</Callout>
</Warning>

Understanding these two modes is fundamental to effectively using `esi-cli` to manage secrets for your applications. Choose the mode that best fits your application's architecture and secret consumption patterns.
4 changes: 2 additions & 2 deletions docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ esi-cli --mode=daemon \
* `esi-cli` will monitor the source `ExternalSecret`s for changes and update these files. Parent directories will be created if they don't exist.
4. `--daemon-refresh-interval=5m`: Sets the periodic refresh/resync interval to 5 minutes.

<Callout type="note">
<Note>
Applications reading files managed by `esi-cli` in `daemon` mode should be designed to detect file changes and reload their configuration if they need to use updated secret values.
</Callout>
</Note>

These examples illustrate common patterns for using `esi-cli`. You can combine flags as needed to suit your specific secret injection requirements. Always refer to the [Command-Line Flags](./flags) documentation for a complete list of options.
4 changes: 2 additions & 2 deletions docs/enterprise/externalsecrets/federation/authn-authz.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@
* It extracts the `issuer` (e.g., `https://kubernetes.default.svc.cluster.local` of the client) and `subject` (e.g., `system:serviceaccount:client-namespace:client-sa-name`) claims from the validated token.
* **Matching `Authorization` CR**: The server searches for `Authorization` Custom Resources defined on its own cluster.
* It looks for an `Authorization` CR where `spec.subject.issuer` and `spec.subject.subject` exactly match the claims from the client's token.
* **Verifying `KubernetesFederation` Link**: It checks that the matched `Authorization` CR's `spec.federationRef.name` points to a valid `KubernetesFederation` CR. The `url` in this `KubernetesFederation` CR should correspond to the client cluster whose JWKS URI was used for token validation. This ensures the authorization rule is indeed for the authenticated cluster.

Check warning on line 51 in docs/enterprise/externalsecrets/federation/authn-authz.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/authn-authz.mdx#L51

Did you really mean 'CR's'?
* **Checking Permissions**: If a matching and valid `Authorization` CR is found, the server checks if the resource requested by the client (e.g., a specific `ClusterSecretStore` name or a `Generator` name/kind/namespace) is listed in the `allowedClusterSecretStores` or `allowedGenerators` sections of that `Authorization` CR.
* If no matching `Authorization` CR is found, or if the requested resource is not permitted, the request is rejected (Authorization Failed).

Expand All @@ -60,8 +60,8 @@
5. **Client Receives Secret (Client-Side)**:
* The Federation Client receives the secret data and processes it (e.g., `esi-cli` injects it into the environment or files).

<Callout type="important">
<Warning>
This multi-step process, involving cryptographic validation of tokens and explicit policy checks via CRDs, ensures that secret data is only shared between trusted and explicitly authorized entities.

Check warning on line 64 in docs/enterprise/externalsecrets/federation/authn-authz.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/authn-authz.mdx#L64

Did you really mean 'CRDs'?
</Callout>
</Warning>

This flow is fundamental to the security model of ESI Federation, enabling robust cross-cluster secret management.
6 changes: 3 additions & 3 deletions docs/enterprise/externalsecrets/federation/client-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@

* `--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.

Check warning on line 31 in docs/enterprise/externalsecrets/federation/client-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/client-setup.mdx#L31

Did you really mean 'namespace'?

* `--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.
Expand All @@ -50,7 +50,7 @@
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](./../../esi-cli/federation) for more detailed examples of `esi-cli` with federation.
Refer to the [`esi-cli` documentation](/docs/enterprise/externalsecrets/esi-cli/federation) for more detailed examples of `esi-cli` with federation.

## ESE as a Federation Client

Expand Down Expand Up @@ -94,8 +94,8 @@
* 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.

<Callout type="note">
<Note>
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.
</Callout>
</Note>

This client-server model allows for flexible and secure secret distribution architectures, catering to various organizational needs and security postures.
4 changes: 2 additions & 2 deletions docs/enterprise/externalsecrets/federation/example.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@
### 2. On the Client Cluster (`client-cluster-alpha`)

**A. Create the Service Account:**
Ensure the `prometheus-esi-client` ServiceAccount exists in the `monitoring` namespace.

Check warning on line 90 in docs/enterprise/externalsecrets/federation/example.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/example.mdx#L90

Did you really mean 'namespace'?
```yaml
# Filename: sa-prometheus-esi-client.yaml on client-cluster-alpha
apiVersion: v1
Expand Down Expand Up @@ -169,8 +169,8 @@
8. `esi-cli` injects the secrets as environment variables or files (e.g., sets `MY_APP_DB_PASSWORD` or writes to `/etc/secrets/service-a.token`).
9. The init container completes, and the main Prometheus container starts with the secrets available.

<Callout type="success">
<Tip>
This setup successfully allows `client-cluster-alpha` to consume secrets managed by `cluster-main`'s Vault instance without `client-cluster-alpha` (or its applications) needing any direct credentials or network access to Vault. The Federation Server acts as a secure intermediary.
</Callout>
</Tip>

This example illustrates the power and flexibility of ESI Federation for managing secrets in a distributed environment.
8 changes: 4 additions & 4 deletions docs/enterprise/externalsecrets/federation/server-setup.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Federation Server Setup
description: Learn how to configure the Federation Server, including CRDs and API endpoints.

Check warning on line 3 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L3

Did you really mean 'CRDs'?
icon: "network-wired"
---

Expand All @@ -10,9 +10,9 @@
</Note>


Setting up an External Secrets Enterprise (ESE) instance as a Federation Server involves configuring specific Custom Resources (CRDs) that define how it interacts with client clusters and what permissions clients have. The server also exposes dedicated API endpoints for clients to request secrets.

Check warning on line 13 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L13

Did you really mean 'CRDs'?

## Custom Resource Definitions (CRDs)

Check warning on line 15 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L15

Did you really mean 'CRDs'?

The federation feature introduces two key Custom Resource Definitions that are typically applied on the **Federation Server** cluster.

Expand Down Expand Up @@ -52,9 +52,9 @@
* `allowedGenerators` (array of objects, optional): A list of `Generator` resources (defined on the Federation Server) that the client identity is allowed to access. Each object in the list should specify:
* `name` (string, **required**): The name of the Generator.
* `kind` (string, **required**): The kind of the Generator (e.g., `VaultDynamicSecret`, `Password`).
* `namespace` (string, **required**): The namespace where the Generator is defined on the Federation Server.

Check warning on line 55 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L55

Did you really mean 'namespace'?
* `allowedGeneratorStates` (array of objects, optional): Advanced permission for allowing the client to manage (e.g., delete) `GeneratorState` objects on the Federation Server. Each object specifies:
* `namespace` (string, **required**): The namespace on the Federation Server where the `GeneratorState` objects reside.

Check warning on line 57 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L57

Did you really mean 'namespace'?

**Example `Authorization` CR:**
```yaml
Expand All @@ -77,9 +77,9 @@
namespace: federation-generators
```

<Callout type="important">
<Warning>
Both `KubernetesFederation` and `Authorization` CRs must be correctly configured on the Federation Server for clients to authenticate and be authorized to access secrets.

Check warning on line 81 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L81

Did you really mean 'CRs'?
</Callout>
</Warning>

## Federation Server API Endpoints

Expand All @@ -98,11 +98,11 @@
* **Permissions**: Requires appropriate `allowedGeneratorStates` or specific generator-level permissions.

* `POST /generators/:generatorNamespace/revoke`
* **Purpose**: Allows an authorized client to request revocation of credentials related to a generator type within a namespace (e.g., revoking all tokens issued by a specific Vault PKI generator for that client).

Check warning on line 101 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L101

Did you really mean 'namespace'?
* **Permissions**: Depends on the generator's capabilities and specific authorization rules.

<Callout type="info">
<Info>
The request body for these endpoints, beyond the authentication details (like `ca.crt` for the client cluster's JWKS endpoint), may include parameters specific to the action, such as inputs for a generator. `esi-cli` handles the construction of these requests based on its command-line flags.
</Callout>
</Info>

Properly configuring these CRDs and understanding the API endpoints are key to operating a secure and functional ESI Federation Server.

Check warning on line 108 in docs/enterprise/externalsecrets/federation/server-setup.mdx

View check run for this annotation

Mintlify / Mintlify Validation - vale-spellcheck

docs/enterprise/externalsecrets/federation/server-setup.mdx#L108

Did you really mean 'CRDs'?
Loading
Loading