Skip to content

Commit 039cd81

Browse files
cappyzawacappyzawa
committed
docs: enhance workload identity documentation for providers
Add comprehensive workload identity documentation for both Google Pub/Sub and Azure DevOps providers. Include controller-level and object-level authentication patterns with feature gate requirements and setup instructions for multi-tenant environments. Signed-off-by: cappyzawa <[email protected]>
1 parent 43b3104 commit 039cd81

File tree

2 files changed

+150
-7
lines changed

2 files changed

+150
-7
lines changed

‎api/v1beta3/provider_types.go‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -116,10 +116,22 @@ type ProviderSpec struct {
116116
// +optional
117117
SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`
118118

119-
// ServiceAccountName is the name of the service account used to
120-
// authenticate with services from cloud providers. An error is thrown if a
121-
// static credential is also defined inside the Secret referenced by the
122-
// SecretRef.
119+
// ServiceAccountName is the name of the Kubernetes ServiceAccount used to
120+
// authenticate with cloud provider services through workload identity.
121+
// This enables multi-tenant authentication without storing static credentials.
122+
//
123+
// Supported provider types: azureeventhub, azuredevops, googlepubsub
124+
//
125+
// When specified, the controller will:
126+
// 1. Create an OIDC token for the specified ServiceAccount
127+
// 2. Exchange it for cloud provider credentials via STS
128+
// 3. Use the obtained credentials for API authentication
129+
//
130+
// When unspecified, controller-level authentication is used (single-tenant).
131+
//
132+
// An error is thrown if static credentials are also defined in SecretRef.
133+
// This field requires the ObjectLevelWorkloadIdentity feature gate to be enabled.
134+
//
123135
// +optional
124136
ServiceAccountName string `json:"serviceAccountName,omitempty"`
125137

‎docs/spec/v1beta3/providers.md‎

Lines changed: 134 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -778,6 +778,75 @@ stringData:
778778
attr2-name: attr2-value
779779
```
780780

781+
###### Google Pub/Sub with Workload Identity Example
782+
783+
To configure a Provider for Google Pub/Sub authenticating with Workload Identity,
784+
create a Kubernetes ServiceAccount with the appropriate annotations, and a
785+
`googlepubsub` Provider with the ServiceAccount reference. This method eliminates
786+
the need for JSON credentials and enables multi-tenant authentication.
787+
788+
**Single tenant approach**
789+
790+
This approach uses the notification-controller service account for setting up
791+
authentication.
792+
793+
- In the default installation, the notification-controller service account is
794+
located in the `flux-system` namespace with name `notification-controller`.
795+
796+
- Configure workload identity with notification-controller as described in the
797+
docs [here](/flux/integrations/gcp/#for-google-cloud-pubsub).
798+
799+
```yaml
800+
---
801+
apiVersion: notification.toolkit.fluxcd.io/v1beta3
802+
kind: Provider
803+
metadata:
804+
name: googlepubsub-controller-level
805+
namespace: flux-system
806+
spec:
807+
type: googlepubsub
808+
address: <GCP Project ID>
809+
channel: <Pub/Sub Topic ID>
810+
# No serviceAccountName specified - uses controller's identity
811+
```
812+
813+
**Multi-tenant approach**
814+
815+
For multi-tenant clusters, set `.spec.serviceAccountName` of the provider to
816+
the service account to be used for authentication. Ensure that the service
817+
account has the appropriate annotations for GCP workload identity.
818+
819+
```yaml
820+
---
821+
apiVersion: notification.toolkit.fluxcd.io/v1beta3
822+
kind: Provider
823+
metadata:
824+
name: googlepubsub-tenant-a
825+
namespace: tenant-a
826+
spec:
827+
type: googlepubsub
828+
address: <GCP Project ID>
829+
channel: <Pub/Sub Topic ID>
830+
serviceAccountName: tenant-a-pubsub-sa
831+
---
832+
apiVersion: v1
833+
kind: ServiceAccount
834+
metadata:
835+
name: tenant-a-pubsub-sa
836+
namespace: tenant-a
837+
annotations:
838+
# For GKE Workload Identity
839+
iam.gke.io/gcp-service-account: tenant-a-pubsub@<GCP_PROJECT_ID>.iam.gserviceaccount.com
840+
# For Workload Identity Federation (non-GKE)
841+
gcp.auth.fluxcd.io/workload-identity-provider: projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>
842+
```
843+
844+
**Note:** Object-level authentication requires the `ObjectLevelWorkloadIdentity` feature gate to be enabled:
845+
846+
```bash
847+
--feature-gates=ObjectLevelWorkloadIdentity=true
848+
```
849+
781850
##### Opsgenie
782851

783852
When `.spec.type` is set to `opsgenie`, the controller will send a payload for
@@ -1837,9 +1906,71 @@ Managed Identity authentication can be setup using Azure Workload identity.
18371906
uses the correct namespace and name of the service account. For more details,
18381907
please refer to this
18391908
[guide](https://azure.github.io/azure-workload-identity/docs/quick-start.html#6-establish-federated-identity-credential-between-the-identity-and-the-service-account-issuer--subject).
1840-
The service account used for authentication can be single-tenant
1841-
(controller-level) or multi-tenant(object-level). For a complete guide on how to
1842-
set up authentication, see the integration [docs](/flux/integrations/azure/).
1909+
The service account used for authentication can be single-tenant or
1910+
multi-tenant. For a complete guide on how to set up authentication, see the
1911+
integration [docs](/flux/integrations/azure/).
1912+
1913+
##### Azure DevOps with Workload Identity Example
1914+
1915+
**Single tenant approach**
1916+
1917+
This approach uses the notification-controller service account for setting up
1918+
authentication.
1919+
1920+
- In the default installation, the notification-controller service account is
1921+
located in the `flux-system` namespace with name `notification-controller`.
1922+
1923+
- Configure workload identity with notification-controller as described in the
1924+
docs [here](/flux/installation/configuration/workload-identity/).
1925+
1926+
```yaml
1927+
---
1928+
apiVersion: notification.toolkit.fluxcd.io/v1beta3
1929+
kind: Provider
1930+
metadata:
1931+
name: azuredevops-controller-level
1932+
namespace: flux-system
1933+
spec:
1934+
type: azuredevops
1935+
address: https://dev.azure.com/<organization>/<project>/_git/<repository>
1936+
# No serviceAccountName specified - uses controller's identity
1937+
```
1938+
1939+
**Multi-tenant approach**
1940+
1941+
For multi-tenant clusters, set `.spec.serviceAccountName` of the provider to
1942+
the service account to be used for authentication. Ensure that the service
1943+
account has the
1944+
[annotations](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview?tabs=dotnet#service-account-annotations)
1945+
for the client-id and tenant-id of the managed identity.
1946+
1947+
```yaml
1948+
---
1949+
apiVersion: notification.toolkit.fluxcd.io/v1beta3
1950+
kind: Provider
1951+
metadata:
1952+
name: azuredevops-tenant-a
1953+
namespace: tenant-a
1954+
spec:
1955+
type: azuredevops
1956+
address: https://dev.azure.com/<organization>/<project>/_git/<repository>
1957+
serviceAccountName: tenant-a-devops-sa
1958+
---
1959+
apiVersion: v1
1960+
kind: ServiceAccount
1961+
metadata:
1962+
name: tenant-a-devops-sa
1963+
namespace: tenant-a
1964+
annotations:
1965+
azure.workload.identity/client-id: <client-id-of-managed-identity>
1966+
azure.workload.identity/tenant-id: <tenant-id>
1967+
```
1968+
1969+
**Note:** Object-level authentication requires the `ObjectLevelWorkloadIdentity` feature gate to be enabled:
1970+
1971+
```bash
1972+
--feature-gates=ObjectLevelWorkloadIdentity=true
1973+
```
18431974

18441975
#### PAT
18451976

0 commit comments

Comments
 (0)