Skip to content

[RFC-0014] Introduce SPIFFE Broker API #1626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matheuscscp merged 1 commit into from
Oct 22, 2026
Merged

[RFC-0014] Introduce SPIFFE Broker API #1626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
22 changes: 22 additions & 0 deletions .github/workflows/e2e.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,3 +89,25 @@ jobs:
kubectl -n helm-system get helmreleases -oyaml || true
kubectl -n helm-system get all
helm ls -n helm-system --all
kubeconfig-remote:
runs-on: ubuntu-latest
permissions:
contents: read # for reading the repository code.
steps:
- name: Test suite setup
# The custom kind config sets the ServiceAccount issuer URL used by the
# remote cluster's OIDC authenticator.
uses: fluxcd/gha-workflows/.github/actions/setup-kubernetes@948f0babb1fce92d805ea0755a3d7ec1cc4f3176 # v0.16.0
with:
go-version: 1.27.x
kind-config: hack/ci/kubeconfig-primary-kind.yaml
- name: Build container image
run: |
make docker-build IMG=test/helm-controller:latest \
BUILD_PLATFORMS=linux/amd64 \
BUILD_ARGS="--load"
- name: Run remote kubeconfig e2e
# Reuses the "kind" cluster the setup action created and adds a second one.
run: hack/ci/kubeconfig-e2e.sh
env:
IMG: test/helm-controller:latest
18 changes: 17 additions & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@
| `--requeue-dependency` | duration | The interval at which failing dependencies are reevaluated. (default 30s) |
| `--snapshot-digest-algo` | string | The algorithm to use to calculate the digest of Helm release storage snapshots. (default "sha256") |
| `--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-configs-label-selector` | string | Watch for ConfigMaps and Secrets with matching labels (default 'reconcile.fluxcd.io/watch=Enabled'). |
Expand Down Expand Up @@ -72,6 +74,21 @@ understands it as the trust domain of the controller's own X509-SVID.

Invalid values cause helm-controller to fail at startup.

### SPIFFE Broker API

When `--spiffe-broker-endpoint` and at least one `--spiffe-broker-id` are set,
helm-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 helm-controller to fail at startup.

### Feature Gates

| Name | Default Value | Description |
Expand All @@ -86,6 +103,5 @@ Invalid values cause helm-controller to fail at startup.
| `DisableChartDigestTracking` | `false` | Disables the tracking of digest changes for Helm OCI charts. When set to `true`, the controller will not append the OCI digest to the chart version in `Chart.yaml`. |
| `DisableConfigWatchers` | `false` | Disables the watchers for ConfigMaps and Secrets. |
| `ExternalArtifact` | `true` | Enables support for the [ExternalArtifact](https://github.com/fluxcd/source-controller/blob/main/docs/spec/v1/externalartifacts.md) source type. |
| `ObjectLevelWorkloadIdentity` | `false` | Enables the use of object-level workload identity for the controller. |
| `OOMWatch` | `false` | Enables the OOM watcher, which will gracefully shut down the controller when the memory usage exceeds the configured limit. This is disabled by default. |
| `UseHelm3Defaults` | `false` | Restores Helm v3 defaults. When enabled, uses client-side apply for installation, Helm's legacy readiness logic, and the `nohooks` post-render strategy instead of the Helm v4 defaults (server-side apply, kstatus-based health checking, and `combined` post-render strategy). |
5 changes: 5 additions & 0 deletions docs/spec/v2/helmreleases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1290,6 +1290,11 @@ this feature, see the following docs:
- [GKE](/flux/integrations/gcp/#for-google-kubernetes-engine)
- [Generic](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server)

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.

Example for an EKS cluster:

```yaml
Expand Down
15 changes: 8 additions & 7 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,13 @@ require (
github.com/fluxcd/pkg/apis/acl v0.12.0
github.com/fluxcd/pkg/apis/event v0.32.0
github.com/fluxcd/pkg/apis/kustomize v1.23.0
github.com/fluxcd/pkg/apis/meta v1.36.1-0.20261021122630-1ab1573eaf5b
github.com/fluxcd/pkg/auth v0.63.1-0.20261021122630-1ab1573eaf5b
github.com/fluxcd/pkg/cache v0.17.1-0.20261021122630-1ab1573eaf5b
github.com/fluxcd/pkg/apis/meta v1.37.0
github.com/fluxcd/pkg/auth v0.65.0
github.com/fluxcd/pkg/cache v0.18.0
github.com/fluxcd/pkg/chartutil v1.32.0
github.com/fluxcd/pkg/http/fetch v0.28.1-0.20261021122630-1ab1573eaf5b
github.com/fluxcd/pkg/runtime v0.120.1-0.20261021122630-1ab1573eaf5b
github.com/fluxcd/pkg/spiffe v0.0.0-20261021122630-1ab1573eaf5b
github.com/fluxcd/pkg/http/fetch v0.29.0
github.com/fluxcd/pkg/runtime v0.121.0
github.com/fluxcd/pkg/spiffe v0.1.0
github.com/fluxcd/pkg/ssa v0.80.0
github.com/fluxcd/pkg/testserver v0.15.0
github.com/fluxcd/source-controller/api v1.9.6
Expand Down Expand Up @@ -114,7 +114,7 @@ require (
github.com/extism/go-sdk v1.7.1 // indirect
github.com/fatih/color v1.19.0 // indirect
github.com/felixge/httpsnoop v1.1.0 // indirect
github.com/fluxcd/pkg/apis/crypto v0.4.1-0.20261021122630-1ab1573eaf5b // indirect
github.com/fluxcd/pkg/apis/crypto v0.5.0 // indirect
github.com/fluxcd/pkg/tar v1.3.0 // indirect
github.com/fsnotify/fsnotify v1.10.1 // indirect
github.com/fxamacker/cbor/v2 v2.9.3 // indirect
Expand All @@ -137,6 +137,7 @@ require (
github.com/go-openapi/swag/stringutils v0.29.1 // indirect
github.com/go-openapi/swag/typeutils v0.29.1 // indirect
github.com/go-openapi/swag/yamlutils v0.29.1 // 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/golang-jwt/jwt/v5 v5.3.1 // indirect
Expand Down
35 changes: 21 additions & 14 deletions go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,26 +152,26 @@ github.com/fluxcd/cli-utils v1.4.0 h1:zlTiCWcVDQvvwZXILYeu5rpbnGt1sS+w32y3+rkOpi
github.com/fluxcd/cli-utils v1.4.0/go.mod h1:OupUOj2boEKTbiguMbGMz5Z/d59JUcb1c7pPESe8Pjw=
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.20261021122630-1ab1573eaf5b h1:/n7p1+Yyu88dVjg3ezqCM0p96VUwMxtjgSb6cELFiQg=
github.com/fluxcd/pkg/apis/crypto v0.4.1-0.20261021122630-1ab1573eaf5b/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/kustomize v1.23.0 h1:tT/sUURyh6ixQG4+Y/ZoUu+hh5/DQLRraWBgy42ubqQ=
github.com/fluxcd/pkg/apis/kustomize v1.23.0/go.mod h1:Jm/LmEsqJIldhhTmhkORAq8JKVZK3ZV2Q88rntjGxEI=
github.com/fluxcd/pkg/apis/meta v1.36.1-0.20261021122630-1ab1573eaf5b h1:g/s+m/jU7cPJ+8IIIXbDD19G7TQAKbiUvqTt5GuywlM=
github.com/fluxcd/pkg/apis/meta v1.36.1-0.20261021122630-1ab1573eaf5b/go.mod h1:1MLvK2Xu3UdTKBzg+Q1Oj7H9PHeiKsUB1UW3uwxAwiM=
github.com/fluxcd/pkg/auth v0.63.1-0.20261021122630-1ab1573eaf5b h1:uqRL6xKRFwUi7AXrPj7BSRAqQYz7rxNMNjSK2W6YqB0=
github.com/fluxcd/pkg/auth v0.63.1-0.20261021122630-1ab1573eaf5b/go.mod h1:gWbB4MzuHWalVyI0o4lE84aINidor9+S63ithckm+94=
github.com/fluxcd/pkg/cache v0.17.1-0.20261021122630-1ab1573eaf5b h1:wi9U1NDlqYmbVUMntuKU71vOqnSFSslDEMbbnBnzJDs=
github.com/fluxcd/pkg/cache v0.17.1-0.20261021122630-1ab1573eaf5b/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/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/chartutil v1.32.0 h1:rqBhgiGsrS4am/jsCfKYlQvPQ+jATug10BtO95UHdq0=
github.com/fluxcd/pkg/chartutil v1.32.0/go.mod h1:pBqCvJVDLpKKnU+k9A+TnceZn+DnnivfVGhzNzHJXZU=
github.com/fluxcd/pkg/http/fetch v0.28.1-0.20261021122630-1ab1573eaf5b h1:q+StvNk04P/dx7IMhw4oKmcfU870OpTIkaZMxgcn5u8=
github.com/fluxcd/pkg/http/fetch v0.28.1-0.20261021122630-1ab1573eaf5b/go.mod h1:SOq8vrzru2zipskTEguXzKHabn2ASyXESQ/DY93FafY=
github.com/fluxcd/pkg/runtime v0.120.1-0.20261021122630-1ab1573eaf5b h1:/S4RzBts7XoNrxXM0hUjmVzZ+fxrXcZ6VyHJfaiWIII=
github.com/fluxcd/pkg/runtime v0.120.1-0.20261021122630-1ab1573eaf5b/go.mod h1:Cw0CQ/tVKS9lgJoyKVouZr1qVnoJcYnSHw3QDzIOOjA=
github.com/fluxcd/pkg/spiffe v0.0.0-20261021122630-1ab1573eaf5b h1:I7Z3cEgoM+EqYpLkr0xI3a1z+Qh1WbZKDCOd8EeGYJg=
github.com/fluxcd/pkg/spiffe v0.0.0-20261021122630-1ab1573eaf5b/go.mod h1:tZ+T8ljAM9ZE0VriHSWM4vfvhlq5zv5bNcPKqwZK1lk=
github.com/fluxcd/pkg/http/fetch v0.29.0 h1:qg9TI6ZaRrJTKqewTjLlcquGQ8H6hFAcMcshnMUQbWw=
github.com/fluxcd/pkg/http/fetch v0.29.0/go.mod h1:SOq8vrzru2zipskTEguXzKHabn2ASyXESQ/DY93FafY=
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/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/ssa v0.80.0 h1:GgakpCFz4pY+unpOscPYlc5eVLUsB7hw9TmWSNr3yp8=
github.com/fluxcd/pkg/ssa v0.80.0/go.mod h1:mUwKP2+KZXm1mal1gSs9SjgcexyqzXbPfHKxdFv5ntM=
github.com/fluxcd/pkg/tar v1.3.0 h1:PbL5jNN5q/F6nXA8aCH+msM75BS6lSnPX2RNd48f8ls=
Expand Down Expand Up @@ -239,6 +239,8 @@ github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpv
github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
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/gofrs/flock v0.13.0 h1:95JolYOvGMqeH31+FC7D2+uULf6mG61mEZ/A8dRYMzw=
Expand Down Expand Up @@ -408,12 +410,17 @@ github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3A
github.com/spiffe/go-spiffe/v2 v2.9.0 h1:g5qTg3qIP1HXV+GzuyEfSJFVxUCpEP5Ui1OINVJHPB4=
github.com/spiffe/go-spiffe/v2 v2.9.0/go.mod h1:w2CLWKLMTX/PPYUEUPv3ltH0RXsw5S8suwNF46w9/Aw=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
github.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 h1:ZF+QBjOI+tILZjBaFj3HgFonKXUcwgJ4djLb6i42S3Q=
Expand Down
Loading
Loading