From 190fa84d88caf91d133767fb81de8cf875427628 Mon Sep 17 00:00:00 2001 From: msfernandes Date: Sat, 4 Oct 2025 01:29:06 -0300 Subject: [PATCH] feat: update apiversions and add spiffefederation docs --- .../externalsecrets/federation/example.mdx | 2 +- .../federation/server-setup.mdx | 43 +++++++++++++++++-- .../tutorials/dynamic-credentials.mdx | 2 +- 3 files changed, 42 insertions(+), 5 deletions(-) diff --git a/docs/enterprise/externalsecrets/federation/example.mdx b/docs/enterprise/externalsecrets/federation/example.mdx index 699e021..438292f 100644 --- a/docs/enterprise/externalsecrets/federation/example.mdx +++ b/docs/enterprise/externalsecrets/federation/example.mdx @@ -51,7 +51,7 @@ This example demonstrates a common use case for ESI Federation: a central cluste This CR registers `client-cluster-alpha` with the Federation Server. ```yaml # Filename: kf-client-cluster-alpha.yaml on cluster-main - apiVersion: federation.external-secrets.io/v1alpha1 + apiVersion: identity.federation.external-secrets.io/v1alpha1 kind: KubernetesFederation metadata: name: client-cluster-alpha diff --git a/docs/enterprise/externalsecrets/federation/server-setup.mdx b/docs/enterprise/externalsecrets/federation/server-setup.mdx index 64da303..fcc3c09 100644 --- a/docs/enterprise/externalsecrets/federation/server-setup.mdx +++ b/docs/enterprise/externalsecrets/federation/server-setup.mdx @@ -15,18 +15,32 @@ Setting up an External Secrets Ultimate Edition instance as a Federation Serve The federation feature introduces two key Custom Resource Definitions that are typically applied on the **Federation Server** cluster. -### 1. `KubernetesFederation` +## 1. Identity -* **API Group**: `federation.external-secrets.io/v1alpha1` +The Identity resource defines how client clusters authenticate to the Federation Server. Each federation relationship specifies the authentication mechanism and trust parameters used when validating incoming requests. + +Currently, there are two supported identity types: + +* `KubernetesFederation` +* `SpiffeFederation` + +Both CRDs belong to the same API Group, but they differ in how trust is established — the first uses a Kubernetes API endpoint (JWKS-based), while the second uses a SPIFFE Trust Domain. + +#### 1.1. `KubernetesFederation` + +* **API Group**: `identity.federation.external-secrets.io/v1alpha1` * **Kind**: `KubernetesFederation` * **Scope**: Cluster * **Purpose**: Defines a named federation relationship with a client Kubernetes cluster. It essentially registers a client cluster with the Federation Server, enabling the server to validate tokens issued by that client cluster. * **Spec Fields**: * `url` (string, **required**): The Kubernetes API Server URL of the client cluster (e.g., `https://kubeapi.client-cluster.example.com`). This URL is used by the Federation Server to construct the JWKS (JSON Web Key Set) URI for the client cluster, allowing it to fetch the public keys needed to validate Service Account (SA) tokens issued by that client cluster. +The Federation Server uses the client cluster’s API Server URL to derive its JWKS (JSON Web Key Set) endpoint. The JWKS keys are then used to validate the digital signatures of incoming Kubernetes SA tokens. + + **Example `KubernetesFederation` CR:** ```yaml -apiVersion: federation.external-secrets.io/v1alpha1 +apiVersion: identity.federation.external-secrets.io/v1alpha1 kind: KubernetesFederation metadata: name: my-client-cluster # A descriptive name for the client cluster @@ -34,6 +48,29 @@ spec: url: https://api.my-client-cluster.example.com ``` +#### 1.2. `SpiffeFederation` + +* **API Group**: `identity.federation.external-secrets.io/v1alpha1` +* **Kind**: `SpiffeFederation` +* **Scope**: Cluster +* **Purpose**: Defines a named federation relationship with a SPIFFE-enabled environment, allowing the Federation Server to trust and validate SPIFFE identities (spiffe://...) issued by that external trust domain. +* **Spec Fields**: + * `trustDomain` (string, **required**): The SPIFFE Trust Domain (e.g. `spiffe://client.example.com`). Used to locate the bundle endpoint and validate SVIDs issued by that domain. + +Unlike `KubernetesFederation`, which relies on the Kubernetes API’s JWKS endpoint, `SpiffeFederation` establishes trust based on a SPIFFE Trust Domain and its associated bundle endpoint. +This allows the Federation Server to verify SVIDs (SPIFFE Verifiable Identity Documents) presented by workloads in the federated domain. + + +**Example `SpiffeFederation` CR:** +```yaml +apiVersion: identity.federation.external-secrets.io/v1alpha1 +kind: KubernetesFederation +metadata: + name: my-client-cluster # A descriptive name for the client cluster +spec: + trustDomain: spiffe://client.example.com +``` + ### 2. `Authorization` * **API Group**: `federation.external-secrets.io/v1alpha1` diff --git a/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx b/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx index e561b0a..945f5c7 100644 --- a/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx +++ b/docs/enterprise/externalsecrets/tutorials/dynamic-credentials.mdx @@ -67,7 +67,7 @@ Apply this manifest to your ESE Federation Server cluster. Create an `Authorization` CR on the ESE Federation Server to allow the Service Account of your application Pod to use the `vault-app-creds-generator`. ```yaml -apiVersion: federation.external-secrets.io/v1alpha1 +apiVersion: identity.federation.external-secrets.io/v1alpha1 kind: KubernetesFederation metadata: name: my-app-cluster