Introduction:
This KB provides configuration reference information for details about the `RouteTimeoutFilter` resource, which defines timeout settings for specific routes from an API gateway listener to the destination service in Consul service mesh.
Pre-Requisites:
- Consul-k8s version =< 1.3.0
- A Stable Consul cluster with API gateway and Services installed in Consul Dataplane accessible via API gateway
NOTE: In the examples to be shown, sample application used is Birdwatcher(Involving 2 services: Frontendbird and Backendbird), It can be found here : https://github.com/consul-up/birdwatcher
Setup:
When no custom timeouts are configured in the Consul environment running with applications accessible via API Gateway, the default envoy request timeout configured is 15s(x-envoy-expected-rq-timeout-ms), as seen in below sample logs from Consul API gateway :
api-gateway 2025-12-10T19:31:50.616Z+00:00 [debug] envoy.connection(25) [Tags: "ConnectionId":"75899"] current connecting state: false
api-gateway 2025-12-10T19:31:50.617Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"75899","StreamId":"11669786640032336746"] cluster 'frontendbird.consul.dc1.internal.60d9964e-a876-713c-b92d-f005c4c9d77e.consul' match for URL '/shuffle?error-rate=0&delay=0'
api-gateway 2025-12-10T19:31:50.617Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"75899","StreamId":"11669786640032336746"] router decoding headers:
api-gateway ':authority', '192.168.105.2:8090'
api-gateway ':path', '/shuffle?error-rate=0&delay=0'
api-gateway ':method', 'GET'
api-gateway ':scheme', 'http'
api-gateway 'user-agent', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36'
api-gateway 'dnt', '1'
api-gateway 'x-client-trace-id', '1'
api-gateway 'accept', '*/*'
api-gateway 'referer', 'http://192.168.105.2:8090/'
api-gateway 'accept-encoding', 'gzip, deflate'
api-gateway 'accept-language', 'en-GB,en-US;q=0.9,en;q=0.8'
api-gateway 'x-forwarded-proto', 'http'
api-gateway 'x-request-id', '67610c96-c79e-b2ae-82de-86fcb18aaaf6'
api-gateway 'x-envoy-expected-rq-timeout-ms', '15000'
api-gateway 2025-12-10T19:31:50.618Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"75899","StreamId":"11669786640032336746"] pool ready
api-gateway 2025-12-10T19:31:50.662Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"75899","StreamId":"11669786640032336746"] upstream headers complete: end_stream=false
api-gateway 2025-12-10T19:31:50.662Z+00:00 [debug] envoy.http(25) [Tags: "ConnectionId":"75899","StreamId":"11669786640032336746"] encoding headers via codec (end_stream=false):
api-gateway ':status', '200'
api-gateway 'content-type', 'application/json; charset=utf-8'
api-gateway 'date', 'Wed, 10 Dec 2025 19:31:50 GMT'
api-gateway 'content-length', '1306'
api-gateway 'x-envoy-upstream-service-time', '44'
api-gateway 'server', 'envoy'
The above example snippet shows logs from API gateway when application was accessed from API Gateway, And you can see the x-envoy-expected-rq-timeout-ms default value set as 15000ms (15s) for the entire request trip till destination upstream. The above request will be a success as long as the Applications response to API gateway gets completed within 15s, and you receive an HTTP status of 200 as also seen in above logs.
In many practical scenarios, the applications may take longer than 15s to respond, and defaulting the default value x-envoy-expected-rq-timeout-ms of 15s, resulting in errors like upstream request timeout with an HTTP Status of 504. Below example shows the logs from api gateway exhibiting 504 errors:
api-gateway 2025-12-10T19:52:08.364Z+00:00 [debug] envoy.http(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] request end stream timestamp recorded
api-gateway 2025-12-10T19:52:08.364Z+00:00 [debug] envoy.connection(25) [Tags: "ConnectionId":"76023"] current connecting state: false
api-gateway 2025-12-10T19:52:08.365Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] cluster 'frontendbird.consul.dc1.internal.60d9964e-a876-713c-b92d-f005c4c9d77e.consul' match for URL '/shuffle?error-rate=0&delay=17'
api-gateway 2025-12-10T19:52:08.365Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] router decoding headers:
api-gateway ':authority', '192.168.105.2:8090'
api-gateway ':path', '/shuffle?error-rate=0&delay=17'
api-gateway ':method', 'GET'
api-gateway ':scheme', 'http'
api-gateway 'user-agent', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36'
api-gateway 'dnt', '1'
api-gateway 'x-client-trace-id', '1'
api-gateway 'accept', '*/*'
api-gateway 'referer', 'http://192.168.105.2:8090/'
api-gateway 'accept-encoding', 'gzip, deflate'
api-gateway 'accept-language', 'en-GB,en-US;q=0.9,en;q=0.8'
api-gateway 'x-forwarded-proto', 'http'
api-gateway 'x-request-id', 'fbf8e5cd-610d-b66e-b6c7-36c25f57d26c'
api-gateway 'x-envoy-expected-rq-timeout-ms', '15000'
api-gateway 2025-12-10T19:52:23.367Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] upstream timeout
api-gateway 2025-12-10T19:52:23.367Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] resetting pool request
api-gateway 2025-12-10T19:52:23.367Z+00:00 [debug] envoy.client(25) [Tags: "ConnectionId":"75895"] Request reset. Reason 0
api-gateway 2025-12-10T19:52:23.367Z+00:00 [debug] envoy.http(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] Sending local reply with details response_timeout
api-gateway 2025-12-10T19:52:23.368Z+00:00 [debug] envoy.http(25) [Tags: "ConnectionId":"76023","StreamId":"8807877821435304157"] encoding headers via codec (end_stream=false):
api-gateway ':status', '504'
api-gateway 'content-length', '24'
api-gateway 'content-type', 'text/plain'
api-gateway 'date', 'Wed, 10 Dec 2025 19:52:23 GMT'
api-gateway 'server', 'envoy'
In the above snippet of logs from API gateway, we can see that the when application takes longer than default 15s(using a simulated delay for understanding) : api-gateway ':path', '/shuffle?error-rate=0&delay=17', we notice that the we get a 504 error, which means a request timeout error on API gateway.
How to use RouteTimeoutFilter on Consul API gateway:
To apply RouteTimeoutFilter settings to a HTTPRoute, set the rules.filters.type parameter in an route to extensionRef and specify the name of the filter in rules.filters.extensionRef.name field. Refer to Route resource configuration reference for additional information.
Below is the sample configuration for example used, and setting requestTimeout: "30s", this will configure x-envoy-expected-rq-timeout-ms to a desired value of 30s, and should give enough time for request to finish.
apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteTimeoutFilter
metadata:
name: <example-config-name>
spec:
idleTimeout: "25s"
requestTimeout: "30s"
One the above Configuration is applied using kubectl apply -f <route-timeout-filter.yaml>, it needs to be referenced in a specific http route on API gateway, where the services in question exists, as below by specifying the name of the filter in rules.filters.extensionRef.name field, and applying the http route using kubectl apply -f <http-route.yaml>
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
name: <upstream-route-name>
namespace: <namespace-name>
spec:
parentRefs:
- name: api-gateway
rules:
- filters:
- type: ExtensionRef
extensionRef:
group: consul.hashicorp.com
kind: RouteTimeoutFilter
name: <example-config-name>
backendRefs:
- kind: Service
name: <service-name>
namespace: <namespace-name>
port: <port-of-service>
The above httpRoute config will bind the RouteTimeoutFilter to the specific route as shown, and relevant x-envoy-expected-rq-timeout-ms will be applied on API gateway for the specific route.
Now, If we try the access application again via api gateway, with Backend application has simulated delayed response of 17s , will finally succeed as the x-envoy-expected-rq-timeout-ms has been configured to 30s, which easily accommodates the application delay. Notice the request went through the destination application, with a HTTP code 200.
api-gateway 2025-12-10T20:24:27.635Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"76220","StreamId":"6759104432878686209"] cluster 'frontendbird.consul.dc1.internal.60d9964e-a876-713c-b92d-f005c4c9d77e.consul' match for URL '/shuffle?error-rate=0&delay=17'
api-gateway 2025-12-10T20:24:27.635Z+00:00 [debug] envoy.router(25) [Tags: "ConnectionId":"76220","StreamId":"6759104432878686209"] router decoding headers:
api-gateway ':authority', '192.168.105.2:8090'
api-gateway ':path', '/shuffle?error-rate=0&delay=17'
api-gateway ':method', 'GET'
api-gateway ':scheme', 'http'
api-gateway 'user-agent', 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36'
api-gateway 'dnt', '1'
api-gateway 'x-client-trace-id', '1'
api-gateway 'accept', '*/*'
api-gateway 'referer', 'http://192.168.105.2:8090/'
api-gateway 'accept-encoding', 'gzip, deflate'
api-gateway 'accept-language', 'en-GB,en-US;q=0.9,en;q=0.8'
api-gateway 'x-forwarded-proto', 'http'
api-gateway 'x-request-id', '03403df7-8316-b194-90f9-5e3887bd5c7a'
api-gateway 'x-envoy-expected-rq-timeout-ms', '30000'
api-gateway 2025-12-10T20:24:42.638Z+00:00 [debug] envoy.http(25) [Tags: "ConnectionId":"76220","StreamId":"6759104432878686209"] encoding headers via codec (end_stream=false):
api-gateway ':status', '200'
api-gateway 'content-type', 'application/json; charset=utf-8'
api-gateway 'date', 'Wed, 10 Dec 2025 20:24:42 GMT'
api-gateway 'content-length', '1309'
api-gateway 'x-envoy-upstream-service-time', '51'
api-gateway 'server', 'envoy'
Outcome:
By configuring a RouteTimeoutFilter and attaching it to the specific HTTPRoute, Consul API Gateway applies custom request timeouts to upstream traffic. This prevents premature 504 errors, ensures long-running application responses complete successfully, and stabilises request handling across the service mesh.
References:
- https://developer.hashicorp.com/consul/docs/reference/k8s/api-gateway/routetimeoutfilter
- https://developer.hashicorp.com/consul/docs/reference/k8s/api-gateway/routes