Skip to content
Help guide the future of agentgateway — Take the survey

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

Path

Verified : Automated tests passed for: Kubernetes resources: The Kubernetes resources on this page were checked against their API schemas. End-to-end run: Every step ran in a fresh test environment and the results were checked.
Page as Markdown

Match requests by path using exact, prefix, or regex patterns.

Match the targeted path of an incoming request against specific path criteria.

For more information, see the Kubernetes Gateway API documentation.

Before you begin

  1. Set up an agentgateway proxy.
  2. Install the httpbin sample app.

Set up exact matching

  1. Create an HTTPRoute resource for the match.example domain that matches incoming requests on the /status/200 exact path.

    kubectl apply -f- <<EOF
    apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: httpbin-match
      namespace: httpbin
    spec:
      parentRefs:
        - name: agentgateway-proxy
          namespace: agentgateway-system
      hostnames:
        - match.example
      rules:
        - matches:
          - path:
              type: Exact
              value: /status/200
          backendRefs:
            - name: httpbin
              port: 8000
    EOF
  2. Send a request to the /status/200 path of the httpbin app on the match.example domain. Verify that you get back a 200 HTTP response code.

    curl -vi http://$INGRESS_GW_ADDRESS:80/status/200 -H "host: match.example"

    Example output:

    * Request completely sent off
    < HTTP/1.1 200 OK
    HTTP/1.1 200 OK
     access-control-allow-credentials: true
    access-control-allow-credentials: true
    < access-control-allow-origin: *
    access-control-allow-origin: *
    < content-length: 0
    content-length: 0
  3. Send another request to the httpbin app. This time, use the /headers path. Because this path is not specified in the HTTPRoute, the request fails and a 404 HTTP response code is returned.

    curl -vi http://$INGRESS_GW_ADDRESS:80/headers -H "host: match.example"

    Example output:

    < HTTP/1.1 404 Not Found
    HTTP/1.1 404 Not Found
    < content-length: 9
    content-length: 9
    < content-type: text/plain; charset=utf-8
    content-type: text/plain; charset=utf-8

Set up prefix path matching

  1. Create an HTTPRoute resource for the match.example domain that matches incoming requests on the /anything prefix path.

    kubectl apply -f- <<EOF
    apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: httpbin-match
      namespace: httpbin
    spec:
      parentRefs:
        - name: agentgateway-proxy
          namespace: agentgateway-system
      hostnames:
        - match.example
      rules:
        - matches:
          - path:
              type: PathPrefix
              value: /anything
          backendRefs:
            - name: httpbin
              port: 8000
    EOF
  2. Send a request to the /anything/team1 path of the httpbin app on the match.example domain. Verify that you get back a 200 HTTP response code.

    curl -vi http://$INGRESS_GW_ADDRESS:80/anything/team1 -H "host: match.example"

    Example output:

    < HTTP/1.1 200 OK
    HTTP/1.1 200 OK
    < access-control-allow-credentials: true
    access-control-allow-credentials: true
    < access-control-allow-origin: *
    access-control-allow-origin: *
    < content-type: application/json; encoding=utf-8
    content-type: application/json; encoding=utf-8
    < content-length: 304
    content-length: 304
    < 
    
    {
      "args": {},
      "headers": {
        "Accept": [
          "*/*"
        ],
        "Host": [
          "match.example"
        ],
        "User-Agent": [
          "curl/8.7.1"
        ]
      },
      "origin": "10.xxx.x.xx:35204",
      "url": "http://match.example/anything/team1",
      "data": "",
      "files": null,
      "form": null,
      "json": null
    }
  3. Send another request to the httpbin app. This time, use the /headers path. Because this path is not specified in the HTTPRoute, the request fails and a 404 HTTP response code is returned.

    curl -vi http://$INGRESS_GW_ADDRESS:80/headers -H "host: match.example"

    Example output:

    < HTTP/1.1 404 Not Found
    HTTP/1.1 404 Not Found
    < content-length: 9
    content-length: 9
    < content-type: text/plain; charset=utf-8
    content-type: text/plain; charset=utf-8

Set up regex matching

Use RE2 syntax for regular expressions to match incoming requests.

  1. Create an HTTPRoute resource for the match.example domain that uses a regular expression (regex) to match incoming requests. The following regex patterns are defined in the example:

    • /.*my-path.*:
      • The request path must start with /.
      • The expression .* means that any character before and after the my-path string is allowed.
      • Allowed pattern: /anything/this-is-my-path-1, not allowed: /anything.
    • /anything/stores/[^/]+?/entities:
      • The request path must start with /anything/stores/.
      • [^/]+? matches any character except /.
      • The request path must end with /entities.
      • Allowed pattern: /anything/stores/us/entities, not allowed: /anything/stores/us/south/entities.
    • /anything/(dogs|cats)/\\d[.]\\d.*
      • The request path must start with /anything/, followed by either dogs/ or cats/.
      • \\d matches a single digit.
      • [.] matches a literal period.
      • \\d.* matches a single digit followed by zero or any character.
      • Allowed pattern: /anything/dogs/3.0-game, not allowed: /anything/birds
    kubectl apply -f- <<EOF
    apiVersion: gateway.networking.k8s.io/v1beta1
    kind: HTTPRoute
    metadata:
      name: httpbin-match
      namespace: httpbin
    spec:
      parentRefs:
        - name: agentgateway-proxy
          namespace: agentgateway-system
      hostnames:
        - "match.example"
      rules:
        - matches:  
          - path:
              type: RegularExpression
              value: /.*my-path.*
          - path:
              type: RegularExpression
              value: /anything/stores/[^/]+?/entities
          - path:
              type: RegularExpression
              value: /anything/(dogs|cats)/\\d[.]\\d.*
          backendRefs:
          - name: httpbin
            namespace: httpbin
            port: 8000
    EOF
  2. Send multiple requests to the httpbin app on the match.example domain.

    • /anything/this-is-my-path-1 matches the regex pattern \/.*my-path.*
    • /anything/stores/us/entities matches the regex pattern /anything/stores/[^/]+?/entities
    • /anything/dogs/3.0-game matches the regex pattern /anything/(dogs|cats)/\\d[.]\\d.*

    Verify that the requests succeed and that you get back a 200 HTTP response code.

    curl -vi http://$INGRESS_GW_ADDRESS:80/anything/this-is-my-path-1 -H "host: match.example"
    curl -vi http://$INGRESS_GW_ADDRESS:80/anything/stores/us/entities -H "host: match.example"
    curl -vi http://$INGRESS_GW_ADDRESS:80/anything/dogs/3.0-game -H "host: match.example"

    Example output:

    < HTTP/1.1 200 OK
    HTTP/1.1 200 OK
    < access-control-allow-credentials: true
    access-control-allow-credentials: true
    < access-control-allow-origin: *
    access-control-allow-origin: *
    < content-type: application/json; encoding=utf-8
    content-type: application/json; encoding=utf-8
    < content-length: 317
    content-length: 317
    < 
    
    {
      "args": {},
      "headers": {
       "Accept": [
             "*/*"
        ],
        "Host": [
         "match.example"
        ],
        "User-Agent": [
          "curl/8.7.1"
        ]
      },
      "origin": "10.xxx.x.xx:43182",
      "url": "http://match.example/anything/stores/us/entities",
      "data": "",
      "files": null,
      "form": null,
      "json": null
    }
  3. Send requests to the httpbin app that do not meet the defined regex patterns.

    • /anything does not match the regex pattern \/.*my-path.*
    • /anything/stores/us/south/entities does not match the regex pattern `/anything/stores/[^/]+?/
    • /anything/birds/1.1-game does not match the regex pattern /anything/(dogs|cats)/\\d[.]\\d.*

    Verify that all requests fail with a 404 HTTP response code, because the path does not match the regex pattern that you defined.

    curl -vi http://$INGRESS_GW_ADDRESS:80/anything -H "host: match.example"
    curl -vi http://$INGRESS_GW_ADDRESS:80/anything/stores/us/south/entities -H "host: match.example"
    curl -vi http://$INGRESS_GW_ADDRESS:80/anything/birds/1.1-game -H "host: match.example"

    Example output:

    < HTTP/1.1 404 Not Found
    HTTP/1.1 404 Not Found
    < content-length: 9
    content-length: 9
    < content-type: text/plain; charset=utf-8
    content-type: text/plain; charset=utf-8

Optional: Normalize paths before matching

By default, path matching uses the request path as agentgateway receives it. Use an AgentgatewayPolicy to normalize request paths before route matching, policy evaluation, and forwarding to the backend. The policy applies to every route on the Gateway. For all normalization rules, the order in which they run, and the paths that they reject, see Path normalization. The following steps use the httpbin-match HTTPRoute from Set up regex matching.

  1. Send a request to the /anything//stores/./us/entities path. This path contains a repeated slash and a . segment. The --path-as-is option stops curl from resolving the . segment before curl sends the request. Verify that you get back a 404 HTTP response code, because the path does not match the /anything/stores/[^/]+?/entities regex pattern.

    curl -vi --path-as-is http://$INGRESS_GW_ADDRESS:80/anything//stores/./us/entities -H "host: match.example"

    Example output:

    > GET /anything//stores/./us/entities HTTP/1.1
    ...
    < HTTP/1.1 404 Not Found
    HTTP/1.1 404 Not Found
    < content-type: text/plain
    content-type: text/plain
    < content-length: 15
    content-length: 15
    <
    route not found
  2. Create a policy that normalizes repeated slashes, dot segments, and percent-encoded unreserved characters for all routes on the agentgateway-proxy Gateway.

    kubectl apply -f- <<EOF
    apiVersion: agentgateway.dev/v1alpha1
    kind: AgentgatewayPolicy
    metadata:
      name: normalize-paths
      namespace: agentgateway-system
    spec:
      targetRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: agentgateway-proxy
      frontend:
        http:
          normalize:
          - MergeSlash
          - DotSegment
          - DecodeUnreserved
    EOF
    FieldDescription
    spec.frontend.http.normalizeThe normalization rules to apply. MergeSlash collapses repeated slashes, DotSegment resolves . and .. segments, and DecodeUnreserved decodes percent-encoded unreserved characters. The DotSegment and DecodeUnreserved rules also reject a path with malformed percent-encoding or %00.
  3. Send the same request again. Verify that you get back a 200 HTTP response code. The url field in the response body shows the normalized /anything/stores/us/entities path that the httpbin app received.

    curl -vi --path-as-is http://$INGRESS_GW_ADDRESS:80/anything//stores/./us/entities -H "host: match.example"

    Example output:

    > GET /anything//stores/./us/entities HTTP/1.1
    ...
    < HTTP/1.1 200 OK
    HTTP/1.1 200 OK
    < Access-Control-Allow-Credentials: true
    Access-Control-Allow-Credentials: true
    < Access-Control-Allow-Origin: *
    Access-Control-Allow-Origin: *
    < Content-Type: application/json; encoding=utf-8
    Content-Type: application/json; encoding=utf-8
    < Content-Length: 316
    Content-Length: 316
    <
    
    {
      "args": {},
      "headers": {
        "Accept": [
          "*/*"
        ],
        "Host": [
          "match.example"
        ],
        "User-Agent": [
          "curl/8.7.1"
        ]
      },
      "origin": "10.244.0.7:43306",
      "url": "http://match.example/anything/stores/us/entities",
      "data": "",
      "files": null,
      "form": null,
      "json": null
    }
  4. Send a request with an escaped NUL character (%00) in the path. Verify that you get back a 400 HTTP response code, because the DotSegment and DecodeUnreserved rules reject %00.

    curl -vi --path-as-is http://$INGRESS_GW_ADDRESS:80/anything/stores/us%00/entities -H "host: match.example"

    Example output:

    > GET /anything/stores/us%00/entities HTTP/1.1
    ...
    < HTTP/1.1 400 Bad Request
    HTTP/1.1 400 Bad Request
    < content-type: text/plain
    content-type: text/plain
    < content-length: 15
    content-length: 15
    <
    invalid request

Cleanup

You can remove the resources that you created in this guide.
kubectl delete AgentgatewayPolicy normalize-paths -n agentgateway-system --ignore-not-found
kubectl delete httproute httpbin-match -n httpbin --ignore-not-found
Was this page helpful?
Agentgateway assistant

Ask me anything about agentgateway configuration, features, or usage.

Note: AI-generated content might contain errors; please verify and test all returned information.

Tip: one topic per conversation gives the best results. Use the + button in the chat header to start a new conversation.

Switching topics? Starting a new conversation improves accuracy.
↑↓ navigate ↵ select esc dismiss

What could be improved?

Your feedback helps us improve assistant answers and identify docs gaps we should fix.

Need more help? Join us on Discord: https://discord.gg/y9efgEmppm

Want to use your own agent? Add the Solo MCP server to query our docs directly. Get started here: https://search.solo.io/.