#Configure GatewayAPI Route

#Overview

This document explains how to configure Route resources after a Gateway is ready. A Route attaches to one or more gateway listeners and defines how matching traffic is forwarded to backend services.

In the recommended workflow, this document comes after Configure GatewayAPI Gateway and before Configure GatewayAPI Policy.

In addition to create and update operations, this document also introduces the extra route viewing capabilities provided by the ACP Web Console.

#Prerequisites

Please ensure that you have completed the following before proceeding:

1. Read Configure GatewayAPI Gateway to understand listeners, attachment rules, and EnvoyProxy
2. Create a Gateway that your Route will attach to

#Configuration

A Route attaches to one or more listeners on a Gateway. The listener you can select depends on the route type, the listener protocol, and the listener's allowed route namespace settings.

#Configuration Via Web Console

1. Navigate to Alauda Container Platform -> Networking -> Gateway -> Routes
2. Click the Create Route button
3. Select the route type (HTTPRoute, TCPRoute, UDPRoute, GRPCRoute, or TLSRoute)

#Create HTTPRoute

#Options Configuration

The Options field allows you to configure advanced traffic management settings:

#Create TCP/UDP Route

#Create GRPCRoute

#Create TLSRoute

#Configuration Via YAML

The following minimal example creates an HTTPRoute that attaches to the https listener of the demo Gateway and forwards matching traffic to a backend Service.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo-443
  namespace: demo
spec:
  hostnames:
    - example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: https
  rules:
    - matches:
        - path:
            type: Exact
            value: /a
      backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          namespace: demo-space
          port: 80
          weight: 100

If you need more route types and advanced HTTPRoute options, use the following complete example:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo-443
  namespace: demo
spec:
  hostnames:
    - example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: https
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          namespace: demo-space
          port: 80
          weight: 100
      filters: [] 
      matches:
        - path:
            type: Exact
            value: /a
      timeouts:
        request: "30s"
        backendRequest: "10s"
      retry:
        codes:
          - 503
        attempts: 3
        backoff: "100ms"
      sessionPersistence:
        type: Cookie
        sessionName: a
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: tcp
  namespace: demo-space
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: tcp
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          port: 80
          weight: 100
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: UDPRoute
metadata:
  name: udp
  namespace: demo
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      namespace: demo
      sectionName: udp
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: echo-resty
          namespace: demo
          port: 53
          weight: 100
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: grpc
  namespace: demo
spec:
  hostnames:
    - grpc.example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: https
  rules:
    - matches:
        - method:
            type: service
            value: myservice
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            set:
              - name: x-custom-header
                value: custom-value
      backendRefs:
        - group: ''
          kind: Service
          name: grpc-service
          port: 50051
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: tls
  namespace: demo
spec:
  hostnames:
    - tls.example.com
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: demo
      sectionName: tls
  rules:
    - backendRefs:
        - group: ''
          kind: Service
          name: tls-backend
          port: 443

#Route Field Reference

Each route is a CR defined by the GatewayAPI specification. For detailed information about the fields and configuration options for each route type, please refer to the official documentation:

• HTTPRoute specification
• TCPRoute specification
• UDPRoute specification
• GRPCRoute specification
• TLSRoute specification

#Publish to Listener

#In Web Console

In the web console, you can select multiple listeners to publish the route to. The available listener candidates are filtered based on the following criteria:

• User permissions: You must have access to the gateway's namespace (the project must include this namespace).
• Route namespace allowlist: The gateway listener's allowed route namespaces must include the route's namespace.
• Route kind matching: The route's kind (HTTPRoute, GRPCRoute, etc.) must match the listener's allowed route kinds.

For more complex cross-namespace scenarios, please refer to attaching to a gateway created in another namespace.

#In YAML

• The sectionName is the listener name.
• Routes can only be attached to listeners that support their specific kind.
• By default, routes can only be attached to listeners where the Gateway is in the same namespace.

For cross-namespace attachment, please refer to attaching to a gateway created in another namespace.

#Backend

Defines the target service(s) where matching requests should be forwarded.

Each service can have a weight field to specify the proportion of traffic to be routed to that service.

#Hostnames

The hostnames field is supported by HTTPRoute, GRPCRoute, and TLSRoute. TCPRoute and UDPRoute do not use this field.

hostnames is a string array. It follows the Hostname Intersection Rules.

#Rules

Each route can contain multiple rules. Each rule consists of the following components:

#Matches

Defines the conditions that must be met for a request to be routed by this rule.

A rule can have multiple matches:

• Each match consists of multiple conditions (e.g., path, headers, query parameters, method)
• Conditions within a match use AND logic (all must be satisfied)
• Matches between each other use OR logic (any match can satisfy the rule)

Example: If Match-1 requires path=/api AND header=v1, and Match-2 requires query=test, then a request is routed if it matches either (path=/api AND header=v1) OR (query=test).

The match structure is common across route types, but the supported match conditions depend on the route type. For example, HTTPRoute and GRPCRoute support different match condition sets.

#Filters

Specifies transformations or modifications to apply to requests or responses.

The filter concept is common across route types, but the supported filter types depend on the route type.

#HTTPRoute Reference

The following match conditions, filter types, and advanced options are used by HTTPRoute.

#Match Condition Types

#Match Condition References

#Filter Types

Notes:

• RequestRedirect and URLRewrite cannot be used together on the same rule
• ReplacePrefixMatch is only compatible with a PathPrefix HTTPRouteMatch
• Header names are case-insensitive per RFC 7230
• Multiple values for same header must use RFC 7230 comma-separated format

#Filter References

#Options

The Options section provides advanced traffic management capabilities for HTTPRoute, including timeout, retry, and session persistence settings.

#Timeouts

#Retry

#Session Persistence

Configures session affinity settings to ensure requests from the same client are routed to the same backend.

#GRPCRoute Match and Filter Reference

The following match conditions and filter types are used by GRPCRoute.

#GRPCRoute Matches

GRPCRoute supports the following match types:

#GRPCRoute Filters

GRPCRoute only supports the RequestHeaderModifier filter:

#TLSRoute Reference

The following behavior is specific to TLSRoute.

#View

#Topology

The following features are additional viewing capabilities provided by the ACP Web Console.

The topology tab provides a visual representation of the route and its associated resources. It displays all policies attached to the route, along with their dependent resources such as secrets referenced by SecurityPolicy.

This feature is currently only available for HTTPRoute.

#Next Step

After routes are attached to listeners, continue with Configure GatewayAPI Policy if you need advanced traffic or security policies. For additional operational examples, see Tasks for Envoy Gateway.

#Related Tasks

• How to attach to listener created in other namespace