external-secrets-inc · gusfcarvalho · Jul 25, 2025 · Jul 25, 2025 · Jul 25, 2025 · Jul 25, 2025
diff --git a/docs.json b/docs.json
@@ -0,0 +1,293 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Starter Kit",
+  "colors": {
+    "primary": "#7300E5",
+    "light": "#FFFFFF",
+    "dark": "#7300E5"
+  },
+  "favicon": "favicon.svg",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "External Secrets Enterprise",
+        "icon": "key",
+        "groups": [
+          {
+            "group": "External Secrets Enterprise",
+            "icon": "key",
+            "pages": [
+              "docs/enterprise/externalsecrets/introduction",
+              "docs/enterprise/externalsecrets/get-started",
+              {
+                "icon": "lines-leaning",
+                "group": "Tutorials",
+                "pages": [
+                  "docs/enterprise/externalsecrets/tutorials/workflows",
+                  "docs/enterprise/externalsecrets/tutorials/dynamic-credentials"
+                ]
+              },
+              {
+                "icon": "wind-turbine",
+                "group": "Generators",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/generators/iam-keys",
+                    "docs/enterprise/externalsecrets/generators/neo4j",
+                    "docs/enterprise/externalsecrets/generators/openai",
+                    "docs/enterprise/externalsecrets/generators/postgresql"
+                  ]
+                },
+                {
+                  "icon": "arrow-progress",
+                  "group": "Workflows",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/workflows/introduction",
+                    "docs/enterprise/externalsecrets/workflows/concepts",
+                    "docs/enterprise/externalsecrets/workflows/preset-workflows",
+                    "docs/enterprise/externalsecrets/workflows/reference",
+                    "docs/enterprise/externalsecrets/workflows/examples",
+                    "docs/enterprise/externalsecrets/workflows/troubleshooting"
+                  ]
+                },
+                {
+                  "icon": "bullseye-arrow",
+                  "group": "Targets",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/targets/index",
+                    "docs/enterprise/externalsecrets/targets/virtual-machine",
+                    "docs/enterprise/externalsecrets/targets/eso-vm-server"
+                  ]
+                },
+                {
+                  "icon": "radar",
+                  "group": "Scanning and Findings",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/scan/introduction"
+                  ]
+                },
+                {
+                  "icon": "webhook",  
+                  "group": "Pod Webhook",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/pod-webhook/index",
+                    "docs/enterprise/externalsecrets/pod-webhook/installation",
+                    "docs/enterprise/externalsecrets/pod-webhook/annotations",
+                    "docs/enterprise/externalsecrets/pod-webhook/usage-examples",
+                    "docs/enterprise/externalsecrets/pod-webhook/troubleshooting"
+                  ]
+                },
+                {
+                  "icon": "terminal",
+                  "group": "ESI CLI",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/esi-cli/index",
+                    "docs/enterprise/externalsecrets/esi-cli/modes",
+                    "docs/enterprise/externalsecrets/esi-cli/flags",
+                    "docs/enterprise/externalsecrets/esi-cli/injection-mechanisms",
+                    "docs/enterprise/externalsecrets/esi-cli/federation",
+                    "docs/enterprise/externalsecrets/esi-cli/usage-examples"
+                  ]
+                },
+                {
+                  "icon": "globe",
+                  "group": "Federation",
+                  "pages": [
+                    "docs/enterprise/externalsecrets/federation/index",
+                    "docs/enterprise/externalsecrets/federation/concepts",
+                    "docs/enterprise/externalsecrets/federation/server-setup",
+                    "docs/enterprise/externalsecrets/federation/client-setup",
+                    "docs/enterprise/externalsecrets/federation/authn-authz",
+                    "docs/enterprise/externalsecrets/federation/example"
+                  ]
+                }
+              ]
+            } 
+        ]
+      },
+      {
+        "tab": "ESI Agent",
+        "groups": [
+          {
+            "group": "ESI Agent",
+            "pages": [
+              {
+                "group": "Getting Started",
+                "pages": [
+                  "docs/enterprise/externalsecrets/esi-agent/quickstart"
+                ]
+              },
+              {
+                "group": "Guides",
+                "pages": [
+                  "docs/enterprise/externalsecrets/esi-agent/guides/namespaced-deployments",
+                  "docs/enterprise/externalsecrets/esi-agent/guides/auto-updates"
+                ]
+              },
+              {
+                "group": "Reference",
+                "pages": [
+                  "docs/enterprise/externalsecrets/esi-agent/reference/api-reference",
+                  "docs/enterprise/externalsecrets/esi-agent/reference/architecture"
+                ]
+              },
+              "docs/enterprise/externalsecrets/esi-agent/troubleshooting"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Audit",
+        "groups": [
+          {
+            "group": "Get Started",
+            "pages": [
+              "docs/enterprise/audit/introduction"
+            ]
+          },
+          {
+            "group": "Get Started",
+            "pages": [
+              "docs/enterprise/audit/installation"
+            ]
+          },
+          {
+            "group": "Dashboard",
+            "pages": [
+              "docs/enterprise/audit/dashboard/lineage",
+              "docs/enterprise/audit/dashboard/filters"
+            ]
+          },
+          {
+            "group": "Destinations",
+            "pages": [
+              "docs/enterprise/audit/destinations/quickstart"
+            ]
+          },
+          {
+            "group": "Policies",
+            "pages": [
+              "docs/enterprise/audit/policies/quickstart",
+              "docs/enterprise/audit/policies/policy-execution-types",
+              {
+                "group": "Examples",
+                "pages": [
+                  "docs/enterprise/audit/policies/examples/access-compliance",
+                  "docs/enterprise/audit/policies/examples/cross-provider-duplication",
+                  "docs/enterprise/audit/policies/examples/ca-verification",
+                  "docs/enterprise/audit/policies/examples/password-compliance",
+                  "docs/enterprise/audit/policies/examples/rotation-compliance"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Listener",
+            "pages": [
+              "docs/enterprise/audit/listener/introduction",
+              {
+                "group": "Providers",
+                "pages": [
+                  "docs/enterprise/audit/listener/providers/hashicorp-vault",
+                  "docs/enterprise/audit/listener/providers/gcp-secret-manager",
+                  "docs/enterprise/audit/listener/providers/aws-secrets-manager",
+                  "docs/enterprise/audit/listener/providers/aws-parameter-store",
+                  "docs/enterprise/audit/listener/providers/azure-key-vault"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Aditional documentation",
+            "pages": [
+              "docs/enterprise/audit/reference/listener-reference",
+              "docs/enterprise/audit/reference/policy-reference",
+              "docs/enterprise/audit/reference/troubleshooting"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Reloader",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "docs/open_source/reloader/introduction"
+            ]
+          },
+          {
+            "group": "Getting Started",
+            "pages": [
+              "docs/open_source/reloader/quickstart"
+            ]
+          },
+          {
+            "group": "Configuration",
+            "pages": [
+              {
+                "group": "Notification Sources",
+                "pages": [
+                  "docs/open_source/reloader/sources/gcp-pubsub-source",
+                  "docs/open_source/reloader/sources/awssqs-source",
+                  "docs/open_source/reloader/sources/vault-source",
+                  "docs/open_source/reloader/sources/azure-eventgrid-source",
+                  "docs/open_source/reloader/sources/webhook-source",
+                  "docs/open_source/reloader/sources/kubernetes-secret-source"
+                ]
+              },
+              {
+                "group": "Trigger Destinations",
+                "pages": [
+                  "docs/open_source/reloader/destinations/deployments",
+                  "docs/open_source/reloader/destinations/external-secrets"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Reference",
+            "pages": [
+              "docs/open_source/reloader/reference/api-reference"
+            ]
+          }
+       ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/docs/logo/logo-esi-full.svg",
+    "dark": "/docs/logo/logo-esi-full-white.svg"
+  },
+  "background": {
+    "color": {
+      "light": "#ffffff",
+      "dark": "#030712"
+    }
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "Open Source",
+        "href": "https://external-secrets.io"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Back to External Secrets",
+      "href": "https://externalsecrets.com"
+    }
+  },
+  "footer": {
+    "socials": {
+      "x": "https://x.com/XSecretsInc",
+      "github": "https://github.com/external-secrets-inc",
+      "linkedin": "https://www.linkedin.com/company/external-secrets-inc"
+    }
+  },
+  "integrations": {
+    "segment": {
+      "key": "nYHwrLGCNSiWISNZYeXtFSNkGHHnrlWX"
+    }
+  }
+}
diff --git a/docs/enterprise/externalsecrets/esi-cli/federation.mdx b/docs/enterprise/externalsecrets/esi-cli/federation.mdx
@@ -1,7 +1,6 @@
 ---
 title: ESI CLI with Federation
 description: Configure and use esi-cli to fetch secrets from an ESI Federation server.
-icon: "network-wired"
 ---
 
 <Note>

diff --git a/docs/enterprise/externalsecrets/esi-cli/flags.mdx b/docs/enterprise/externalsecrets/esi-cli/flags.mdx
@@ -1,7 +1,6 @@
 ---
 title: Command-Line Flags
 description: A comprehensive reference for all esi-cli command-line flags.
-icon: "flag"
 ---
 
 <Note>
@@ -19,7 +18,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.                                                                                                             |
 | `--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. | 

diff --git a/docs/enterprise/externalsecrets/esi-cli/index.mdx b/docs/enterprise/externalsecrets/esi-cli/index.mdx
@@ -1,7 +1,6 @@
 ---
 title: Overview
 description: Command-Line Interface for External Secrets Operator secret injection and management.
-icon: "play"
 ---
 
 <Note>
@@ -16,7 +15,7 @@

 `esi-cli` is a cornerstone for integrating applications with ESO, commonly run within Kubernetes init containers to prepare the secret environment before an application starts, or as a sidecar container to provide and refresh secrets while an application runs.

 It Allows you to effectively run applications without creating a Kubernetes Secret beforehand, while still leveraging all of ESO's powerful features such as combination and templating. 

 It features distinct modes of operation, a comprehensive set of command-line flags for granular control, and robust support for [ESI Federation](/docs/enterprise/externalsecrets/federation/index), allowing secret access from centralized ESI servers.


diff --git a/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx b/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx
@@ -1,7 +1,6 @@
 ---
 title: Secret Injection Mechanisms
 description: Learn how esi-cli injects secrets as environment variables and files.
-icon: "syringe"
 ---
 
 <Note>

diff --git a/docs/enterprise/externalsecrets/esi-cli/modes.mdx b/docs/enterprise/externalsecrets/esi-cli/modes.mdx
@@ -1,7 +1,6 @@
 ---
 title: Modes of Operation
 description: Understand the init and daemon modes of esi-cli.
-icon: "toggle-on"
 ---
 
 <Note>
@@ -77,7 +76,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.

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

diff --git a/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx b/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx
@@ -1,7 +1,6 @@
 ---
 title: Examples
 description: Practical examples for using esi-cli in different modes.
-icon: "books"
 ---
 
 <Note>

diff --git a/docs/enterprise/externalsecrets/federation/authn-authz.mdx b/docs/enterprise/externalsecrets/federation/authn-authz.mdx
@@ -1,7 +1,6 @@
 ---
 title: Authentication & Authorization
 description: Delve into the security mechanisms that protect federated secret access.
-icon: "lock"
 ---
 
 <Note>
@@ -48,7 +47,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.
    *   **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).

@@ -61,7 +60,7 @@
    *   The Federation Client receives the secret data and processes it (e.g., `esi-cli` injects it into the environment or files).

 <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.
 </Warning>

 This flow is fundamental to the security model of ESI Federation, enabling robust cross-cluster secret management.
diff --git a/docs/enterprise/externalsecrets/federation/client-setup.mdx b/docs/enterprise/externalsecrets/federation/client-setup.mdx
@@ -1,7 +1,6 @@
 ---
 title: Federation Client Setup
 description: Discover how to set up esi-cli and ESE instances as Federation Clients.
-icon: "users"
 ---
 
 <Note>
@@ -28,7 +27,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.

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

diff --git a/docs/enterprise/externalsecrets/federation/concepts.mdx b/docs/enterprise/externalsecrets/federation/concepts.mdx
@@ -1,7 +1,6 @@
 ---
 title: Core Concepts
 description: Understand the fundamental components and ideas behind ESI Federation.
-icon: "brain"
 ---
 
 <Note>
@@ -31,7 +30,7 @@
        *   Other ESE instances: An ESE deployment in a different cluster can be configured to act as a client to a central Federation Server.

 *   **Authentication**:
    *   Federation Clients authenticate to the Federation Server using Kubernetes Service Account (SA) JSON Web Tokens (JWTs) from their own cluster.
    *   The Federation Server validates these tokens by fetching the client cluster's public keys (JWKS).

 *   **Authorization**:

diff --git a/docs/enterprise/externalsecrets/federation/example.mdx b/docs/enterprise/externalsecrets/federation/example.mdx
@@ -1,7 +1,6 @@
 ---
 title: Examples
 description: Walk through a practical example of setting up and using ESI Federation.
-icon: "books"
 ---
 
 <Note>
@@ -87,7 +86,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.
   ```yaml
   # Filename: sa-prometheus-esi-client.yaml on client-cluster-alpha
   apiVersion: v1

diff --git a/docs/enterprise/externalsecrets/federation/index.mdx b/docs/enterprise/externalsecrets/federation/index.mdx
@@ -1,7 +1,6 @@
 ---
 title: Overview
 description: Securely access secrets across multiple Kubernetes clusters with External Secrets Enterprise Federation.
-icon: "play"
 ---
 
 <Note>

diff --git a/docs/enterprise/externalsecrets/federation/server-setup.mdx b/docs/enterprise/externalsecrets/federation/server-setup.mdx
@@ -1,7 +1,6 @@
 ---
 title: Federation Server Setup
 description: Learn how to configure the Federation Server, including CRDs and API endpoints.
-icon: "network-wired"
 ---
 
 <Note>
@@ -10,9 +9,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.

 ## Custom Resource Definitions (CRDs)

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

@@ -52,9 +51,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.
    *   `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.

 **Example `Authorization` CR:**
 ```yaml
@@ -78,7 +77,7 @@
 ```

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

 ## Federation Server API Endpoints
@@ -98,11 +97,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).
    *   **Permissions**: Depends on the generator's capabilities and specific authorization rules.

 <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.
 </Info>

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