Learn Multigress - Gateway API & HTTPRoute

#Introduction

In episode 3 you already saw the Gateway and HTTPRoute in action. Episode 4 deepens your understanding of the Gateway API object family: what each one does, how you configure routing based on host and path, and how HTTPRoute interacts with the Services and Ingress already in your cluster.

This is the core episode of the series. Almost every feature in the following episodes — TLS, canary, rate limiting — is built on top of the route concepts you master here.

#Getting to Know the Gateway API Objects

#GatewayClass: Declaring the Implementation

GatewayClass is the topmost resource. It declares which implementation handles the resources below it. A cluster can have several classes, for example multigress for production and multigress-dev for development.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: multigress
spec:
  controllerName: multigress.io/multigress-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: multigress-dev
spec:
  controllerName: multigress.io/multigress-controller

Notice that both use the same controller, differing only in name. This is useful for applying different policies between environments.

#Gateway: Declaring Listeners

Gateway declares the entry point: ports, protocols, and the hosts it serves. A listener can be constrained with hostname so the gateway only accepts certain domains.

#Route: Determining Where Traffic Flows

The route family in the Gateway API includes HTTPRoute, TLSRoute, GRPCRoute, TCPRoute, and UDPRoute. Each handles a different protocol and follows the same structure: parentRefs points to a Gateway, and rules contains the routing rules.

#ReferenceGrant: Cross-Namespace Permission

By default, a route may only point to a backend in the same namespace. For cross-namespace access, you need a ReferenceGrant:

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-echo-route
  namespace: default
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: multigress-system
  to:
    - group: ""
      kind: Service

The ReferenceGrant resource above allows HTTPRoutes from the multigress-system namespace to point to Services in the default namespace. Without it, cross-namespace routes will be rejected.

#Configuring Host and Path Routing

#Hostname and Path Matching

HTTPRoute matches requests based on hostnames and the path rules inside rules. The following example routes the domain api.example.com with the /v1 path to the api Service, and all other paths to the web Service:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: main-gateway
      namespace: multigress-system
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api
          port: 8080
    - backendRefs:
        - name: web
          port: 80

A rule without matches acts as the default: it catches all traffic that doesn't match the earlier rules. Rule order matters a lot, so arrange them from most specific to most general.

#Path Matching Types

The Gateway API recognizes two match types:

• PathPrefix: matches the path prefix. /v1 will match /v1/users and /v1/orders.
• Exact: matches only the exact path.

curl -s http://localhost:8080/v1/health -H "Host: api.example.com"
curl -s http://localhost:8080/ -H "Host: api.example.com"

The first request is routed to the api Service, the second to the web Service. The curl -s http://localhost:8080/v1/health -H "Host: api.example.com" command uses the Host header to simulate a domain without needing DNS.

#Integration Modes with Service and Ingress

#Backend Is Always a Service

An important point that often confuses people: HTTPRoute points to a Service, not a Deployment or Pod. This keeps configuration declarative — the proxy only knows the Service name and port, and Kubernetes handles pod selection.

#HTTPRoute vs Ingress

Both can coexist. Ingress continues to work for legacy controllers, while HTTPRoute is used by Multigress. If you want to migrate, the steps are:

1. Create a new GatewayClass and Gateway.
2. Create an HTTPRoute equivalent to each Ingress.
3. Verify traffic, then delete the old Ingress.

kubectl get ingress -A
kubectl get httproute -A

Migration can be done gradually per domain — it doesn't have to happen all at once. During this process, both paths can run in parallel because the Gateway listeners are separate from the ingress controller.

#Closing

Episode 4 completes your core understanding of the Gateway API: the roles of GatewayClass, Gateway, routes, and ReferenceGrant, how to configure host and path routing with the right match types, and how HTTPRoute coexists with existing Services and Ingress.

The key takeaways:

• GatewayClass declares the implementation; Gateway declares the listeners.
• HTTPRoute, TLSRoute, and the route family point to Services through parentRefs.
• ReferenceGrant is required for cross-namespace routes.
• PathPrefix matches prefixes; Exact only matches the exact path.
• The route backend is always a Service, not a Deployment or Pod.
• HTTPRoute and Ingress can coexist during migration.

In the next episode 5 we'll secure traffic with TLS & HTTPS termination — storing TLS certificates in a Kubernetes secret, configuring HTTPS termination on the Gateway, and learning TLS passthrough and SNI control. Make sure your episode 3 Gateway is still running.