Route HTTP requests

Route requests to different backend services using paths, methods, headers, and query parameters. This guide extends the HTTPS setup to send matching API requests to api-backend and other requests to web-backend.

Prerequisites

An installed and authenticated evroc CLI, with the project and region selected
The working HTTPS listener, web-route HTTP route, and web-backend service from Create an HTTPS load balancer
A second backend service, api-backend, whose application serves GET /api/status; follow Create the backend pool and service for that application, using a separate pool and naming the service api-backend
A way to distinguish responses from the two applications, such as their response bodies or access logs

Use backend services in the same project and region as the route. Replace web.example.com with your application's hostname and <public-ipv4> with the load balancer's public IPv4 address in the requests below.

Define the routing rules

This example sends a request to api-backend when it meets all four conditions:

The path is /api or starts with /api/
The method is GET
The x-version header is v2
The preview query parameter is true

Other requests go to web-backend through a catch-all rule.

Save the following rules as rules.yaml:

- name: api
  backendServiceRef: api-backend
  matches:
    - path:
        type: PathPrefix
        value: /api
      method: GET
      headers:
        - name: x-version
          value: v2
      queryParams:
        - name: preview
          value: "true"
- name: default
  backendServiceRef: web-backend

Each rule needs a unique name and a backend service reference. Short backend names resolve in the selected project and region; full resource references are also accepted. The CLI accepts JSON as well as YAML rules files.

Fields within one match entry must all match. If a rule contains multiple match entries, a request only needs to satisfy one of them. A rule without matches is a catch-all. Use Exact for a single path or PathPrefix to include paths below it.

Apply the rules

The update replaces the entire rules array, including any existing rules. Hostname restrictions are preserved unless you also supply --hostname. The rules apply to requests for the hostnames already accepted by web-route and its listener.

Apply the rules from the file:

evroc loadbalancer httproute update web-route --rules-file=rules.yaml

Inspect the updated route and wait for its Ready condition to be True:

evroc loadbalancer httproute get web-route -o yaml

Verify matching and fallback requests

For a certificate issued by a private CA, add --cacert with that CA's PEM file to both requests below.

Send a request that satisfies all four conditions:

curl --resolve web.example.com:443:<public-ipv4> \
  --header 'x-version: v2' \
  'https://web.example.com/api/status?preview=true'

Verify that the response or application access logs show that api-backend handled the request.

Repeat the request without the x-version header:

curl --resolve web.example.com:443:<public-ipv4> \
  'https://web.example.com/api/status?preview=true'

Verify that web-backend handled this request through the catch-all rule. It might return a different response, such as 404, if that application doesn't serve /api/status.

Update hostnames or a single-rule backend

Repeat --hostname to match multiple names, or use --hostname= to clear hostname restrictions. Without hostname restrictions, the route matches all hostnames accepted by its listener.

For a route with exactly one rule, --backend-service-ref changes its backend while preserving the rule's name and matches. For a route with multiple rules, such as this example, use --rules-file. You can't combine --rules-file and --backend-service-ref in the same command.

evroc User Documentation