Skip to content

Add documentation for Request Routing in Kmesh (L7 capability) #1469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+93 −0
Open

Add documentation for Request Routing in Kmesh (L7 capability) #1469

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 93 additions & 0 deletions docs/l7/request-routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@

# Request Routing in Kmesh
Copy link
Member

@YaoZengzeng YaoZengzeng Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we already have this doc, ref: https://kmesh.net/docs/application-layer/try-request-routing

Copy link
Contributor Author

@AkarshSahlot AkarshSahlot Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for pointing that out! Yes, I noticed the existing documentation and my PR focuses on testing or demonstrating the process specifically on the macOS platform. I wanted to share my experience to help macOS users better follow the steps.

Copy link
Member

@hzxuzhonghu hzxuzhonghu Aug 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AkarshSahlot If this is for macos, i am not sure kmesh works. If it can work on mac os. Can you please update the install guide rather than for each task


This document explains how to configure HTTP request routing at Layer 7 using Kmesh. Request routing allows you to control how traffic is directed to different backend services based on URL paths.

## Prerequisites

Before starting, you should have:

- A Kubernetes cluster with Istio and Kmesh installed
- Gateway API CRDs applied
- Deployed services, such as httpbin and sleep
- The appropriate label set on your namespace to enable Kmesh

## Use Case: Path-Based Routing

This example routes traffic to two different versions of the httpbin service, depending on the requested URL path.

- Requests to paths beginning with /v1 are sent to httpbin-v1
- Requests to paths beginning with /v2 are sent to httpbin-v2

## Step 1: Deploy Sample Workloads

```bash
kubectl create namespace example
kubectl label namespace example istio.io/dataplane-mode=Kmesh
kubectl apply -n example -f samples/httpbin/httpbin-v1.yaml
kubectl apply -n example -f samples/httpbin/httpbin-v2.yaml
kubectl apply -n example -f samples/sleep/sleep.yaml
```

## Step 2: Define Gateway and Route

Save this configuration as http-route.yaml

```yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
meta
Copy link

@gemini-code-assist gemini-code-assist bot Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

critical

The YAML for the HTTPRoute is invalid. The field meta should be metadata:. With the current configuration, kubectl apply -f http-route.yaml will fail because the resource specification is malformed.

Suggested change
meta
metadata:

name: http-route
namespace: example
spec:
parentRefs:
- name: example-gateway
Comment on lines +43 to +44
Copy link

@gemini-code-assist gemini-code-assist bot Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The example relies on an example-gateway which is not defined in this document. This makes the example incomplete and hard for users to follow. For demonstrating mesh request routing, it's more common and clearer to attach the HTTPRoute to a Service.

I suggest the following changes to make the example self-contained:

  1. In Step 1, create a virtual httpbin service that will act as the parent for the route. You can add instructions to create a file (e.g., httpbin-service.yaml) with the following content and apply it:

    apiVersion: v1
kind: Service
metadata:
  name: httpbin
  namespace: example
spec:
  ports:
  - port: 8000
    name: http
  selector:
    # This service has no pods, it's just a handle for the HTTPRoute.
    app: non-existent

  2. In Step 2, update the HTTPRoute to reference this new service as its parent, as suggested below.

Suggested change
parentRefs:
- name: example-gateway
parentRefs:
- name: httpbin
kind: Service
port: 8000

rules:
- matches:
- path:
type: PathPrefix
value: /v1
backendRefs:
- name: httpbin-v1
port: 8000
- matches:
- path:
type: PathPrefix
value: /v2
backendRefs:
- name: httpbin-v2
port: 8000
```

Apply the configuration:

```bash
kubectl apply -f http-route.yaml
```

## Step 3: Verify Routing

Open a shell in the sleep pod

```bash
kubectl -n example exec deploy/sleep -- bash
```

From within the pod, run

```bash
curl http://httpbin.example.svc.cluster.local:8000/v1/status/200
curl http://httpbin.example.svc.cluster.local:8000/v2/status/200
```

You should see that the path for /v1 gets a response from httpbin-v1 and /v2 gets a response from httpbin-v2.

## Notes and Limitations

Header-based and regex path matching may require further validation. These instructions assume the example-gateway resource is present and working as expected.
Copy link

@gemini-code-assist gemini-code-assist bot Aug 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Following the suggestion to use a Service as the parentRef for the HTTPRoute, this line assuming an example-gateway is no longer necessary and could cause confusion. It should be removed.


## Related References

Kmesh issue <https://github.com/kmesh-net/kmesh/issues/600>

Istio Request Routing: <https://istio.io/latest/docs/tasks/traffic-management/request-routing>