Zuplo
Configuration

Managed Dedicated: Host Header Override

By default, the Host header your gateway sends to a backend is derived from the URL it connects to. Host header override lets your code send a Host header that differs from the hostname in the request URL, so the gateway can connect to one address while the backend sees the hostname it expects.

This setting is only available on Managed Dedicated instances and is off by default.

When to use it

Reach for this when the address you connect to and the hostname your backend expects aren't the same:

  • Virtual-hosted backends. A single load balancer, ingress controller, or web server hosts several sites and picks one based on the Host header. Your gateway connects to the shared address and names the site it wants.
  • Private networking. With private networking, you reach a backend through an internal endpoint or IP whose DNS name doesn't match the public hostname the backend is configured for, such as https://10.0.4.12 with a Host of api.acme.com.
  • Testing a new backend before DNS moves. Point the gateway at the new origin's address while sending the production Host header, so you can validate the migration without changing public DNS.
  • Legacy backends keyed on the hostname. Applications that route, build links, or select a tenant from the Host header keep working when the gateway sits in front of them.

An incorrect Host header can send traffic to the wrong site on a shared backend, and some applications trust the header when building redirects and links. Enable this setting only if you need it, and set the header to a value your code controls rather than one copied from client input.

Enable the setting

Add allowHostHeaderOverride to the zuplo.jsonc file at the root of your project and deploy:

JSONCode
{
  "version": 1,
  "projectType": "managed-dedicated",
  "allowHostHeaderOverride": true,
}

The setting applies to the whole project. Without it, a Host header you set on an outbound request is ignored.

The zuplo.jsonc file isn't editable in the Zuplo Portal. Connect your project to source control and edit the file there or push a local change with git. See Project Configuration for the other settings this file supports.

Example

Once the setting is enabled, set the Host header on any outbound request. This custom handler connects to an internal load balancer and tells it which site to serve:

TypeScriptCode
import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const url = new URL(request.url);

  return fetch(`${environment.INTERNAL_ORIGIN}${url.pathname}${url.search}`, {
    method: request.method,
    body: request.body,
    headers: {
      ...Object.fromEntries(request.headers),
      Host: "api.acme.com",
    },
  });
}

With INTERNAL_ORIGIN set to https://10.0.4.12, the gateway connects to 10.0.4.12 and the backend receives a request for api.acme.com.

Last modified on
OverviewArchitecture