Skip to content

Route HTTP traffic

HTTP and HTTPS listeners that route requests by host, path, method, header and query, redirect to HTTPS, split traffic by weight, and serve several domains on one address.

Updated View as Markdown

An http or https listener reads each request and routes it by its rules, checked in order: the first rule that matches takes the request, and the listener’s default action takes the rest. An action forwards the request to one or more target groups, redirects it, or answers it with a fixed response. One load balancer can have TCP, TLS, HTTP and HTTPS listeners at once.

Targets get the client’s address in X-Forwarded-For, and the listener’s protocol and port in X-Forwarded-Proto and X-Forwarded-Port. X-Forwarded-For is appended to whatever the client sent, so trust only its last entry.

A WAF inspects requests to HTTP and HTTPS listeners before they reach a target, and blocks or logs what its rules match.

HTTP target groups

An HTTP listener forwards to http target groups. A group’s protocol is set when it’s created, and an http group can’t take PROXY protocol. Its health check is HTTP by default: GET / on the traffic port, healthy on 200-399.

ezgh lb target-groups create web --vpc vpc_5p7r9s3t1vxz --port 8080 --protocol http
ezgh lb target-groups create api --vpc vpc_5p7r9s3t1vxz --port 9000 --protocol http --health-check-path /healthz

A tcp group serves only TCP and TLS listeners, and an http group only HTTP and HTTPS ones; mixing them is 409 protocol_mismatch.

Redirect HTTP to HTTPS

An http listener on port 80 whose default action redirects every request to HTTPS on port 443, keeping the host, path and query:

ezgh lb listeners create lbr_4k2m9x0a7qpe --protocol http --port 80 --redirect-https

An HTTPS listener

An https listener takes a certificate, as a TLS listener does, and speaks HTTP/2 and HTTP/1.1 to clients. Its default action here forwards to one group:

ezgh lb listeners create lbr_4k2m9x0a7qpe --protocol https --port 443 \
  --certificate crt_8s4f2k9d1mzq --forward tgp_7t3n1v8c2wzd

Other default actions are --fixed-response 404 and --redirect-https. --target-group tgp_… alone is the same as --forward tgp_….

Route by host and path

Rules are a JSON list. Each has an optional name, a match and an action:

rules.jsonjson
[
  {
    "name": "api",
    "match": { "hosts": ["api.example.com"] },
    "action": { "type": "forward", "forward": { "targetGroups": [{ "targetGroup": "tgp_3a5s7d9f1ghj" }] } }
  },
  {
    "name": "static",
    "match": { "paths": [{ "type": "prefix", "value": "/static" }] },
    "action": { "type": "forward", "forward": { "targetGroups": [{ "targetGroup": "tgp_9q4w6e8r0tyu" }] } }
  },
  {
    "name": "old-pricing",
    "match": { "paths": [{ "type": "exact", "value": "/pricing.html" }] },
    "action": { "type": "redirect", "redirect": { "path": "/pricing", "statusCode": 301 } }
  }
]
ezgh lb listeners update lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp --rules-file rules.json
ezgh lb listeners rules lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp

--rules-file replaces the whole list. ezgh lb listeners rules … -o json prints a listener’s rules in the same form, to edit and send back.

Conditions

A rule matches when every field it has matches. hosts, paths and methods match when any of their entries does; headers and queryParams match only when all of their entries do. A rule with no fields matches every request. Each field takes at most 5 entries, and a listener at most 100 rules.

Field Matches
hosts The request’s host, ignoring case and port: api.example.com, or *.example.com for any name ending in .example.com (not example.com itself). Lowercase.
paths {"type": "exact", "value": "/healthz"}, or {"type": "prefix", "value": "/api"}, which matches /api and /api/x but not /apix. Starts with /; no spaces, # or ?.
methods Uppercase methods: GET, POST.
headers {"name": "X-Version", "value": "2"}: the exact value; the name ignores case.
queryParams {"name": "beta", "value": "1"}: the exact value, compared decoded (%20 and + are a space).

Actions

type Fields
forward forward.targetGroups: 1 to 5 http groups of the load balancer, each with a weight from 0 to 999. One group may leave out its weight.
redirect redirect.scheme (http or https), host, port and path each replace that part of the URL; a part left out keeps the request’s, and the query is always kept. statusCode is 301, 302 (the default), 307 or 308. At least one part must change.
fixedResponse fixedResponse.statusCode from 200 to 599, contentType text/plain (the default), text/html or application/json, and an optional body of at most 1024 bytes.

Split traffic by weight

To send a share of requests to a new version, forward to two groups with weights. Here the default action sends about 90% of requests to web and 10% to web-canary:

ezgh lb listeners update lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp \
  --forward tgp_7t3n1v8c2wzd=90 --forward tgp_9q4w6e8r0tyu=10

Each request picks a group by weight, so one client’s requests can reach both. A weight of 0 sends a group nothing. In a rule, the same split is a forward with two targetGroups, each with its weight.

Serve several domains on one HTTPS listener

A tls or https listener can hold more certificates beside its default one. Each client gets the certificate whose names match the host it asks for (by SNI); a client that asks for none of them, or sends no name, gets the default. Combine it with host rules to serve several sites from one address:

ezgh lb listeners update lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp \
  --additional-certificate crt_1a2b3c4d5e6f --additional-certificate crt_7g8h9j0k1l2m
  • A listener takes at most 24 additional certificates, each issued in the project and named once.
  • --additional-certificate replaces the list; --no-additional-certificates empties it.
  • Each renews by itself, as the default does.

In the API, they’re the listener’s additionalCertificates.

In the console

On a load balancer’s page, Add listener offers HTTP and HTTPS. An HTTP or HTTPS listener’s second step, Rules, holds its rules in order, each moved with the arrows, and its default action last. The Rules tab lists a listener’s rules, and Edit rules changes them.

API

Listeners are created and changed with CreateListener and UpdateListener. An HTTP or HTTPS listener takes defaultAction (or targetGroup alone, for a forward to it) and rules; its targetGroup reads null unless the default action forwards to exactly one group. A change that names rules replaces the whole list, and honours If-Match with the listener’s ETag (412 precondition_failed when someone changed it first).

Navigation

Type to search…

↑↓ navigate↵ selectEsc close