From 8f554285793b4154d575083e19e2183ef48d158a Mon Sep 17 00:00:00 2001 From: Thanatat Tamtan Date: Mon, 22 Jun 2026 23:06:27 +0700 Subject: [PATCH 1/3] docs(routes): document config.host upstream Host-header override Add config.host to the v2 config list and a dedicated "Override the Host header" subsection under External server, with curl + CLI (--host) examples. Primary use case is an external backend that virtual-hosts on Host; also works for deployment:// (WebService) targets. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01YYMGjvqWELm2ctgKamiMSS --- content/networking/routes.md | 40 ++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/content/networking/routes.md b/content/networking/routes.md index 39c4ca7..621bebc 100644 --- a/content/networking/routes.md +++ b/content/networking/routes.md @@ -65,6 +65,12 @@ request handling: returns 2xx the request is forwarded, otherwise the response is returned to the client. Request and response headers can be whitelisted via `authRequestHeaders` / `authResponseHeaders`. +- **`config.host`** — override the `Host` header the gateway sends upstream. + Empty (the default) forwards the request's original Host — the route's own + domain. Set it when the backend serves content by Host (virtual hosting); see + [External server](#override-the-host-header) below. It applies to + `http://` (external) and `deployment://` (WebService) targets and is ignored + for redirect and IPFS/IPNS/Static targets. ```bash curl https://api.deploys.app/route.createV2 \ @@ -114,6 +120,40 @@ A few rules the gateway enforces: trusted network path. The client-facing side is still HTTPS, terminated at the edge. +### Override the Host header + +By default the edge forwards your visitor's `Host` (the route domain, e.g. +`legacy.acme.com`) to your server. If that server virtual-hosts — serving +different sites by `Host` — point it at the right one with `config.host`: + +```bash +curl https://api.deploys.app/route.createV2 \ + -H "Authorization: Bearer $DEPLOYS_TOKEN" \ + -d '{ + "project": "acme", + "location": "gke.cluster-rcf2", + "domain": "legacy.acme.com", + "path": "/", + "target": "http://203.0.113.10:8080", + "config": { "host": "legacy.internal" } + }' +``` + +With the CLI, pass `--host`: + +```bash +deploys route create \ + --project acme --location gke.cluster-rcf2 \ + --domain legacy.acme.com --path / \ + --target http://203.0.113.10:8080 \ + --host legacy.internal +``` + +`host` is a bare hostname or IP, with an optional `:port` — no scheme or path. +It only rewrites the forwarded `Host` header; the backend is still chosen by +`target`. The same field works on a `deployment://` (WebService) target when +the container routes by `Host`. + {{< callout type="note" >}} External HTTP routes are billed for the **edge egress** they serve — since the compute is yours, there's no flat per-route fee. See From 4e47ce564df6eb339098881a91bad037f7ae5a63 Mon Sep 17 00:00:00 2001 From: Thanatat Tamtan Date: Tue, 23 Jun 2026 05:21:05 +0700 Subject: [PATCH 2/3] docs(routes): note Host override is ignored on access-gated deployment routes Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01YYMGjvqWELm2ctgKamiMSS --- content/networking/routes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/networking/routes.md b/content/networking/routes.md index 621bebc..1c6eea1 100644 --- a/content/networking/routes.md +++ b/content/networking/routes.md @@ -154,6 +154,12 @@ It only rewrites the forwarded `Host` header; the backend is still chosen by `target`. The same field works on a `deployment://` (WebService) target when the container routes by `Host`. +{{< callout type="note" >}} +The override is **not applied to a `deployment://` route whose deployment has +deployment-access (Google login) enabled** — the access gate anchors on the +original Host, so it takes precedence and the override is ignored on that route. +{{< /callout >}} + {{< callout type="note" >}} External HTTP routes are billed for the **edge egress** they serve — since the compute is yours, there's no flat per-route fee. See From 7fbf670284a78e817abbb48819eff6304808ba81 Mon Sep 17 00:00:00 2001 From: Thanatat Tamtan Date: Tue, 23 Jun 2026 06:26:47 +0700 Subject: [PATCH 3/3] docs(routes): scope Host override to external targets only The override is rejected on non-external targets (matching the api), so drop the deployment:// mention and the (now-moot) access-gate caveat. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01YYMGjvqWELm2ctgKamiMSS --- content/networking/routes.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/content/networking/routes.md b/content/networking/routes.md index 1c6eea1..f69402c 100644 --- a/content/networking/routes.md +++ b/content/networking/routes.md @@ -68,9 +68,8 @@ request handling: - **`config.host`** — override the `Host` header the gateway sends upstream. Empty (the default) forwards the request's original Host — the route's own domain. Set it when the backend serves content by Host (virtual hosting); see - [External server](#override-the-host-header) below. It applies to - `http://` (external) and `deployment://` (WebService) targets and is ignored - for redirect and IPFS/IPNS/Static targets. + [External server](#override-the-host-header) below. It is valid **only for an + `http://` (external) target** and is rejected for every other target type. ```bash curl https://api.deploys.app/route.createV2 \ @@ -151,14 +150,9 @@ deploys route create \ `host` is a bare hostname or IP, with an optional `:port` — no scheme or path. It only rewrites the forwarded `Host` header; the backend is still chosen by -`target`. The same field works on a `deployment://` (WebService) target when -the container routes by `Host`. - -{{< callout type="note" >}} -The override is **not applied to a `deployment://` route whose deployment has -deployment-access (Google login) enabled** — the access gate anchors on the -original Host, so it takes precedence and the override is ignored on that route. -{{< /callout >}} +`target`. The override is **external-only** — it is rejected on a +`deployment://`, redirect, or IPFS route, where the upstream `Host` is either +reserved for routing or has no meaning. {{< callout type="note" >}} External HTTP routes are billed for the **edge egress** they serve — since the