From d8a121491870fb710ebdffb132062737f635278a Mon Sep 17 00:00:00 2001 From: bmertens-datum Date: Sat, 3 Oct 2026 16:21:16 -0400 Subject: [PATCH 1/2] docs: Add guide for raising an HTTPProxy's request timeout Datum's edge ends every response about 15 seconds after the request arrives, which cuts off large downloads, streams, and slow APIs. HTTPProxy has no timeout field, so the guide shows how to attach a BackendTrafficPolicy to the HTTPProxy's generated HTTPRoute and raise requestTimeout up to the 1 hour platform cap. Co-Authored-By: Claude Opus 5.5 (1M context) --- alb/guides/request-timeout.mdx | 277 +++++++++++++++++++++++++++++++++ docs.json | 3 +- 2 files changed, 279 insertions(+), 1 deletion(-) create mode 100644 alb/guides/request-timeout.mdx diff --git a/alb/guides/request-timeout.mdx b/alb/guides/request-timeout.mdx new file mode 100644 index 0000000..0c58342 --- /dev/null +++ b/alb/guides/request-timeout.mdx @@ -0,0 +1,277 @@ +--- +title: "Raise the Request Timeout for an HTTPProxy" +description: "Stop large downloads, streams, and slow API responses from being cut off after about 15 seconds by raising an HTTPProxy's request timeout to as much as 1 hour with datumctl and an Envoy Gateway BackendTrafficPolicy." +--- + +This guide describes how to **raise the request timeout** for an application behind a Datum **`HTTPProxy`**, from the default of about 15 seconds up to a maximum of **1 hour**, using `datumctl`. The configuration uses an **Envoy Gateway `BackendTrafficPolicy`** resource and applies to **Windows, macOS, and Linux**. + +--- + +## Overview + +By default, Datum's edge gives every request about **15 seconds** to finish. The clock starts when the request arrives and covers the whole response, not just the wait for it to begin. If your origin is still sending when time runs out, Datum ends the response. + +You likely need this guide if you see any of the following: + +- **Large downloads stop partway through.** The file is cut off after about 15 seconds. `curl` reports: + + ``` + curl: (18) transfer closed with 1234567 bytes remaining to read + ``` + +- **Streaming responses stop after about 15 seconds.** Server-sent events, log tails, long polling, and similar connections that stay open close without warning. +- **Slow requests fail with a `504`.** If your origin takes more than about 15 seconds to start answering, the request returns `504 Gateway Timeout` with a page that mentions `response_timeout`. + +`HTTPProxy` has no timeout setting of its own. Instead, you attach a `BackendTrafficPolicy` to the route that Datum creates for your `HTTPProxy`, and set the timeout there. + +At a high level, this setup: + +1. Finds the name of your `HTTPProxy`, which is also the name of the route to target +2. Applies a **`BackendTrafficPolicy`** that sets `timeout.http.requestTimeout` +3. Confirms the policy was accepted +4. Verifies that a long response now completes + +--- + +## Prerequisites + +- `datumctl` installed and authenticated +- A valid **Project** +- An existing **`HTTPProxy`** +- Permission to create: + - `BackendTrafficPolicy` + +Verify access and find your `HTTPProxy` name: + +```bash +datumctl get httpproxy --project --namespace default +``` + +--- + +## Critical Requirement: Target the Route with Your HTTPProxy's Name + +Datum creates an `HTTPRoute` for every `HTTPProxy`, and gives it **the same name as the `HTTPProxy`**. The policy must target that `HTTPRoute`, not the `HTTPProxy` itself. + +### Why This Matters + +- A `BackendTrafficPolicy` can only attach to Gateway API resources such as an `HTTPRoute`. It cannot target an `HTTPProxy` directly +- If `targetRefs` names a route that doesn't exist, the policy is stored but never takes effect, and your responses are still cut off at about 15 seconds + +You can confirm the route exists: + +```bash +datumctl get httproute --project --namespace default +``` + +--- + +## Configuration Steps + +### Step 1: Set Variables + +Set `timeout` to the longest you expect a single response to take, up to `1h`. Use a value like `90s`, `10m`, or `1h`. + +#### Windows (PowerShell) + +```powershell +$project = "your-project-id" +$namespace = "default" +$proxy = "your-httpproxy-name" +$hostname = "your-app.example.com" +$timeout = "1h" +``` + +#### macOS / Linux + +```bash +project="your-project-id" +namespace="default" +proxy="your-httpproxy-name" +hostname="your-app.example.com" +timeout="1h" +``` + +--- + +### Step 2: Apply the BackendTrafficPolicy + +> **Note:** Datum caps the request timeout at **1 hour**. A value higher than `1h` is rejected when you apply it. + +> **Warning:** Only one `BackendTrafficPolicy` can attach to a route. If your route already has one (for example, from the [Load Balancer Failover](/alb/guides/load-balancer-failover) guide), add the `timeout` block to that policy instead of creating a second one. A second policy targeting the same route is not accepted. + +#### Windows (PowerShell) + +```powershell +@" +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: BackendTrafficPolicy +metadata: + name: ${proxy}-timeout +spec: + targetRefs: + - group: gateway.networking.k8s.io + kind: HTTPRoute + name: $proxy + timeout: + http: + requestTimeout: $timeout +"@ | datumctl apply --project $project --namespace $namespace -f - +``` + +#### macOS / Linux + +```bash +cat <-timeout`) so it's easy to find and clean up + +--- + +## Summary + +- Datum's edge ends every response about 15 seconds after the request arrives unless you raise the timeout +- `HTTPProxy` has no timeout field. Set `timeout.http.requestTimeout` in a `BackendTrafficPolicy` instead +- The policy targets the `HTTPRoute` that has the same name as your `HTTPProxy` +- The maximum is `1h`, measured over the whole response, including streams +- Only one `BackendTrafficPolicy` can attach to a route, so add the timeout to an existing policy if there is one diff --git a/docs.json b/docs.json index dd2ac30..d1a112e 100644 --- a/docs.json +++ b/docs.json @@ -108,7 +108,8 @@ "alb/guides/basic-auth", "alb/guides/oidc-google", "alb/guides/oidc-auth0", - "alb/guides/load-balancer-failover" + "alb/guides/load-balancer-failover", + "alb/guides/request-timeout" ] } ] From 6ee100240f425ab29b322c4a9de6a344870b9473 Mon Sep 17 00:00:00 2001 From: bmertens-datum Date: Sat, 3 Oct 2026 16:23:59 -0400 Subject: [PATCH 2/2] docs: Quote the real status for a conflicting BackendTrafficPolicy Verified live: a second policy on the same route reports Accepted=False, reason Conflicted, and the first keeps working. Co-Authored-By: Claude Opus 5.5 (1M context) --- alb/guides/request-timeout.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/alb/guides/request-timeout.mdx b/alb/guides/request-timeout.mdx index 0c58342..b6d5d56 100644 --- a/alb/guides/request-timeout.mdx +++ b/alb/guides/request-timeout.mdx @@ -16,7 +16,7 @@ You likely need this guide if you see any of the following: - **Large downloads stop partway through.** The file is cut off after about 15 seconds. `curl` reports: ``` - curl: (18) transfer closed with 1234567 bytes remaining to read + curl: (18) transfer closed with bytes remaining to read ``` - **Streaming responses stop after about 15 seconds.** Server-sent events, log tails, long polling, and similar connections that stay open close without warning. @@ -98,7 +98,7 @@ timeout="1h" > **Note:** Datum caps the request timeout at **1 hour**. A value higher than `1h` is rejected when you apply it. -> **Warning:** Only one `BackendTrafficPolicy` can attach to a route. If your route already has one (for example, from the [Load Balancer Failover](/alb/guides/load-balancer-failover) guide), add the `timeout` block to that policy instead of creating a second one. A second policy targeting the same route is not accepted. +> **Warning:** Only one `BackendTrafficPolicy` can attach to a route. If your route already has one (for example, from the [Load Balancer Failover](/alb/guides/load-balancer-failover) guide), add the `timeout` block to that policy instead of creating a second one. A second policy targeting the same route reports `Accepted: False` with reason `Conflicted` and has no effect. #### Windows (PowerShell) @@ -245,7 +245,7 @@ datumctl delete backendtrafficpolicy ${proxy}-timeout \ |---------|------------|------------| | Responses still stop after about 15 seconds | `targetRefs` doesn't name the `HTTPRoute` for your `HTTPProxy`, or the policy is not `Accepted` | Set `targetRefs[].name` to the exact `HTTPProxy` name and check `status.ancestors` as in Step 3 | | Policy is rejected when you apply it | `requestTimeout` is higher than `1h` | Use `1h` or less | -| Policy is applied but not `Accepted` | Another `BackendTrafficPolicy` already targets the same route | Add the `timeout` block to the existing policy and delete the new one | +| Policy is applied but not `Accepted`, reason `Conflicted` | Another `BackendTrafficPolicy` already targets the same route (the older policy wins) | Add the `timeout` block to the existing policy and delete the new one | | Responses stop after exactly the value you set | The response took longer than the timeout | Raise the timeout (up to `1h`) or have the client reconnect | | Streamed responses never arrive, at any timeout | A `TrafficProtectionPolicy` (WAF) is attached | Known limitation, see [Limitations](#limitations) |