xds: implement cluster metadata parsing for GCP Authentication filter (gRFC A83) (#9044)

This PR implements the xDS Cluster Metadata parsing logic as specified
in [gRFC
A83](https://github.com/grpc/proposal/blob/master/A83-xds-gcp-authn-filter.md#xds-cluster-metadata).
This allows the xDS client to extract and validate cluster metadata to
configure the audience used by GCP Authentication filter.
  
### Changes
- **GCP Authn Support**: Added `audienceConverter` to parse
`envoy.extensions.filters.http.gcp_authn.v3.Audience` protos.
- **CDS Integration**: Updated
`validateClusterAndConstructClusterUpdate` to invoke metadata
validation.
- **Validation**: Added strict validation for the `url` field; an empty
URL in the audience metadata will now result in a NACK of the Cluster
resource.
- **Environment Variable**: Metadata parsing for GCP Authn is guarded by
the `GCPAuthenticationFilterEnabled` environment variable.
  
RELEASE NOTES: N/A

Author: Pranjali-2501

internal/envconfig/xds.go

@@ -89,4 +89,9 @@ var (
 	// filtered and prefix-propagated to the LRS server. For more details, see:
 	// https://github.com/grpc/proposal/blob/master/A85-lrs-custom-metrics-changes.md
 	XDSORCAToLRSPropEnabled = boolFromEnv("GRPC_EXPERIMENTAL_XDS_ORCA_LRS_PROPAGATION", false)
+
+	// GCPAuthenticationFilterEnabled enables the xDS GCP Authentication
+	// filter. For more details, see:
+	// https://github.com/grpc/proposal/blob/master/A83-xds-gcp-authn-filter.md
+	GCPAuthenticationFilterEnabled = boolFromEnv("GRPC_EXPERIMENTAL_XDS_GCP_AUTHENTICATION_FILTER", false)
 )

internal/xds/xdsclient/xdsresource/metadata.go

@@ -21,15 +21,20 @@ import (
 	"fmt"
 	"net/netip"
 
-	v3corepb "github.com/envoyproxy/go-control-plane/envoy/config/core/v3"
 	"google.golang.org/grpc/internal/envconfig"
 	"google.golang.org/protobuf/types/known/anypb"
+
+	v3corepb "github.com/envoyproxy/go-control-plane/envoy/config/core/v3"
+	v3gcpauthnpb "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/gcp_authn/v3"
 )
 
 func init() {
 	if envconfig.XDSHTTPConnectEnabled {
 		registerMetadataConverter("type.googleapis.com/envoy.config.core.v3.Address", proxyAddressConvertor{})
 	}
+	if envconfig.GCPAuthenticationFilterEnabled {
+		registerMetadataConverter("type.googleapis.com/envoy.extensions.filters.http.gcp_authn.v3.Audience", audienceConverter{})
+	}
 }
 
 var (
@@ -100,3 +105,28 @@ func (proxyAddressConvertor) convert(anyProto *anypb.Any) (any, error) {
 	}
 	return ProxyAddressMetadataValue{Address: parseAddress(socketaddress)}, nil
 }
+
+// AudienceMetadataValue holds the audience parsed from the
+// envoy.extensions.filters.http.gcp_authn.v3.Audience proto message, as
+// specified in gRFC A83.
+type AudienceMetadataValue struct {
+	// Audience is the URL of the receiving service that performs token
+	// authentication.
+	Audience string
+}
+
+// audienceConverter implements the metadataConverter interface to
+// handle the conversion of envoy.extensions.filters.http.gcp_authn.v3.Audience
+// protobuf messages into an internal representation.
+type audienceConverter struct{}
+
+func (audienceConverter) convert(anyProto *anypb.Any) (any, error) {
+	audienceProto := &v3gcpauthnpb.Audience{}
+	if err := anyProto.UnmarshalTo(audienceProto); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal the envoy.extensions.filters.http.gcp_authn.v3.Audience resource from Any proto: %v", err)
+	}
+	if audienceProto.GetUrl() == "" {
+		return nil, fmt.Errorf("empty url field in audience metadata")
+	}
+	return AudienceMetadataValue{Audience: audienceProto.GetUrl()}, nil
+}

internal/xds/xdsclient/xdsresource/metadata_test.go

@@ -19,12 +19,18 @@ package xdsresource
 import (
 	"testing"
 
-	v3corepb "github.com/envoyproxy/go-control-plane/envoy/config/core/v3"
 	"github.com/google/go-cmp/cmp"
 	"google.golang.org/grpc/internal/testutils"
+	"google.golang.org/protobuf/types/known/anypb"
+
+	v3corepb "github.com/envoyproxy/go-control-plane/envoy/config/core/v3"
+	v3gcpauthnpb "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/gcp_authn/v3"
 )
 
-const proxyAddressTypeURL = "type.googleapis.com/envoy.config.core.v3.Address"
+const (
+	proxyAddressTypeURL = "type.googleapis.com/envoy.config.core.v3.Address"
+	audienceTypeURL     = "type.googleapis.com/envoy.extensions.filters.http.gcp_authn.v3.Audience"
+)
 
 func setupProxyAddressConverter(t *testing.T) {
 	registerMetadataConverter(proxyAddressTypeURL, proxyAddressConvertor{})
@@ -33,6 +39,13 @@ func setupProxyAddressConverter(t *testing.T) {
 	})
 }
 
+func setupAudienceConverter(t *testing.T) {
+	registerMetadataConverter(audienceTypeURL, audienceConverter{})
+	t.Cleanup(func() {
+		unregisterMetadataConverterForTesting(audienceTypeURL)
+	})
+}
+
 func (s) TestProxyAddressConverterSuccess(t *testing.T) {
 	setupProxyAddressConverter(t)
 	converter := metadataConverterForType(proxyAddressTypeURL)
@@ -45,7 +58,7 @@ func (s) TestProxyAddressConverterSuccess(t *testing.T) {
 		want ProxyAddressMetadataValue
 	}{
 		{
-			name: "valid IPv4 address and port",
+			name: "valid_IPv4_address_and_port",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -61,7 +74,7 @@ func (s) TestProxyAddressConverterSuccess(t *testing.T) {
 			},
 		},
 		{
-			name: "valid full IPv6 address and port",
+			name: "valid_full_IPv6_address_and_port",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -77,7 +90,7 @@ func (s) TestProxyAddressConverterSuccess(t *testing.T) {
 			},
 		},
 		{
-			name: "valid shortened IPv6 address",
+			name: "valid_shortened_IPv6_address",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -93,7 +106,7 @@ func (s) TestProxyAddressConverterSuccess(t *testing.T) {
 			},
 		},
 		{
-			name: "valid link-local IPv6 address",
+			name: "valid_link-local_IPv6_address",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -109,7 +122,7 @@ func (s) TestProxyAddressConverterSuccess(t *testing.T) {
 			},
 		},
 		{
-			name: "valid IPv4-mapped IPv6 address",
+			name: "valid_IPv4-mapped_IPv6_address",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -152,7 +165,7 @@ func (s) TestProxyAddressConverterFailure(t *testing.T) {
 		wantErr string
 	}{
 		{
-			name: "invalid address",
+			name: "invalid_address",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -163,14 +176,14 @@ func (s) TestProxyAddressConverterFailure(t *testing.T) {
 			wantErr: "address field is not a valid IPv4 or IPv6 address: \"invalid-ip\"",
 		},
 		{
-			name: "missing socket_address",
+			name: "missing_socket_address",
 			addr: &v3corepb.Address{
 				// No SocketAddress field set.
 			},
 			wantErr: "no socket_address field in metadata",
 		},
 		{
-			name: "address is not a socket address",
+			name: "address_is_not_a_socket_address",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_EnvoyInternalAddress{
 					EnvoyInternalAddress: &v3corepb.EnvoyInternalAddress{
@@ -183,7 +196,7 @@ func (s) TestProxyAddressConverterFailure(t *testing.T) {
 			wantErr: "no socket_address field in metadata",
 		},
 		{
-			name: "port value not set",
+			name: "port_value_not_set",
 			addr: &v3corepb.Address{
 				Address: &v3corepb.Address_SocketAddress{
 					SocketAddress: &v3corepb.SocketAddress{
@@ -206,3 +219,47 @@ func (s) TestProxyAddressConverterFailure(t *testing.T) {
 		})
 	}
 }
+
+func (s) TestAudienceConverterSuccess(t *testing.T) {
+	setupAudienceConverter(t)
+	converter := metadataConverterForType(audienceTypeURL)
+	if converter == nil {
+		t.Fatalf("Converter for %q not found in registry", audienceTypeURL)
+	}
+	tests := []struct {
+		name     string
+		audience *anypb.Any
+		want     AudienceMetadataValue
+		wantErr  string
+	}{
+		{
+			name:     "valid_audience",
+			audience: testutils.MarshalAny(t, &v3gcpauthnpb.Audience{Url: "https://example.com"}),
+			want:     AudienceMetadataValue{Audience: "https://example.com"},
+		},
+		{
+			name:     "empty_audience",
+			audience: testutils.MarshalAny(t, &v3gcpauthnpb.Audience{Url: ""}),
+			want:     AudienceMetadataValue{Audience: ""},
+			wantErr:  "empty url field in audience metadata",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := converter.convert(tt.audience)
+			if tt.wantErr != "" {
+				if err == nil || err.Error() != tt.wantErr {
+					t.Errorf("convert() got error = %v, wantErr = %q", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("convert() failed with error: %v", err)
+			}
+			if diff := cmp.Diff(tt.want, got); diff != "" {
+				t.Errorf("convert(%s) returned unexpected diff (-want +got):\n%s", tt.audience.GetTypeUrl(), diff)
+			}
+		})
+	}
+}

internal/xds/xdsclient/xdsresource/type_cds.go

@@ -83,6 +83,9 @@ type ClusterUpdate struct {
 	// LRSReportEndpointMetrics specifies the subset of ORCA metrics that
 	// should be propagated to the LRS server.
 	LRSReportEndpointMetrics *LRSReportEndpointMetricsConfig
+
+	// Metadata contains the metadata from the cluster resource.
+	Metadata map[string]any
 }
 
 // LRSReportEndpointMetricsConfig holds the configuration for propagating ORCA

internal/xds/xdsclient/xdsresource/unmarshal_cds.go

@@ -215,6 +215,14 @@ func validateClusterAndConstructClusterUpdate(cluster *v3clusterpb.Cluster, serv
 		}
 	}
 
+	var metadata map[string]any
+	if envconfig.GCPAuthenticationFilterEnabled {
+		var err error
+		if metadata, err = validateAndConstructMetadata(cluster.GetMetadata()); err != nil {
+			return ClusterUpdate{}, err
+		}
+	}
+
 	ret := ClusterUpdate{
 		ClusterName:              cluster.GetName(),
 		SecurityCfg:              sc,
@@ -223,6 +231,7 @@ func validateClusterAndConstructClusterUpdate(cluster *v3clusterpb.Cluster, serv
 		OutlierDetection:         od,
 		TelemetryLabels:          telemetryLabels,
 		LRSReportEndpointMetrics: lrsReportEndpointMetrics,
+		Metadata:                 metadata,
 	}
 
 	if lrs := cluster.GetLrsServer(); lrs != nil {