Targeting MeshHTTPRoutes in supported policies

Uses: Kong Mesh
Related Documentation
Incompatible with
on-prem

Use MeshHTTPRoute as a target in supported policies like MeshTimeout, MeshAccessLog, and MeshRetry to apply fine-grained traffic control to specific HTTP methods and paths instead of entire services.

Prerequisites

Complete the Kubernetes quickstart and deploy the demo application with mTLS enabled:

helm upgrade --install --create-namespace --namespace kuma-system kuma kuma/kuma

kubectl wait -n kuma-system --for=condition=ready pod --selector=app=kuma-control-plane --timeout=90s

kubectl apply -f https://bit.ly/kuma-demo-mtls

kubectl wait -n kuma-demo --for=condition=ready pod --selector=app=demo-app --timeout=90s

kubectl port-forward svc/demo-app -n kuma-demo 5050:5050 &
Copied to clipboard!

Verify the demo app is running:

curl -XPOST localhost:5050/api/counter
Copied to clipboard!

Expected output:

{"counter":1,"zone":""}
Copied to clipboard!

Apply a MeshTimeout policy

Limit request duration from demo-app to kv to 1 second:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
  name: demo-app-to-kv-meshservice
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
    - targetRef:
        kind: MeshService
        name: kv
      default:
        http:
          requestTimeout: 1s
EOF
Copied to clipboard!

Then simulate a delay with a MeshHTTPRoute:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: demo-app-kv-api
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
    - targetRef:
        kind: MeshService
        name: kv
      rules:
        - matches:
            - path:
                type: Exact
                value: "/api/key-value/counter"
              method: POST
          default:
            filters:
              - type: RequestHeaderModifier
                requestHeaderModifier:
                  set:
                    - name: x-set-response-delay-ms
                      value: "2000"
EOF
Copied to clipboard!

Call the endpoint again:

curl -XPOST localhost:5050/api/counter
Copied to clipboard!

You should receive a timeout response:

{"instance":"...","status":504,"title":"failed sending request","type":"..."}
Copied to clipboard!

Update timeout for MeshHTTPRoute

Apply a new timeout for the route:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
  name: demo-app-kv-api-meshhttproute
  namespace: kuma-demo
spec:
  to:
    - targetRef:
        kind: MeshHTTPRoute
        name: demo-app-kv-api
      default:
        http:
          requestTimeout: 3s
EOF
Copied to clipboard!

Re-run the request:

curl -XPOST localhost:5050/api/counter
Copied to clipboard!

This time the request should succeed after a delay:

{"counter":3,"zone":""}
Copied to clipboard!

Clean up

Remove timeouts and delay:

kubectl delete meshtimeout demo-app-to-kv-meshservice -n kuma-demo
kubectl delete meshtimeout demo-app-kv-api-meshhttproute -n kuma-demo
Copied to clipboard!

Reset the route:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: demo-app-kv-api
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
    - targetRef:
        kind: MeshService
        name: kv
      rules:
        - default: {}
          matches:
            - path:
                type: Exact
                value: "/api/key-value/counter"
              method: POST
EOF
Copied to clipboard!

Log traffic with MeshAccessLog

Create an access log policy targeting the route:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshAccessLog
metadata:
  name: demo-app-kv-api
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
    - targetRef:
        kind: MeshHTTPRoute
        name: demo-app-kv-api
      default:
        backends:
          - type: File
            file:
              path: "/dev/stdout"
EOF
Copied to clipboard!

Trigger the route:

curl -XPOST localhost:5050/api/counter
Copied to clipboard!

Check logs:

kubectl logs -n kuma-demo -l app=demo-app -c kuma-sidecar
Copied to clipboard!

Apply a MeshRetry policy

Remove the default retry policy:

kubectl delete meshretry mesh-retry-all-default -n kuma-system
Copied to clipboard!

Inject faults:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshFaultInjection
metadata:
  name: kv-503
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: kv
  from:
    - targetRef:
        kind: Mesh
      default:
        http:
          - abort:
              httpStatus: 503
              percentage: 50
EOF
Copied to clipboard!

Create a retry policy for the route:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshRetry
metadata:
  name: demo-app-kv-http
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
    - targetRef:
        kind: MeshHTTPRoute
        name: demo-app-kv-api
      default:
        http:
          numRetries: 10
          retryOn:
            - "503"
EOF
Copied to clipboard!

Add a broader retry for all traffic to kv:

cat <<EOF | kubectl apply -f -
apiVersion: kuma.io/v1alpha1
kind: MeshRetry
metadata:
  name: demo-app-kv
  namespace: kuma-demo
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: demo-app
  to:
    - targetRef:
        kind: MeshService
        name: kv
      default:
        http:
          numRetries: 10
          retryOn:
            - 5xx
EOF
Copied to clipboard!

What you’ve learned

  • Apply MeshTimeout policies targeting MeshHTTPRoute
  • Use MeshAccessLog to log only matching traffic
  • Create MeshRetry policies scoped to MeshHTTPRoute and MeshService
  • Combine policies for precise traffic control

Next steps

  • Learn more about MeshHTTPRoute
  • Combine policies like MeshFaultInjection, MeshRetry, and MeshTimeout
  • Explore MeshCircuitBreaker and MeshRateLimit with MeshHTTPRoute targeting

Did this doc help?

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!