[RFC-0014] Introduce SPIFFE Broker API

AGENTS.md

@@ -135,7 +135,6 @@ Bump `fluxcd/pkg/*` modules as a set — version skew breaks `go.sum`. Run `make
 - `make verify` is the CI gate — a dirty diff means you forgot to run codegen or tidy.
 - The `replace` directives in `go.mod` (semver and go-digest) exist for correctness. Leave them alone.
 - `Storage` serializes writes per object via `fluxcd/pkg/lockedfile` and expects `--storage-path` to be a real local directory. Never write artifacts outside `Storage.BasePath` — the file server exposes that path verbatim at `--storage-addr`.
-- Workload Identity is feature-gated by `auth.FeatureGateObjectLevelWorkloadIdentity` (from `fluxcd/pkg/auth`). Token caching is opt-in via `--token-cache-max-size`.
 - `CacheSecretsAndConfigMaps` (in `internal/features`) is off by default; `Secret`/`ConfigMap` lookups bypass the cache and hit the API server directly. Mind that before adding new secret reads to a hot path.
 - The controller watches a label-selected subset of its CRs — see `Cache.ByObject` in `mustSetupManager`. Adding a new kind requires updating both `main.go` and the scheme.
 - `pkg/azure`, `pkg/gcp`, `pkg/minio` are importable by external consumers. Treat their exported surface as semi-public API.

docs/README.md

@@ -36,6 +36,8 @@
 | `--storage-adv-addr`                  | string        | The advertised address of the static file server.                                                                                                                                        |
 | `--storage-path`                      | string        | The local storage path.                                                                                                                                                                  |
 | `--token-cache-max-size`              | int           | The maximum amount of entries in the LRU cache used for tokens. (default 100, enabled)                                                                                                   |
+| `--spiffe-broker-endpoint`            | string        | The gRPC URL of the SPIFFE Broker endpoint.                                                                                                                                              |
+| `--spiffe-broker-id`                  | strings       | SPIFFE ID of the SPIFFE Broker endpoint. Can be repeated.                                                                                                                                |
 | `--token-cache-max-duration`          | duration      | The maximum duration for which a token would be considered unexpired. This is capped at 1h. (default 1h)                                                                                 |
 | `--watch-all-namespaces`              | boolean       | Watch for custom resources in all namespaces, if set to false it will only watch the runtime namespace. (default true)                                                                   |
 | `--watch-label-selector`              | string        | Watch for resources with matching labels e.g. 'sharding.fluxcd.io/key=shard1'.                                                                                                           |
@@ -71,10 +73,24 @@ understands it as the trust domain of the controller's own X509-SVID.
 
 Invalid values cause source-controller to fail at startup.
 
+### SPIFFE Broker API
+
+When `--spiffe-broker-endpoint` and at least one `--spiffe-broker-id` are set,
+source-controller acquires an X.509-SVID from the SPIFFE Workload API and uses it to
+authenticate to the SPIFFE Broker API. The `SPIFFE_ENDPOINT_SOCKET` environment
+variable must point to the Workload API socket.
+
+The Broker is used to acquire JWT-SVIDs for object-level workload identity when
+a ServiceAccount sets `credential.auth.fluxcd.io/provider` to `spiffe`. The
+Broker endpoint is a TCP gRPC target, e.g.
+`dns:///spire-server.spire.svc.cluster.local:8443`.
+
+Each `--spiffe-broker-id` value is interpreted like the SPIFFE IDs used by the
+mTLS flags. Invalid values cause source-controller to fail at startup.
+
 ### Feature Gates
 
 | Name                          | Default Value | Description                                                                                                                                                                                                               |
 |-------------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `CacheSecretsAndConfigMaps`   | `false`       | Configures the caching of Secrets and ConfigMaps by the controller-runtime client. When enabled, it will cache both object types, resulting in increased memory usage and cluster-wide RBAC permissions (list and watch). |
-| `ObjectLevelWorkloadIdentity` | `false`       | Enables the use of object-level workload identity for the controller.                                                                                                                                                     |
 | `OptimizedGitClones`          | `true`        | Optimises Git resource usage by only cloning repositories when the HEAD commit changed since last reconciliation.                                                                                                         |

docs/spec/v1/buckets.md

@@ -295,10 +295,6 @@ spec:
 
 ##### AWS Object-Level Workload Identity example
 
-**Note:** To use Object-Level Workload Identity (`.spec.serviceAccountName` with 
-cloud providers), the controller feature gate `ObjectLevelWorkloadIdentity` must 
-be enabled.
-
 ```yaml
 ---
 apiVersion: source.toolkit.fluxcd.io/v1
@@ -573,10 +569,6 @@ spec:
 
 ##### Azure Object-Level Workload Identity example
 
-**Note:** To use Object-Level Workload Identity (`.spec.serviceAccountName` with 
-cloud providers), the controller feature gate `ObjectLevelWorkloadIdentity` must 
-be enabled.
-
 ```yaml
 ---
 apiVersion: source.toolkit.fluxcd.io/v1
@@ -676,10 +668,6 @@ spec:
 
 ##### GCP Object-Level Workload Identity example
 
-**Note:** To use Object-Level Workload Identity (`.spec.serviceAccountName` with 
-cloud providers), the controller feature gate `ObjectLevelWorkloadIdentity` must 
-be enabled.
-
 ```yaml
 ---
 apiVersion: source.toolkit.fluxcd.io/v1
@@ -1000,9 +988,12 @@ the `.spec.provider` field:
 - When `.spec.provider` is set to `generic`, the controller will fetch the image
   pull secrets attached to the Service Account and use them for authentication.
 - When `.spec.provider` is set to `aws`, `azure`, or `gcp`, the Service Account
-  will be used for Workload Identity authentication. In this case, the controller
-  feature gate `ObjectLevelWorkloadIdentity` must be enabled, otherwise the
-  controller will error out.
+  will be used for Workload Identity authentication.
+
+For a complete guide to the ServiceAccount annotations used for object-level
+workload identity, including the `spiffe` credential provider, see the
+[ServiceAccount annotations](/flux/integrations/serviceaccount-annotations)
+docs.
 
 **Note:** that for a publicly accessible object storage, you don't need to
 provide a `secretRef` nor `serviceAccountName`.

docs/spec/v1/gitrepositories.md

@@ -465,11 +465,14 @@ in the same namespace as GitRepository with purpose depending on the value of
 the `.spec.provider` field:
 
 - When `.spec.provider` is set to `azure`, the Service Account
-  will be used for Workload Identity authentication. In this case, the controller
-  feature gate `ObjectLevelWorkloadIdentity` must be enabled, otherwise the
-  controller will error out. For Azure DevOps specific setup, see the
+  will be used for Workload Identity authentication. For Azure DevOps specific setup, see the
   [Azure DevOps integration guide](https://fluxcd.io/flux/integrations/azure/#for-azure-devops).
 
+For a complete guide to the ServiceAccount annotations used for object-level
+workload identity, including the `spiffe` credential provider, see the
+[ServiceAccount annotations](/flux/integrations/serviceaccount-annotations)
+docs.
+
 **Note:** that for a publicly accessible git repository, you don't need to
 provide a `secretRef` nor `serviceAccountName`.
 

docs/spec/v1/ocirepositories.md

@@ -281,9 +281,12 @@ the `.spec.provider` field:
   use the Service Account token for object-level workload identity when the
   Service Account opts in with the credential annotations described below.
 - When `.spec.provider` is set to `aws`, `azure`, or `gcp`, the Service Account
-  will be used for Workload Identity authentication. In this case, the controller
-  feature gate `ObjectLevelWorkloadIdentity` must be enabled, otherwise the
-  controller will error out.
+  will be used for Workload Identity authentication.
+
+For a complete guide to the ServiceAccount annotations used for object-level
+workload identity, including the `spiffe` credential provider, see the
+[ServiceAccount annotations](/flux/integrations/serviceaccount-annotations)
+docs.
 
 **Note:** that for a publicly accessible image repository, you don't need to
 provide a `secretRef` nor `serviceAccountName`.
@@ -314,13 +317,6 @@ and continues to use its `imagePullSecrets`, or anonymous access if it has none.
 Setting only one of the two required annotations is a configuration error. The
 credential annotations cannot be combined with `imagePullSecrets`.
 
-Object-level workload identity for the `generic` provider requires the
-`ObjectLevelWorkloadIdentity` feature gate to be enabled:
-
-```bash
---feature-gates=ObjectLevelWorkloadIdentity=true
-```
-
 Example:
 
 ```yaml

go.mod

@@ -23,21 +23,21 @@ require (
 	github.com/docker/go-units v0.5.0
 	github.com/elazarl/goproxy v1.8.4
 	github.com/fluxcd/cli-utils v1.4.0
-	github.com/fluxcd/pkg/apis/crypto v0.4.1-0.20261022125904-05e84321fa52
+	github.com/fluxcd/pkg/apis/crypto v0.5.0
 	github.com/fluxcd/pkg/apis/event v0.32.0
-	github.com/fluxcd/pkg/apis/meta v1.36.1-0.20261022125904-05e84321fa52
-	github.com/fluxcd/pkg/artifact v0.25.1-0.20261022125904-05e84321fa52
-	github.com/fluxcd/pkg/auth v0.63.1-0.20261022125904-05e84321fa52
-	github.com/fluxcd/pkg/cache v0.17.1-0.20261022125904-05e84321fa52
+	github.com/fluxcd/pkg/apis/meta v1.37.0
+	github.com/fluxcd/pkg/artifact v0.26.0
+	github.com/fluxcd/pkg/auth v0.65.0
+	github.com/fluxcd/pkg/cache v0.18.0
 	github.com/fluxcd/pkg/git v0.55.0
 	github.com/fluxcd/pkg/gittestserver v0.32.0
 	github.com/fluxcd/pkg/helmtestserver v0.44.0
 	github.com/fluxcd/pkg/http/transport v0.9.0
 	github.com/fluxcd/pkg/masktoken v0.10.0
 	github.com/fluxcd/pkg/oci v0.72.0
-	github.com/fluxcd/pkg/runtime v0.120.1-0.20261022125904-05e84321fa52
+	github.com/fluxcd/pkg/runtime v0.121.0
 	github.com/fluxcd/pkg/sourceignore v0.21.0
-	github.com/fluxcd/pkg/spiffe v0.0.0-20261022125904-05e84321fa52
+	github.com/fluxcd/pkg/spiffe v0.1.0
 	github.com/fluxcd/pkg/ssh v0.28.0
 	github.com/fluxcd/pkg/tar v1.3.0
 	github.com/fluxcd/pkg/testserver v0.15.0
@@ -224,6 +224,7 @@ require (
 	github.com/go-openapi/validate v0.26.1 // indirect
 	github.com/go-piv/piv-go/v2 v2.6.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/gobuffalo/flect v1.0.3 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/gofrs/flock v0.13.0 // indirect
 	github.com/gofrs/uuid v4.4.0+incompatible // indirect

go.sum

@@ -350,18 +350,18 @@ github.com/fluxcd/gitkit v0.6.0 h1:iNg5LTx6ePo+Pl0ZwqHTAkhbUHxGVSY3YCxCdw7VIFg=
 github.com/fluxcd/gitkit v0.6.0/go.mod h1:svOHuKi0fO9HoawdK4HfHAJJseZDHHjk7I3ihnCIqNo=
 github.com/fluxcd/pkg/apis/acl v0.12.0 h1:UWpZDqKxpKDW38wdXIMHV8Uv3POPu2vUrra0JH1frH0=
 github.com/fluxcd/pkg/apis/acl v0.12.0/go.mod h1:PJrGIu5Bw/6/siO95uhS+pi5oKSU+gVJqHqsPHb8Kok=
-github.com/fluxcd/pkg/apis/crypto v0.4.1-0.20261022125904-05e84321fa52 h1:YkDjmLFe0+RhzlFTwHgoO6xLpPYuhoiqQlMo+Qj2tW0=
-github.com/fluxcd/pkg/apis/crypto v0.4.1-0.20261022125904-05e84321fa52/go.mod h1:bEwkDgBjLXMVJ2BwmVbbj32PkirmNSicabgl2Jvw7Dk=
+github.com/fluxcd/pkg/apis/crypto v0.5.0 h1:buy9YCvrD8IpKqOVCSV9k2wlF2iVPaETLOZBqsbyfVs=
+github.com/fluxcd/pkg/apis/crypto v0.5.0/go.mod h1:bEwkDgBjLXMVJ2BwmVbbj32PkirmNSicabgl2Jvw7Dk=
 github.com/fluxcd/pkg/apis/event v0.32.0 h1:3zyjdUspwQN+EQJPlUXwCvCMbeqtB+azlNmeenAcbuE=
 github.com/fluxcd/pkg/apis/event v0.32.0/go.mod h1:ALma8dTqo+NbI+z4BawSzt0pAPjetCSNNUSSS/9p0VU=
-github.com/fluxcd/pkg/apis/meta v1.36.1-0.20261022125904-05e84321fa52 h1:vKtcpfELWz1l2eOQjWeEbCJZMNH29W4Fwa3EPM37zW0=
-github.com/fluxcd/pkg/apis/meta v1.36.1-0.20261022125904-05e84321fa52/go.mod h1:1MLvK2Xu3UdTKBzg+Q1Oj7H9PHeiKsUB1UW3uwxAwiM=
-github.com/fluxcd/pkg/artifact v0.25.1-0.20261022125904-05e84321fa52 h1:xUbaB4s9PtJ771fZirtqH8GDg3tnZ8qtTYQup322K4k=
-github.com/fluxcd/pkg/artifact v0.25.1-0.20261022125904-05e84321fa52/go.mod h1:9wKz9vfH7zuhteNxQkGw9l7sCN1xW8YZttEWNN8M/L0=
-github.com/fluxcd/pkg/auth v0.63.1-0.20261022125904-05e84321fa52 h1:QoZGEf9JonMNcEAacH8EGtSq55dplp18TTSH//M2r7o=
-github.com/fluxcd/pkg/auth v0.63.1-0.20261022125904-05e84321fa52/go.mod h1:gWbB4MzuHWalVyI0o4lE84aINidor9+S63ithckm+94=
-github.com/fluxcd/pkg/cache v0.17.1-0.20261022125904-05e84321fa52 h1:9ZSGSkmi4OxVCSj9Uzrt6E1Ph0ypPUajsc76pYqUg2s=
-github.com/fluxcd/pkg/cache v0.17.1-0.20261022125904-05e84321fa52/go.mod h1:OW3fncHhPnPZFZav5FdEa//cyMHSndI0JS+IM69LXOU=
+github.com/fluxcd/pkg/apis/meta v1.37.0 h1:gVwadRI8BrRrl4Rw0ZBJ/VSWh7qNpf7ShmTjDhcVf30=
+github.com/fluxcd/pkg/apis/meta v1.37.0/go.mod h1:1MLvK2Xu3UdTKBzg+Q1Oj7H9PHeiKsUB1UW3uwxAwiM=
+github.com/fluxcd/pkg/artifact v0.26.0 h1:gqBI9pFOkCCuwxky3rTkwGGKOGokkSUQ5GuNtUdfiJA=
+github.com/fluxcd/pkg/artifact v0.26.0/go.mod h1:4P7avVbWbMgqZhckfP9y+wLa01l/4kRLXflp6zU6kVc=
+github.com/fluxcd/pkg/auth v0.65.0 h1:AIA+RM4MOyc+iGCMgfuohH1TQsGMBB7Msay7yBLg7IE=
+github.com/fluxcd/pkg/auth v0.65.0/go.mod h1:ozzC9/AiqvfeC8BVyFRsUTQAn34gasyElX4aCBHV83c=
+github.com/fluxcd/pkg/cache v0.18.0 h1:MllbYkQYJ5zJ5nK52mDWpSov4kSXiCsLJoPeV43y6os=
+github.com/fluxcd/pkg/cache v0.18.0/go.mod h1:OW3fncHhPnPZFZav5FdEa//cyMHSndI0JS+IM69LXOU=
 github.com/fluxcd/pkg/git v0.55.0 h1:jMdW0uAYuzcwIL5rJq5pmDd+jSrgOe6eIOZfdrcAvO8=
 github.com/fluxcd/pkg/git v0.55.0/go.mod h1:s9AK9ZEG9CtAgkcX4QhQphLsaDBTje32tT5V3knpj1I=
 github.com/fluxcd/pkg/gittestserver v0.32.0 h1:y1wbnEaOXpEYqAxGMxcsXZTH6W4QjFyTj6m1d1ytjY0=
@@ -376,12 +376,12 @@ github.com/fluxcd/pkg/masktoken v0.10.0 h1:jY9tuBIS1T7z9F8nJc9ozT0QrI391Se9vMu0e
 github.com/fluxcd/pkg/masktoken v0.10.0/go.mod h1:zOCZp3trYmD5/csLOizvIGTi4gn76nnkTFu+vKOJufo=
 github.com/fluxcd/pkg/oci v0.72.0 h1:nUTGHTd/2qq2yT66anHfXiwE19uJl6VL36zm74iFwbU=
 github.com/fluxcd/pkg/oci v0.72.0/go.mod h1:5ngbB6SDvo6daD29HZtBbC6CcnHxuI+5JJR/YqtZhKM=
-github.com/fluxcd/pkg/runtime v0.120.1-0.20261022125904-05e84321fa52 h1:UD7MGD096C02MqQFDujvSGktyuDhYUnvQhjBePw3bLk=
-github.com/fluxcd/pkg/runtime v0.120.1-0.20261022125904-05e84321fa52/go.mod h1:Cw0CQ/tVKS9lgJoyKVouZr1qVnoJcYnSHw3QDzIOOjA=
+github.com/fluxcd/pkg/runtime v0.121.0 h1:xFBJ+8To7YEaenBvFZ843MmKST0fQTaALsA+qH0ZzVE=
+github.com/fluxcd/pkg/runtime v0.121.0/go.mod h1:8JWIvsBXvHzSOYfuiPNDB6cmHTjWF5m2WyCB1Tiy8Ek=
 github.com/fluxcd/pkg/sourceignore v0.21.0 h1:p65j81RzXAeL4KJKgbkFRou+xiA0841CUdAsOCSAb5o=
 github.com/fluxcd/pkg/sourceignore v0.21.0/go.mod h1:N9NFuxbEMm+UPtP9t+Oyx5LEs0uHu7W+WVPmdlIbCeY=
-github.com/fluxcd/pkg/spiffe v0.0.0-20261022125904-05e84321fa52 h1:nl8eRotsfHEZS7m7SwZbZidq8F/MGj3yxyH5Vh6bas4=
-github.com/fluxcd/pkg/spiffe v0.0.0-20261022125904-05e84321fa52/go.mod h1:tZ+T8ljAM9ZE0VriHSWM4vfvhlq5zv5bNcPKqwZK1lk=
+github.com/fluxcd/pkg/spiffe v0.1.0 h1:BpfZHrine91A/tcGjSs6oejT0VyQpDx4nal2KLfE1Fc=
+github.com/fluxcd/pkg/spiffe v0.1.0/go.mod h1:IKBOcFXvk4PwdaE86+d25iB3m+l7iYKUxWl2yVDX/Co=
 github.com/fluxcd/pkg/ssh v0.28.0 h1:DbqDtvJGKzrSfXfB8Hi9T2mbTnNBodijpRZRfxx59wE=
 github.com/fluxcd/pkg/ssh v0.28.0/go.mod h1:FyaNc49GQcFIHdyZzwmG/9UApGaD5nKXT6CtzWAsaE0=
 github.com/fluxcd/pkg/tar v1.3.0 h1:PbL5jNN5q/F6nXA8aCH+msM75BS6lSnPX2RNd48f8ls=
@@ -497,6 +497,8 @@ github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U=
 github.com/go-test/deep v1.1.1/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/gobuffalo/flect v1.0.3 h1:xeWBM2nui+qnVvNM4S3foBhCAL2XgPU+a7FdpelbTq4=
+github.com/gobuffalo/flect v1.0.3/go.mod h1:A5msMlrHtLqh9umBSnvabjsMrCcCpAyzglnDvkbYKHs=
 github.com/gobwas/glob v0.2.3 h1:A4xDbljILXROh+kObIiy5kIaPYD8e96x1tgBhUI5J+Y=
 github.com/gobwas/glob v0.2.3/go.mod h1:d3Ez4x06l9bZtSvzIay5+Yzi0fmZzPgnTbPcKjJAkT8=
 github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=