Add support for API key authN in TrafficPolicy #12962

ymesika · 2025-11-24T16:35:21Z

Description

Design for this is available in: #12919 (pending approval)

This PR adds API key authentication support to TrafficPolicies, allowing API keys to be provided via HTTP headers, query parameters, or cookies.

Features:

API key sources: header, query parameter, and cookie
Secret management via SecretRef or SecretSelector
Policy attachment at gateway, HTTPRoute, and route levels
Uses Envoy's native envoy.filters.http.api_key_auth filter

Testing:

Unit, translator (golden files), and e2e tests
E2e tests cover all attachment levels, key sources, and secret update propagation

CI: Added e2e to cluster-five in CI workflow

Fixes #12909

Change Type

/kind feature

Changelog

Add support for configuring an API key authentication in TrafficPolicy with keys defined in secret(s)

Additional Notes

Signed-off-by: Yossi Mesika <[email protected]>

Copilot

Pull request overview

This PR adds API key authentication support to TrafficPolicy, enabling users to authenticate requests using API keys provided via HTTP headers, query parameters, or cookies. The implementation uses Envoy's native envoy.filters.http.api_key_auth filter and integrates with Kubernetes secrets for key management.

Key Changes:

Added APIKeyAuthentication field to TrafficPolicy CRD with support for multiple key sources (header/query/cookie) and flexible secret management
Implemented API key auth filter handling in the trafficpolicy plugin following the same pattern as RBAC (disabled by default, configured per-route)
Added comprehensive test coverage including unit tests, translator tests (golden files), and e2e tests covering all attachment levels and secret update propagation

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
api/v1alpha1/traffic_policy_types.go	Defines APIKeyAuthentication and APIKeySource types with validation constraints
api/v1alpha1/zz_generated.deepcopy.go	Auto-generated deepcopy methods for new API types
install/helm/kgateway-crds/templates/gateway.kgateway.dev_trafficpolicies.yaml	CRD schema definition for API key authentication
internal/kgateway/krtcollections/secrets.go	Adds GetSecretCollection method to access secrets without reference grant checks
internal/kgateway/extensions2/plugins/trafficpolicy/api_key_auth.go	Core implementation of API key auth translation to Envoy configuration
internal/kgateway/extensions2/plugins/trafficpolicy/api_key_auth_test.go	Unit tests for API key auth IR, validation, and filter handling
internal/kgateway/extensions2/plugins/trafficpolicy/traffic_policy_plugin.go	Integration of API key auth into trafficpolicy plugin filter chain
internal/kgateway/extensions2/plugins/trafficpolicy/merge.go	Merge logic for API key auth policies
internal/kgateway/extensions2/plugins/trafficpolicy/constructor.go	Constructor integration for API key auth IR
internal/kgateway/translator/gateway/gateway_translator_test.go	Translator tests for API key auth at gateway, HTTPRoute, and route levels
internal/kgateway/translator/gateway/testutils/inputs/traffic-policy/	Golden file test inputs for various API key auth configurations
internal/kgateway/translator/gateway/testutils/outputs/traffic-policy/	Expected golden file outputs for API key auth translation
test/e2e/features/apikeyauth/types.go	E2e test suite type definitions and manifest paths
test/e2e/features/apikeyauth/suite.go	E2e test implementations covering all key sources and secret updates
test/e2e/features/apikeyauth/testdata/	Test manifests for e2e tests
test/e2e/tests/kgateway_tests.go	Registration of APIKeyAuth test suite
.github/workflows/e2e.yaml	Added APIKeyAuth tests to cluster-five CI workflow

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

test/e2e/features/apikeyauth/suite.go

install/helm/kgateway-crds/templates/gateway.kgateway.dev_trafficpolicies.yaml

api/v1alpha1/traffic_policy_types.go

Signed-off-by: Yossi Mesika <[email protected]>

lgadban

Can we add translator tests (and maybe augment the e2e test as well) to have a scenario with APIKey policy attached to both Gateway and Route?

IIUC the behavior should be that the route-specific policy is the only one applied

api/v1alpha1/traffic_policy_types.go

lgadban · 2025-11-26T20:07:19Z

internal/kgateway/extensions2/plugins/trafficpolicy/api_key_auth.go

+		// Fetch secrets matching labels, then filter by namespace
+		allSecrets := krt.Fetch(krtctx, secretCol, krt.FilterLabel(ak.SecretSelector.MatchLabels))
+		for i := range allSecrets {
+			secret := &allSecrets[i]
+			if secret.Namespace == policy.Namespace {
+				secrets = append(secrets, secret)
+			}
+		}


Can we not filter by namespace as part of the initial krt.Fetch?
Something like:

krt.Fetch(krtctx, secretCol, krt.FilterGeneric(func(obj any) bool {...}, krt.FilterLabel(ak.SecretSelector.MatchLabels))

We still may need to iterate on the specifics here to get performance to a reasonable place. (adding a specific Index, etc.)

A very similar concept was added in #11163.

Either way, we should make sure and track some basic performance numbers (i.e. resource impact vs. number of secrets, etc.).

This can also be a follow up

Modified to have a FilterGeneric

lgadban · 2025-11-26T20:15:10Z

api/v1alpha1/kgateway/traffic_policy_types.go

+}
+
+// +kubebuilder:validation:ExactlyOneOf=secretRef;secretSelector
+type APIKeyAuthentication struct {


Just realized this after the EP has merged, but we don't expose a disable option for APIKey.

We may need to in order to be consistent with our other policies.

Unfortunately the envoy api doesn't have a disabled field like other filter configs.
I think we can still support this by adding config to all routes instead of a higher level one. When it's disabled on a route we will avoid adding it.
Is this an approach that makes sense?

We can do this in a follow up, but we have general pattern we can use to handle global disable for various policies by using Envoy's generic filter disable mechanism and a specifically configured composite filter.

See #12945 for more details on how we did it for JWT.

I didn't manage to add it to this PR. Will open a follow-up an issue for that.

Signed-off-by: Yossi Mesika <[email protected]>

lgadban

LGTM!
Approved with a few nits, but I definitely think we need to make the secret collection getter longer and more explicit in a follow up, possibly when we add global disable.

lgadban · 2025-12-01T20:54:04Z

api/v1alpha1/kgateway/traffic_policy_types.go

+	// APIKeyAuthentication authenticates users based on a configured API Key.
+	// +optional
+	APIKeyAuthentication *APIKeyAuthentication `json:"apiKeyAuthentication,omitempty"`


this is a nit and would like other opinions, but this could just be apiKey ?

I'm indifferent between the two names. Hoping to get other opinions too.

we don't have consensus so I would just leave as-is and we can address in a follow up

pkg/kgateway/extensions2/plugins/trafficpolicy/api_key_auth.go

pkg/kgateway/translator/gateway/gateway_translator_test.go

lgadban · 2025-12-01T21:03:09Z

pkg/krtcollections/secrets.go

+
+// GetSecretCollection returns the secret collection for a given GroupKind.
+// This is useful for accessing secrets without reference grant checks (e.g., same namespace).
+func (s *SecretIndex) GetSecretCollection(gk schema.GroupKind) krt.Collection[ir.Secret] {


We should probably rename this method to be explicit that refGrants are not being used here, and should be explicit in the godoc that you MUST know what you are doing to ignore refGrant look ups

See below for how we handled this for a similar method:

kgateway/pkg/krtcollections/policy.go

Lines 322 to 324 in 8419f0a

func (i *BackendIndex) GetBackendFromRefWithoutRefGrantValidation(kctx krt.HandlerContext, src ir.ObjectSource, ref gwv1.BackendObjectReference) (*ir.BackendObjectIR, error) {

return i.getBackendFromRef(kctx, src.Namespace, ref)

}

Either way though, you are exposing this because we need the raw collection to do our own FilterKey right?

Thank you for this important comment.
This led me to totally modify how we handle the Secret ref and selectors and take into account whether there is a reference grant when matching secrets are not in the same namespace.
Also added multiple setup tests for those.

Signed-off-by: Yossi Mesika <[email protected]>

ymesika · 2025-12-03T14:21:28Z

api/v1alpha1/kgateway/traffic_policy_types.go

+	//   client2: "k-456"
+	//
+	// +optional
+	SecretRef *gwv1.SecretObjectReference `json:"secretRef,omitempty"`


@lgadban notice I changed it to SecretObjectReference from LocalObjectReference.

Signed-off-by: Yossi Mesika <[email protected]>

lgadban · 2025-12-04T22:17:51Z

pkg/krtcollections/secrets.go

+			if !s.refgrants.ReferenceAllowed(kctx, from.GroupKind, from.Namespace, to) {
+				return nil, ErrMissingReferenceGrant
+			}


if we return here, is there even value in collecting allowedSecrets?

should we just continue but aggregate errors encountered, then return allowedSecrets and the joined errors if any are present?

lgadban · 2025-12-04T22:21:20Z

pkg/krtcollections/secrets.go

+	kctx krt.HandlerContext,
+	from From,
+	secretGK schema.GroupKind,
+	namespace string,


is namespace field actually used?

lgadban · 2025-12-04T22:22:20Z

pkg/krtcollections/secrets.go

-// This is useful for accessing secrets without reference grant checks (e.g., same namespace).
-func (s *SecretIndex) GetSecretCollection(gk schema.GroupKind) krt.Collection[ir.Secret] {
-	return s.secrets[gk]
+// GetSecretsBySelector retrieves secrets matching the label selector in the specified namespace,


see comment below, this doc is confusing as namespace doesn't seem to be relevant here.

IIUC, this method will get secrets matching labels in all namespaces and then enforce RefGrants for that set of secrets

lgadban · 2025-12-04T22:26:20Z

test/e2e/features/apikeyauth/types.go

+	apiKeyAuthManifestQuery        = filepath.Join(fsutils.MustGetThisDir(), "testdata", "api-key-auth-query.yaml")
+	apiKeyAuthManifestCookie       = filepath.Join(fsutils.MustGetThisDir(), "testdata", "api-key-auth-cookie.yaml")
+	apiKeyAuthManifestSecretUpdate = filepath.Join(fsutils.MustGetThisDir(), "testdata", "api-key-auth-secret-update.yaml")
+	apiKeyAuthManifestDisable      = filepath.Join(fsutils.MustGetThisDir(), "testdata", "api-key-auth-disable.yaml")


apiKeyAuthManifestDisable is not currently used right? (as it will be implemented in a follow up?)

can we remove it for now and all the related types/files/etc

lgadban · 2025-12-04T22:29:55Z

test/e2e/features/apikeyauth/suite.go

according to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/api_key_auth/v3/api_key_auth.proto#envoy-v3-api-field-extensions-filters-http-api-key-auth-v3-keysource-header

if the header source is used, it supports the prefix of Bearer in the header value.

If it's easy to add, it would be great to add a test case for this to the basic api-key-auth.yaml test.
I imagine an extremely common use case would be the standard Authorization header with a Bearer $APIKEY value.

Add support for API key authN in TrafficPolicy

fd44ae2

Signed-off-by: Yossi Mesika <[email protected]>

Copilot AI review requested due to automatic review settings November 24, 2025 16:35

Copilot started reviewing on behalf of ymesika November 24, 2025 16:35 View session

gateway-bot added kind/feature Categorizes issue or PR as related to a new feature. release-note labels Nov 24, 2025

Copilot finished reviewing on behalf of ymesika November 24, 2025 16:38

Lint fix

d16cab0

Signed-off-by: Yossi Mesika <[email protected]>

Copilot AI reviewed Nov 24, 2025

View reviewed changes

ymesika added 2 commits November 24, 2025 16:49

Copilot review comments addressed

7d8b1b8

Signed-off-by: Yossi Mesika <[email protected]>

Golden refreshed

1699f45

Signed-off-by: Yossi Mesika <[email protected]>

lgadban self-requested a review November 25, 2025 04:06

ymesika added 5 commits November 25, 2025 08:26

Sort test output credentials for consistency

8718f8e

Signed-off-by: Yossi Mesika <[email protected]>

Add a configurable client id header and simplify code

fa97d62

Signed-off-by: Yossi Mesika <[email protected]>

Allow empty ClientIdHeader

43bdc0d

Signed-off-by: Yossi Mesika <[email protected]>

Change HideAPIKey to ForwardCredential

5877f3f

Signed-off-by: Yossi Mesika <[email protected]>

Merge branch 'main' into api-key-auth

3dfc517

Signed-off-by: Yossi Mesika <[email protected]>

lgadban reviewed Nov 26, 2025

View reviewed changes

ymesika added 3 commits November 27, 2025 13:45

Review comments addressed

da8d09d

Signed-off-by: Yossi Mesika <[email protected]>

Merge branch 'main' into api-key-auth

343705d

Signed-off-by: Yossi Mesika <[email protected]>

Merge branch 'main' into api-key-auth

a532c41

Signed-off-by: Yossi Mesika <[email protected]>

lgadban approved these changes Dec 1, 2025

View reviewed changes

ymesika added 2 commits December 3, 2025 15:49

Support refgrants in SecretRef or Selector

b4df3ea

Signed-off-by: Yossi Mesika <[email protected]>

Merge branch 'main' into api-key-auth

a7b6517

Signed-off-by: Yossi Mesika <[email protected]>

ymesika commented Dec 3, 2025

View reviewed changes

Merge branch 'main' into api-key-auth

51ea7a8

Signed-off-by: Yossi Mesika <[email protected]>

lgadban reviewed Dec 4, 2025

View reviewed changes

	func (i BackendIndex) GetBackendFromRefWithoutRefGrantValidation(kctx krt.HandlerContext, src ir.ObjectSource, ref gwv1.BackendObjectReference) (ir.BackendObjectIR, error) {
	return i.getBackendFromRef(kctx, src.Namespace, ref)
	}

Add support for API key authN in TrafficPolicy #12962

Are you sure you want to change the base?

Add support for API key authN in TrafficPolicy #12962

Uh oh!

Conversation

ymesika commented Nov 24, 2025

Description

Change Type

Changelog

Additional Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lgadban left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lgadban left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants