For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Request matching

Based on the route schema (see the configuration reference for the full field reference and schema validation for IDE integration), you can configure the following matchingMatchingThe process of determining which route should handle an incoming request based on criteria such as path, hostname, headers, query parameters, or HTTP methods. conditions for HTTP or TCP routes.

HTTP routes

For routes configured with HTTP or HTTPS listeners, you can configure the following matching conditions. These matching conditions do not apply to TLS listeners, which use TCP routes and only support hostname-based matching.

Path matching

Match incoming requests based on their path using one of the following strategies.

If no path match is specified, the default is to match all paths (/).

routes:
- name: api-exact
  matches:
  - path:
      exact: "/api/v1/users"
    backends:
    - host: api.example.com:8080

routes:
- name: api-prefix
  matches:
  - path:
      pathPrefix: "/api/v1"
    backends:
    - host: api.example.com:8080

routes:
- name: api-regex
  matches:
  - path:
      regex: ["^/api/v[0-9]+/users$", 0]
    backends:
    - host: api.example.com:8080

Header matching

Match incoming requests based on HTTP headers included in the request.

• Exact match:
  { "name": "Authorization", "value": { "exact": "Bearer token" } }
• Regex match:
  { "name": "Authorization", "value": { "regex": "^Bearer .*" } }

routes:
- name: auth-exact
  matches:
  - path:
      pathPrefix: "/api"
    headers:
    - name: "Authorization"
      value:
        exact: "Bearer abc123token"
    backends:
    - host: api.example.com:8080

routes:
- name: auth-regex
  matches:
  - path:
      pathPrefix: "/api"
    headers:
    - name: "Authorization"
      value:
        regex: "^Bearer .*"
    backends:
    - host: api.example.com:8080

routes:
- name: multi-header
  matches:
  - path:
      pathPrefix: "/api"
    headers:
    - name: "Authorization"
      value:
        regex: "^Bearer .*"
    - name: "Content-Type"
      value:
        exact: "application/json"
    backends:
    - host: api.example.com:8080

Method matching

Optionally restrict matches to specific HTTP methods.

{ "method": { "method": "GET" } }

routes:
- name: get-only
  matches:
  - path:
      pathPrefix: "/api"
    method: "GET"
    backends:
    - host: api.example.com:8080

routes:
- name: post-only
  matches:
  - path:
      pathPrefix: "/api/users"
    method: "POST"
    backends:
    - host: api.example.com:8080

routes:
- name: read-operations
  matches:
  - path:
      pathPrefix: "/api/users"
    method: "GET"
    backends:
    - host: read-api.example.com:8080
- name: write-operations
  matches:
  - path:
      pathPrefix: "/api/users"
    method: "POST"
    backends:
    - host: write-api.example.com:8080

Query parameter matching

Match on query parameters, either by exact value or regex.

• Exact:
  { "name": "version", "value": { "exact": "v1" } }
• Regex:
  { "name": "version", "value": { "regex": "^v[0-9]+$" } }

routes:
- name: version-exact
  matches:
  - path:
      pathPrefix: "/api"
    query:
    - name: "version"
      value:
        exact: "v1"
    backends:
    - host: api-v1.example.com:8080

routes:
- name: version-regex
  matches:
  - path:
      pathPrefix: "/api"
    query:
    - name: "version"
      value:
        regex: "^v[0-9]+$"
    backends:
    - host: api.example.com:8080

routes:
- name: multi-query
  matches:
  - path:
      pathPrefix: "/api"
    query:
    - name: "version"
      value:
        exact: "v1"
    - name: "format"
      value:
        regex: "^(json|xml)$"
    backends:
    - host: api.example.com:8080

Combined matching

You can combine multiple matching conditions to create a more specific route, such as the following example.

routes:
- name: comprehensive-match
  matches:
  - path:
      pathPrefix: "/api/v1"
    method: "GET"
    headers:
    - name: "Authorization"
      value:
        regex: "^Bearer .*"
    query:
    - name: "format"
      value:
        exact: "json"
    backends:
    - host: api.example.com:8080

TCP routes

For routes configured with TCP listeners, you can configure the following matching conditions.

Hostname matching

Match incoming requests based on the hostname included in the request. This is primarily used for TLS termination scenarios.

tcpRoutes:
- name: database-backend
  hostnames:
  - "db.example.com"
  backends:
  - host: postgres.example.com:5432

Backend routing

Route directly to backends. You can include multiple backends and weights to load balance across them.

Higher weights receive more traffic. Each new TCP connection is assigned to a backend proportionally based on the ratio of the weights.

In the following example, traffic is load balanced across the three backends in the ratio 1:2:1. The first backend receives 25% of the traffic, the second backend receives 50% of the traffic, and the third backend receives 25% of the traffic.

If no weight is specified, the default is 1. Backends with a weight of 0 receive no traffic. Each incoming TCP connection maintains a 1:1 mapping with an outgoing backend connection; once a connection is established, it remains bound to its assigned backend for the lifetime of that connection.

tcpRoutes:
- name: redis-cluster
  backends:
  - host: redis-1.example.com:6379
    weight: 1
  - host: redis-2.example.com:6379
    weight: 2
  - host: redis-3.example.com:6379
    weight: 1