Path matching

This document describes how F5 NGINX Ingress Controller translates VirtualServer and VirtualServerRoute route paths into NGINX location directives, with a focus on the longest prefix match (^~) modifier.

Overview

Each route in a VirtualServer or subroute in a VirtualServerRoute has a path field that maps directly to an NGINX location directive. NGINX Ingress Controller supports five path matching types, each with different syntax and priority behavior. Understanding these types, especially the longest prefix match, allows you to control exactly which location block handles a given request.

Matching types and priority

The following table lists all five supported path types in order of priority from highest to lowest:

When NGINX receives a request, it evaluates locations in the following order:

1. Exact match (=): If the URI matches an exact location, NGINX uses it immediately and stops searching.
2. Prefix scan: NGINX scans all prefix locations (both ^~ and plain /) and remembers the longest match.
3. Longest prefix match (^~): If the longest matching prefix location has the ^~ modifier, NGINX uses it immediately and skips all regex evaluation.
4. Regex evaluation (~ and ~*): NGINX checks regex locations in the order they appear in the configuration. The first matching regex wins.
5. Prefix fallback: If no regex matches, NGINX uses the longest matching prefix location from step 2.

Longest prefix match (^~)

The ^~ modifier gives a prefix location higher priority than regex locations. When a request URI matches a ^~ location, NGINX uses that location immediately and does not evaluate any regular expression locations, even if a regex would also match.

This is useful when you want to serve a specific path prefix with certainty, regardless of any regex patterns that might also match.

When to use longest prefix match

Use ^~ when:

• You need to guarantee that a specific path prefix is always handled by a particular upstream or action, even if regex locations exist that could match the same URI.
• You are serving static assets from a known path (such as /images/static/ or /assets/) and want to prevent regex patterns (such as ~ \.jpg$) from intercepting those requests.

Path syntax rules

A longest prefix match path must follow these rules:

• The path must start with ^~ followed by a valid URI path starting with /.
• Optional whitespace between ^~ and the path is allowed (for example, ^~ /images/ and ^~/images/ are equivalent).
• The URI portion must not contain whitespace, {, }, ;, or \ characters.
• The URI portion must not contain .. path segments.

How it differs from a regular prefix match

The only difference is that ^~ prevents regex locations from overriding the match.

VirtualServer example

The following VirtualServer defines routes using several path types, including the longest prefix match:

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: path-matching
spec:
  host: path-matching.example.com
  upstreams:
  - name: static-backend
    service: static-svc
    port: 80
  - name: images-backend
    service: images-svc
    port: 80
  - name: app-backend
    service: app-svc
    port: 80
  routes:
  - path: "=/images/logo.jpg"
    action:
      pass: static-backend
  - path: "^~/images/static/"
    action:
      pass: static-backend
  - path: "~ \\.jpg$"
    action:
      pass: images-backend
  - path: /images/
    action:
      pass: app-backend

This configuration produces the following NGINX location blocks:

location = /images/logo.jpg {
    # Exact match - highest priority
    ...
}

location ^~ /images/static/ {
    # Longest prefix match - blocks regex evaluation
    ...
}

location ~ "\.jpg$" {
    # Case-sensitive regex
    ...
}

location /images/ {
    # Regular prefix - lowest priority
    ...
}

With this configuration:

VirtualServerRoute subroutes with longest prefix match

When a VirtualServer route delegates to a VirtualServerRoute using the route or routeSelector field, the parent route’s path acts as a constraint on subroute paths. For a ^~ parent path, each subroute must also use the ^~ modifier.

VirtualServer with delegation

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: path-matching-vsr
spec:
  host: path-matching-vsr.example.com
  routes:
  - path: "^~/static/"
    route: static-routes

VirtualServerRoute with ^~ subroutes

apiVersion: k8s.nginx.org/v1
kind: VirtualServerRoute
metadata:
  name: static-routes
spec:
  host: path-matching-vsr.example.com
  subroutes:
  - path: "^~/static/css/"
    action:
      pass: css-backend
  - path: "^~/static/js/"
    action:
      pass: js-backend

This produces two NGINX location blocks:

location ^~ /static/css/ {
    ...
}

location ^~ /static/js/ {
    ...
}

Important

The parent route’s path (^~/static/) does not create an NGINX location block. Only the subroute paths become NGINX locations. If a request matches the parent prefix but not any subroute (for example, /static/fonts/bold.woff), no location handles it and NGINX returns a 404 response.

Subroute path constraints

When a VirtualServer route delegates to a VirtualServerRoute, the subroute paths must follow constraints based on the parent route’s path type:

For longest prefix parent paths, a plain prefix subroute like /static/css/ is rejected because the validation requires that the subroute path string starts with ^~/static/. The ^~ modifier must be present on every subroute.

See also

• VirtualServer and VirtualServerRoute resources for the full CRD field reference.
• NGINX location directive documentation for the upstream NGINX matching algorithm.
• NGINX location priority for a detailed explanation of NGINX’s location evaluation order.
• Ingress path matching using path-regex annotation for configuring regex path matching with Ingress resources.
• Path matching examples on GitHub for runnable examples of all five path types.