Your Gateway is listening. Envoy proxies are running. External traffic can reach the cluster. But right now, every request goes to the same place. In production, you need sophisticated routing: API version 2 requests go to the new service, beta users get experimental features, 10% of traffic tests the canary deployment.
HTTPRoute is where the real routing logic lives. The Gateway defines the entry point. HTTPRoute defines what happens next—matching requests by path, headers, query parameters, or HTTP method, then directing them to the right backend.
This lesson covers the complete HTTPRoute matching vocabulary. By the end, you will route traffic based on any request characteristic and implement canary deployment patterns using traffic weights.
Path matching is the most common routing pattern. Gateway API provides three match types, each serving different use cases.
Exact matches the path exactly—character for character. No trailing slash tolerance, no prefix matching.
Test the route:
Output:
When to use Exact: Health check endpoints, specific API actions, webhooks that must match precisely.
PathPrefix matches any path starting with the specified prefix. This is the most common match type.
Test the route:
Output:
When to use PathPrefix: Routing entire API versions to a service, namespace-based routing, catch-all patterns.
RegularExpression provides maximum flexibility using RE2 syntax.
Test the route:
Output:
When to use RegularExpression: Version-flexible routing, complex patterns, user ID extraction. Use sparingly—regex matching has performance overhead.
Route requests based on HTTP headers. This enables API versioning, beta features, and premium user routing without changing URLs.
Test the routes:
Output:
Match headers using patterns:
Test the routes:
Output:
Route beta testers to experimental features:
Route based on URL query parameters. Useful for feature flags, debug modes, and tier selection.
Test the routes:
Output:
Match both path and query parameters:
This matches /api/v2/tasks?experimental=enabled but not /api/v1/tasks?experimental=enabled.
Route based on HTTP method. A common pattern: send read operations to read replicas, write operations to the primary.
Test the routes:
Output:
Traffic weights enable gradual rollouts. Send most traffic to the stable version, a small percentage to the canary.
Traffic distribution:
Test with multiple requests:
Output:
Approximately 2 out of 20 requests go to canary.
Gradually increase canary traffic as confidence grows:
For instant cutover, change weights from 100/0 to 0/100:
Mirror traffic to a shadow service for testing without affecting production responses. The shadow service receives copies of requests, but its responses are discarded.
How it works:
Use cases:
Verify mirroring:
Output:
Rules are evaluated in order. More specific rules should come first.
Request routing Summary:
Wrong order (specific rule never matches):
Correct order:
For gRPC services, use GRPCRoute instead of HTTPRoute. GRPCRoute understands gRPC semantics like service and method matching.
Verify GRPCRoute:
Output:
Your Gateway needs a listener that accepts HTTP/2 for gRPC:
[!NOTE] gRPC uses HTTP/2, but the protocol field is HTTP. The actual HTTP version negotiation happens at the transport layer.
Create an HTTPRoute that routes all /api/ requests to the Task API:
Verify:
Expected Output:
Extend your HTTPRoute to route x-version: 2 requests to task-api-v2:
Test (if services exist):
Create a canary deployment with 90% stable, 10% canary:
Verify weights:
Expected Output:
Route debug requests to a debug-enabled backend:
Test (if services exist):
You built a traffic-engineer skill in Lesson 0. Based on what you learned about HTTPRoute:
Your skill should now generate HTTPRoute for common patterns:
Path-based template:
Header-based template:
Traffic splitting template:
When generating multiple rules, your skill should order them:
This ordering prevents more specific rules from being shadowed by general ones.
Your skill should ask about protocol:
Ask your traffic-engineer skill to generate routing:
What you're learning: AI generates routing rules from requirements. Review the output—did AI use the correct path matching type? Are the backend ports correct? Did it order rules appropriately?
Check AI's output:
If the route does not match your requirements, tell AI what needs to change:
Extend the configuration:
What you're learning: AI adapts existing configurations. Review the weights—do they sum correctly? Is the canary service defined with the right port?
Compare AI's final output to what you learned in this lesson:
This iteration—specifying requirements, evaluating output, refining with constraints—is how production configurations emerge.
When deploying HTTPRoute changes in production, test with kubectl apply --dry-run=client first. Incorrect routing rules can send traffic to wrong services or drop requests entirely. For canary deployments, start with small weights (1-5%) and monitor error rates before increasing.
HTTPRoute defines sophisticated routing logic with path matching (Exact, PathPrefix, RegularExpression), header matching, query parameter matching, and traffic weights for canary deployments, making it the application developer's primary resource.
📋Quick Reference
Access condensed key takeaways and quick reference notes for efficient review.
Free forever. No credit card required.