Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Gateways and Ingress

Istio and the Kubernetes Gateway API: HTTPRoute Explained

Learn the Kubernetes Gateway API in Istio: GatewayClass, Gateway and HTTPRoute resources, automated deployment, how they map to Istio's own APIs and when to choose which.

Istio's Gateway and VirtualService resources predate Kubernetes' own standard for the same job. The Kubernetes Gateway API is that standard: a set of role-oriented resources for describing load balancers and routes, implemented by many projects, Istio among them. Istio supports it as a first-class way to configure ingress, and it is the direction the project recommends for new deployments. This lesson shows the model and how it maps to what you already know.

The product cannot run on this site. The YAML is read-only and a Python stand-in converts one model to the other.

Why a new API

The older Istio resources had two quirks: a Gateway was just a listener description that attached to pods by label, and a VirtualService mixed edge routing with mesh routing. The Gateway API is built around three personas:

  • Infrastructure provider: defines a GatewayClass (which controller implements gateways). For Istio, the class is istio.
  • Cluster operator: creates Gateway objects, the actual listeners and the infrastructure behind them.
  • Application developer: creates HTTPRoute (also GRPCRoute, TCPRoute, TLSRoute) objects in their own namespace and attaches them to a Gateway.

Permissions follow these roles: developers need rights only on routes, and the Gateway decides which namespaces may attach (allowedRoutes).

Installing the CRDs

The Gateway API resources are not part of core Kubernetes in every cluster; their CRDs are installed separately and then Istio's controller reacts to them:

Terminal
kubectl get crd gateways.gateway.networking.k8s.io 2>/dev/null || \
  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/<version>/standard-install.yaml

Replace <version> with a current release; pin it in your repository.

A Gateway and an HTTPRoute

YAML
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: shop
  namespace: shop-edge
spec:
  gatewayClassName: istio
  listeners:
    - name: https
      port: 443
      protocol: HTTPS
      hostname: "shop.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: shop-cert
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              shop-access: "true"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop
spec:
  parentRefs:
    - name: shop
      namespace: shop-edge
  hostnames: ["shop.example.com"]
  rules:
    - matches:
        - path: { type: PathPrefix, value: /api }
      backendRefs:
        - name: api
          port: 8080
    - backendRefs:
        - name: productpage
          port: 9080

The big operational difference: you do not create a gateway Deployment. When Istio sees a Gateway of class istio it automatically provisions an Envoy Deployment and a Service named shop-istio in the same namespace. Scaling, annotations and labels can be tuned through the Gateway's infrastructure field or with a ConfigMap referenced by parametersRef.

Check it:

Terminal
kubectl get gateway -n shop-edge          # PROGRAMMED should be True
kubectl get httproute -n shop
kubectl describe httproute shop -n shop   # status shows Accepted and ResolvedRefs conditions

Route status conditions (Accepted, ResolvedRefs) are an improvement: they tell you in plain terms why a route was rejected, such as a namespace that is not allowed or a missing Service.

Traffic splitting and filters

Weights, header matches, redirects and header modifications are part of the standard:

YAML
rules:
  - backendRefs:
      - name: reviews-v1
        port: 9080
        weight: 90
      - name: reviews-v2
        port: 9080
        weight: 10
  - matches:
      - headers:
          - name: x-canary
            value: "true"
    backendRefs:
      - name: reviews-v2
        port: 9080
    filters:
      - type: RequestHeaderModifier
        requestHeaderModifier:
          add:
            - name: x-routed-by
              value: gateway-api

Mesh traffic: the GAMMA initiative

The same HTTPRoute can configure east-west traffic. Instead of a Gateway, the parentRef is a Service, which attaches the rules to requests going to that Service inside the mesh. Istio supports this for sidecar and ambient modes; it covers the common routing cases, but fine-grained features (fault injection, mirroring variants, some retry details) may still need a VirtualService.

YAML
parentRefs:
  - group: ""
    kind: Service
    name: reviews

Which one should you pick?

  • New edge deployments on a cluster that already uses the Gateway API: use the standard resources; they are portable and role-friendly.
  • Existing, working Istio Gateway/VirtualService setups: keep them; both APIs coexist.
  • Advanced features without a Gateway API equivalent yet: stay with VirtualService/DestinationRule for those routes.

Try it: convert a VirtualService route to an HTTPRoute

This stand-in turns a simplified VirtualService dictionary into an HTTPRoute dictionary and prints it, so you can see how the fields correspond.

Python VirtualService to HTTPRoute converter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Try it: allowedRoutes check

Python May this namespace attach routes?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the gatewayClassName for Istio's implementation of the Gateway API?

    GatewayClass istio tells the Istio controller to program the Gateway.
  2. 2. What happens when you create a Gateway of class istio?

    Automated deployment creates the Envoy proxy and Service for the Gateway.
  3. 3. Which field attaches an HTTPRoute to a Gateway?

    parentRefs names the Gateway (or, for mesh traffic, the Service) a route attaches to.
  4. 4. Who decides which namespaces may attach routes to a listener?

    allowedRoutes lets the cluster operator control which namespaces can bind to the listener.

Summary

  • The Gateway API splits roles: GatewayClass, Gateway (operators) and HTTPRoute (developers).
  • Istio provisions the gateway proxy automatically for a Gateway of class istio.
  • Route status conditions explain rejections.
  • The same routes can configure mesh traffic with a Service as parent.
  • Both APIs coexist; use VirtualService where the standard lacks a feature.

Next: Circuit breaking and outlier detection