Redirects and rewrites

Configure HTTP redirects and URL rewrites in ambient mesh using HTTPRoute rules at a gateway or waypoint proxy.

HTTP redirects return a 3xx response that instructs the client to send the request to a new URL. URL rewrites modify components of a request, such as the path or hostname, before forwarding it to the destination. Both are configured using filter rules in an HTTPRoute at a gateway or waypoint proxy. In this guide, you configure a redirect that returns a 302 response for a specific path, then replace it with a rewrite that modifies the path before forwarding the request.

Before you begin

Install an ambient mesh.

Add the default namespace to the ambient mesh.

kubectl label namespace default istio.io/dataplane-mode=ambient

Deploy a waypoint proxy in the default namespace. The HTTPRoute in this guide attaches to a Service as a parentRef, which requires a waypoint to enforce L7 rules.
```
istioctl waypoint apply --enroll-namespace --wait
```

Deploy sample apps

Deploy the following sample services to your cluster.

Deploy the httpbin deployment to respond to test requests.

kubectl create -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
      version: v1
  template:
    metadata:
      labels:
        app: httpbin
        version: v1
    spec:
      containers:
      - image: docker.io/kennethreitz/httpbin
        imagePullPolicy: IfNotPresent
        name: httpbin
        command: ["gunicorn", "--access-logfile", "-", "-b", "0.0.0.0:80", "httpbin:app"]
        ports:
        - containerPort: 80
EOF

Deploy the httpbin service.

kubectl create -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: httpbin
  labels:
    app: httpbin
spec:
  ports:
  - name: http
    port: 8000
    targetPort: 80
  selector:
    app: httpbin
EOF

Deploy a curl client to send test requests.

kubectl create -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: curl
spec:
  replicas: 1
  selector:
    matchLabels:
      app: curl
  template:
    metadata:
      labels:
        app: curl
    spec:
      containers:
      - name: curl
        image: curlimages/curl
        command: ["/bin/sleep","3650d"]
        imagePullPolicy: IfNotPresent
EOF

Configure a redirect

Use an HTTPRoute to return HTTP redirect (3xx) responses to a client.

Send a baseline request to confirm the current URL.

kubectl exec deploy/curl -- curl -sSI http://httpbin:8000/anything/old-url

Example output:

{
  "url": "http://httpbin:8000/anything/old-url"
}

Create an HTTPRoute with a RequestRedirect filter that rewrites /anything/old-url to /anything/new-url. This route has two rules. When a route is bound to a service, it replaces the mesh’s default pass-through behavior for that service. Without the second rule’s backendRef, any request that did not match the PathPrefix would return 404. The first rule does not need a backendRef because a redirect is a terminal action.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-redirect
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: httpbin
    port: 8000
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /anything/old-url
      filters:
        - type: RequestRedirect
          requestRedirect:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /anything/new-url
            statusCode: 302
    - backendRefs:
      - name: httpbin
        port: 8000
EOF

Test the redirect.

kubectl exec deploy/curl -- curl -sSI http://httpbin:8000/anything/old-url

Example output:

HTTP/1.1 302 Found
location: http://httpbin:8000/anything/new-url
date: Tue, 29 Oct 2024 23:51:35 GMT
server: istio-envoy
x-envoy-decorator-operation: http-filter-redirect-0-istio-autogenerated-k8s-gateway:8000/*
transfer-encoding: chunked

Delete the route before configuring the rewrite in the next section.
```
kubectl delete httproute http-filter-redirect
```

Configure a rewrite

Use an HTTPRoute to rewrite components of a request before it is forwarded to its destination.

Create an HTTPRoute with a URLRewrite filter that rewrites /anything/old-url to /anything/new-url.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-rewrite
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: httpbin
    port: 8000
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /anything/old-url
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: httpbin
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /anything/new-url
      backendRefs:
        - name: httpbin
          port: 8000
    - backendRefs:
      - name: httpbin
        port: 8000
EOF

Test the rewrite. Requests to any path other than /anything/old-url pass through unchanged.

kubectl exec deploy/curl -- curl -sSi http://httpbin:8000/anything/unchanged/

Example output:

{
  "url": "http://httpbin:8000/anything/unchanged/"
}

Requests to /anything/old-url are rewritten to /anything/new-url. Note both the rewritten URL and the X-Envoy-Original-Path header, which preserves the original path.

kubectl exec deploy/curl -- curl -sSi http://httpbin:8000/anything/old-url/

Example output:

{
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin", 
    "User-Agent": "curl/8.7.1", 
    "X-Envoy-Original-Path": "/anything/old-url/"
  }, 
  "url": "http://httpbin/anything/new-url/"
}

Cleanup

Delete the sample resources.

kubectl delete httproute http-filter-redirect http-filter-rewrite
kubectl delete deploy httpbin curl
kubectl delete svc httpbin

Mirroring