feat: add FailedRefetchDuration to RemoteJWKS (#9265)

jukie · web-flow · commit 139de9952858 · 2026-06-21T18:43:30.000-07:00
Add support for failed_refetch_duration

Signed-off-by: jukie &lt;10012479+jukie@users.noreply.github.com&gt;
diff --git a/api/v1alpha1/jwt_types.go b/api/v1alpha1/jwt_types.go
@@ -115,6 +115,15 @@ type RemoteJWKS struct {
 	// +kubebuilder:default="300s"
 	// +optional
 	CacheDuration *gwapiv1.Duration `json:"cacheDuration,omitempty"`
+
+	// FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS
+	// after a failed fetch.
+	// This does not control retries within a single fetch attempt (see BackendSettings.Retry),
+	// only the interval between fetch attempts after a failure.
+	// If not specified, Envoy's default of 1 second is used.
+	//
+	// +optional
+	FailedRefetchDuration *gwapiv1.Duration `json:"failedRefetchDuration,omitempty"`
 }
 
 // LocalJWKSType defines the types of values for Local JWKS.
diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml
@@ -5369,6 +5369,15 @@ spec:
                                 in GEP-2257, a strict subset of the syntax parsed by Golang time.ParseDuration.
                               pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
                               type: string
+                            failedRefetchDuration:
+                              description: |-
+                                FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS
+                                after a failed fetch.
+                                This does not control retries within a single fetch attempt (see BackendSettings.Retry),
+                                only the interval between fetch attempts after a failure.
+                                If not specified, Envoy's default of 1 second is used.
+                              pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
+                              type: string
                             uri:
                               description: |-
                                 URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.
diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml
@@ -5368,6 +5368,15 @@ spec:
                                 in GEP-2257, a strict subset of the syntax parsed by Golang time.ParseDuration.
                               pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
                               type: string
+                            failedRefetchDuration:
+                              description: |-
+                                FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS
+                                after a failed fetch.
+                                This does not control retries within a single fetch attempt (see BackendSettings.Retry),
+                                only the interval between fetch attempts after a failure.
+                                If not specified, Envoy's default of 1 second is used.
+                              pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
+                              type: string
                             uri:
                               description: |-
                                 URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.
diff --git a/internal/gatewayapi/securitypolicy.go b/internal/gatewayapi/securitypolicy.go
@@ -1479,11 +1479,12 @@ func (t *Translator) buildRemoteJWKS(
 	gtwCtx *GatewayContext,
 ) (*ir.RemoteJWKS, error) {
 	var (
-		protocol      ir.AppProtocol
-		rd            *ir.RouteDestination
-		traffic       *ir.TrafficFeatures
-		err           error
-		cacheDuration *metav1.Duration
+		protocol              ir.AppProtocol
+		rd                    *ir.RouteDestination
+		traffic               *ir.TrafficFeatures
+		err                   error
+		cacheDuration         *metav1.Duration
+		failedRefetchDuration *metav1.Duration
 	)
 
 	u, err := url.Parse(remoteJWKS.URI)
@@ -1518,11 +1519,20 @@ func (t *Translator) buildRemoteJWKS(
 		cacheDuration = ir.MetaV1DurationPtr(d)
 	}
 
+	if remoteJWKS.FailedRefetchDuration != nil {
+		d, err := time.ParseDuration(string(*remoteJWKS.FailedRefetchDuration))
+		if err != nil {
+			return nil, err
+		}
+		failedRefetchDuration = ir.MetaV1DurationPtr(d)
+	}
+
 	return &ir.RemoteJWKS{
-		Destination:   rd,
-		Traffic:       traffic,
-		URI:           remoteJWKS.URI,
-		CacheDuration: cacheDuration,
+		Destination:           rd,
+		Traffic:               traffic,
+		URI:                   remoteJWKS.URI,
+		CacheDuration:         cacheDuration,
+		FailedRefetchDuration: failedRefetchDuration,
 	}, nil
 }
 
diff --git a/internal/gatewayapi/testdata/securitypolicy-with-jwt-backendsettings.in.yaml b/internal/gatewayapi/testdata/securitypolicy-with-jwt-backendsettings.in.yaml
@@ -114,6 +114,7 @@ securityPolicies:
                 consecutiveLocalOriginFailures: 5
                 splitExternalLocalOriginErrors: false
           uri: https://foo.bar.com/jwt/public-key/jwks.json
+          failedRefetchDuration: 30s
         claimToHeaders:
         - header: claim-header
           claim: claim
diff --git a/internal/gatewayapi/testdata/securitypolicy-with-jwt-backendsettings.out.yaml b/internal/gatewayapi/testdata/securitypolicy-with-jwt-backendsettings.out.yaml
@@ -176,6 +176,7 @@ securityPolicies:
                 requestTimeout: 5s
               tcp:
                 connectTimeout: 15s
+          failedRefetchDuration: 30s
           uri: https://foo.bar.com/jwt/public-key/jwks.json
     targetRef:
       group: gateway.networking.k8s.io
@@ -284,6 +285,7 @@ xdsIR:
               issuer: https://foo.bar.com
               name: foobar
               remoteJWKS:
+                failedRefetchDuration: 30s
                 traffic:
                   backendConnection:
                     bufferLimit: 100000000
diff --git a/internal/ir/xds.go b/internal/ir/xds.go
@@ -1263,6 +1263,10 @@ type RemoteJWKS struct {
 
 	// Duration after which the cached JWKS should be expired. If not specified, default cache duration is 5 minutes.
 	CacheDuration *metav1.Duration `json:"cacheDuration,omitempty"`
+
+	// FailedRefetchDuration is the interval Envoy waits before re-fetching the JWKS after a
+	// failed fetch. If not specified, Envoy's default of 1 second is used.
+	FailedRefetchDuration *metav1.Duration `json:"failedRefetchDuration,omitempty"`
 }
 
 // OIDC defines the schema for authenticating HTTP requests using
diff --git a/internal/ir/zz_generated.deepcopy.go b/internal/ir/zz_generated.deepcopy.go
diff --git a/internal/xds/translator/jwt.go b/internal/xds/translator/jwt.go
@@ -182,6 +182,9 @@ func buildJWTAuthn(irListener *ir.HTTPListener, jwtAuthn *jwtauthnv3.JwtAuthenti
 				if jwks.CacheDuration != nil {
 					remote.RemoteJwks.CacheDuration = durationpb.New(jwks.CacheDuration.Duration)
 				}
+				if jwks.FailedRefetchDuration != nil {
+					remote.RemoteJwks.AsyncFetch.FailedRefetchDuration = durationpb.New(jwks.FailedRefetchDuration.Duration)
+				}
 				// Set the retry policy if it exists.
 				if jwks.Traffic != nil && jwks.Traffic.Retry != nil {
 					var rp *corev3.RetryPolicy
diff --git a/internal/xds/translator/testdata/in/xds-ir/jwt-with-backend-tls-retry.yaml b/internal/xds/translator/testdata/in/xds-ir/jwt-with-backend-tls-retry.yaml
@@ -127,3 +127,4 @@ http:
                   connectTimeout: 15s
             uri: https://foo.bar.com/jwt/public-key/jwks.json
             cacheDuration: 300s
+            failedRefetchDuration: 30s
diff --git a/internal/xds/translator/testdata/out/xds-ir/jwt-with-backend-tls-retry.listeners.yaml b/internal/xds/translator/testdata/out/xds-ir/jwt-with-backend-tls-retry.listeners.yaml
@@ -32,7 +32,8 @@
                   - scp
                 payloadInMetadata: foobar
                 remoteJwks:
-                  asyncFetch: {}
+                  asyncFetch:
+                    failedRefetchDuration: 30s
                   cacheDuration: 300s
                   httpUri:
                     cluster: securitypolicy/default/policy-for-route/jwt/0
diff --git a/release-notes/current.yaml b/release-notes/current.yaml
@@ -19,6 +19,7 @@ new features: |
   Added support for `ListenerSet` as a `targetRef` kind in `ClientTrafficPolicy`, allowing client traffic settings to be applied to a named group of listeners without a gateway-wide policy.
   Added a `fromMetadata` field to global rate limit `limit` in `BackendTrafficPolicy`, allowing the limit value to be sourced from per-request dynamic metadata (e.g. set by an upstream ext_proc), falling back to the static `requests`/`unit` when the metadata is absent.
   Added `spec.clientIPDetection.xForwardedFor.disableXForwardedForAppend` to ClientTrafficPolicy to disable Envoy's automatic X-Forwarded-For append behavior when using XFF-based client IP detection.
+  Added a `failedRefetchDuration` field to JWT providers in `SecurityPolicy`, configuring how long Envoy waits before re-fetching the JWKS after a failed fetch. If not specified, Envoy's default of 1 second is used.
 
 bug fixes: |
   Fixed HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, and UDPRoute Accepted condition being set to False when an attached listener is not programmed due to a missing TLS certificate ref; listener programmed state is now correctly separated from route acceptance.
diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -5430,6 +5430,7 @@ _Appears in:_
 | `backendSettings` | _[ClusterSettings](#clustersettings)_ |  false  |  | BackendSettings holds configuration for managing the connection<br />to the backend. |
 | `uri` | _string_ |  true  |  | URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.<br />If a custom trust bundle is needed, it can be specified in a BackendTLSConfig resource and target the BackendRefs. |
 | `cacheDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#duration)_ |  false  | 300s |  |
+| `failedRefetchDuration` | _[Duration](https://gateway-api.sigs.k8s.io/reference/api-spec/1.5/spec/#duration)_ |  false  |  | FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS<br />after a failed fetch.<br />This does not control retries within a single fetch attempt (see BackendSettings.Retry),<br />only the interval between fetch attempts after a failure.<br />If not specified, Envoy's default of 1 second is used. |
 
 
 #### ReplaceRegexMatch
diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml
@@ -55731,6 +55731,15 @@ spec:
                                 in GEP-2257, a strict subset of the syntax parsed by Golang time.ParseDuration.
                               pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
                               type: string
+                            failedRefetchDuration:
+                              description: |-
+                                FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS
+                                after a failed fetch.
+                                This does not control retries within a single fetch attempt (see BackendSettings.Retry),
+                                only the interval between fetch attempts after a failure.
+                                If not specified, Envoy's default of 1 second is used.
+                              pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
+                              type: string
                             uri:
                               description: |-
                                 URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.
diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml
@@ -33704,6 +33704,15 @@ spec:
                                 in GEP-2257, a strict subset of the syntax parsed by Golang time.ParseDuration.
                               pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
                               type: string
+                            failedRefetchDuration:
+                              description: |-
+                                FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS
+                                after a failed fetch.
+                                This does not control retries within a single fetch attempt (see BackendSettings.Retry),
+                                only the interval between fetch attempts after a failure.
+                                If not specified, Envoy's default of 1 second is used.
+                              pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
+                              type: string
                             uri:
                               description: |-
                                 URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.
diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml
@@ -33704,6 +33704,15 @@ spec:
                                 in GEP-2257, a strict subset of the syntax parsed by Golang time.ParseDuration.
                               pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
                               type: string
+                            failedRefetchDuration:
+                              description: |-
+                                FailedRefetchDuration is the duration Envoy waits before re-fetching the JWKS
+                                after a failed fetch.
+                                This does not control retries within a single fetch attempt (see BackendSettings.Retry),
+                                only the interval between fetch attempts after a failure.
+                                If not specified, Envoy's default of 1 second is used.
+                              pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
+                              type: string
                             uri:
                               description: |-
                                 URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate.

Original file line number	Diff line number	Diff line change
`@@ -1263,6 +1263,10 @@ type RemoteJWKS struct {`
`1263`	`1263`
`1264`	`1264`	`// Duration after which the cached JWKS should be expired. If not specified, default cache duration is 5 minutes.`
`1265`	`1265`	CacheDuration *metav1.Duration `json:"cacheDuration,omitempty"`
	`1266`	`+`
	`1267`	`+ // FailedRefetchDuration is the interval Envoy waits before re-fetching the JWKS after a`
	`1268`	`+ // failed fetch. If not specified, Envoy's default of 1 second is used.`
	`1269`	+ FailedRefetchDuration *metav1.Duration `json:"failedRefetchDuration,omitempty"`
`1266`	`1270`	`}`
`1267`	`1271`
`1268`	`1272`	`// OIDC defines the schema for authenticating HTTP requests using`