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.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
- Set up an agentgateway proxy.
- Install the httpbin sample app.
Set up exact matching
Create an HTTPRoute resource for the
match.exampledomain that matches incoming requests on the/status/200exact 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 EOFSend a request to the
/status/200path of the httpbin app on thematch.exampledomain. 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: 0Send another request to the httpbin app. This time, use the
/headerspath. 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
Create an HTTPRoute resource for the
match.exampledomain that matches incoming requests on the/anythingprefix 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 EOFSend a request to the
/anything/team1path of the httpbin app on thematch.exampledomain. 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 }Send another request to the httpbin app. This time, use the
/headerspath. 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.
Create an HTTPRoute resource for the
match.exampledomain 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 themy-pathstring is allowed. - Allowed pattern:
/anything/this-is-my-path-1, not allowed:/anything.
- The request path must start with
/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.
- The request path must start with
/anything/(dogs|cats)/\\d[.]\\d.*- The request path must start with
/anything/, followed by eitherdogs/orcats/. \\dmatches 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
- The request path must start with
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 EOFSend multiple requests to the httpbin app on the
match.exampledomain./anything/this-is-my-path-1matches the regex pattern\/.*my-path.*/anything/stores/us/entitiesmatches the regex pattern/anything/stores/[^/]+?/entities/anything/dogs/3.0-gamematches 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 }Send requests to the httpbin app that do not meet the defined regex patterns.
/anythingdoes not match the regex pattern\/.*my-path.*/anything/stores/us/south/entitiesdoes not match the regex pattern `/anything/stores/[^/]+?//anything/birds/1.1-gamedoes 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.
Send a request to the
/anything//stores/./us/entitiespath. This path contains a repeated slash and a.segment. The--path-as-isoption 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/[^/]+?/entitiesregex 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 foundCreate a policy that normalizes repeated slashes, dot segments, and percent-encoded unreserved characters for all routes on the
agentgateway-proxyGateway.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 EOFField Description spec.frontend.http.normalizeThe normalization rules to apply. MergeSlashcollapses repeated slashes,DotSegmentresolves.and..segments, andDecodeUnreserveddecodes percent-encoded unreserved characters. TheDotSegmentandDecodeUnreservedrules also reject a path with malformed percent-encoding or%00.Send the same request again. Verify that you get back a 200 HTTP response code. The
urlfield in the response body shows the normalized/anything/stores/us/entitiespath 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 }Send a request with an escaped NUL character (
%00) in the path. Verify that you get back a 400 HTTP response code, because theDotSegmentandDecodeUnreservedrules 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