[RFC-0010] Introduce feature gate for enabling object-level workload identity

Signed-off-by: Matheus Pimenta <[email protected]>

Author: matheuscscp

apis/meta/conditions.go

@@ -152,6 +152,10 @@ const (
 	// InvalidCELExpressionReason represents the fact that a CEL expression
 	// in the configuration is invalid.
 	InvalidCELExpressionReason string = "InvalidCELExpression"
+
+	// FeatureGateDisabledReason represents the fact that a feature is trying to
+	// be used, but the feature gate for that feature is disabled.
+	FeatureGateDisabledReason string = "FeatureGateDisabled"
 )
 
 // ObjectWithConditions describes a Kubernetes resource object with status conditions.

auth/feature_gate.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2025 The Flux authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package auth
+
+import (
+	"fmt"
+	"os"
+)
+
+// FeatureGateObjectLevelWorkloadIdentity is a feature gate that enables the use of
+// object-level workload identity for authentication.
+const FeatureGateObjectLevelWorkloadIdentity = "ObjectLevelWorkloadIdentity"
+
+// ErrObjectLevelWorkloadIdentityNotEnabled is returned when object-level
+// workload identity is attempted but not enabled.
+var ErrObjectLevelWorkloadIdentityNotEnabled = fmt.Errorf(
+	"%s feature gate is not enabled", FeatureGateObjectLevelWorkloadIdentity)
+
+// SetFeatureGates sets the default values for the feature gates.
+func SetFeatureGates(features map[string]bool) {
+	// opt-in from Flux v2.6.
+	features[FeatureGateObjectLevelWorkloadIdentity] = false
+}
+
+// EnvVarEnableObjectLevelWorkloadIdentity is the environment variable that
+// enables the use of object-level workload identity for authentication.
+const EnvVarEnableObjectLevelWorkloadIdentity = "ENABLE_OBJECT_LEVEL_WORKLOAD_IDENTITY"
+
+// EnableObjectLevelWorkloadIdentity enables the use of object-level workload
+// identity for authentication.
+func EnableObjectLevelWorkloadIdentity() {
+	os.Setenv(EnvVarEnableObjectLevelWorkloadIdentity, "true")
+}
+
+// IsObjectLevelWorkloadIdentityEnabled returns true if the object-level
+// workload identity feature gate is enabled.
+func IsObjectLevelWorkloadIdentityEnabled() bool {
+	return os.Getenv(EnvVarEnableObjectLevelWorkloadIdentity) == "true"
+}

auth/get_token.go

@@ -48,6 +48,11 @@ func GetToken(ctx context.Context, provider Provider, opts ...Option) (Token, er
 	var providerIdentity string
 	var serviceAccountP *corev1.ServiceAccount
 	if o.ServiceAccount != nil {
+		// Check the feature gate for object-level workload identity.
+		if !IsObjectLevelWorkloadIdentityEnabled() {
+			return nil, ErrObjectLevelWorkloadIdentityNotEnabled
+		}
+
 		// Get service account and prepare a function to create a token for it.
 		var serviceAccount corev1.ServiceAccount
 		if err := o.Client.Get(ctx, *o.ServiceAccount, &serviceAccount); err != nil {

auth/get_token_test.go

@@ -211,11 +211,12 @@ func TestGetToken(t *testing.T) {
 	}
 
 	for _, tt := range []struct {
-		name          string
-		provider      *mockProvider
-		opts          []auth.Option
-		expectedToken auth.Token
-		expectedErr   string
+		name               string
+		provider           *mockProvider
+		opts               []auth.Option
+		disableObjectLevel bool
+		expectedToken      auth.Token
+		expectedErr        string
 	}{
 		{
 			name: "controller access token",
@@ -376,12 +377,25 @@ func TestGetToken(t *testing.T) {
 			},
 			expectedErr: "failed to parse artifact repository 'some-registry.io/some/artifact': mock error",
 		},
+		{
+			name:     "disable object level workload identity",
+			provider: &mockProvider{},
+			opts: []auth.Option{
+				auth.WithServiceAccount(saRef, kubeClient),
+			},
+			disableObjectLevel: true,
+			expectedErr:        "ObjectLevelWorkloadIdentity feature gate is not enabled",
+		},
 	} {
 		t.Run(tt.name, func(t *testing.T) {
 			g := NewWithT(t)
 
 			tt.provider.t = t
 
+			if !tt.disableObjectLevel {
+				t.Setenv(auth.EnvVarEnableObjectLevelWorkloadIdentity, "true")
+			}
+
 			token, err := auth.GetToken(ctx, tt.provider, tt.opts...)
 
 			if tt.expectedErr != "" {

oci/tests/integration/testapp/main.go

@@ -67,6 +67,7 @@ var (
 func main() {
 	flag.Parse()
 	if *wiSAName != "" && *wiSANamespace != "" {
+		auth.EnableObjectLevelWorkloadIdentity()
 		conf, err := rest.InClusterConfig()
 		if err != nil {
 			panic(err)