How to Replace Istio Ingress Gateway with Kubernetes Gateway API – Step‑by‑Step Guide

Kubernetes Gateway API Overview

The Gateway API is a next‑generation traffic‑management standard that addresses the limitations of the long‑standing Ingress API, offering richer matching rules, weight‑based routing, and role‑based access control. It also introduces support for mesh (east‑west) traffic through the GAMMA working group.

How It Works

Three core resources form the API:

GatewayClass : defines a shared configuration and is bound to a controller.

Gateway : represents a network entry point that can be created by an admin or the controller.

Route : maps incoming traffic to services; current types include HTTPRoute, TLSRoute, TCPRoute, UDPRoute, and GRPCRoute.

The following diagram (originally in the article) shows the relationship among these resources:

Using the Gateway API in Istio

The article walks through a complete example that replaces an Istio Ingress Gateway with a Kubernetes Gateway API resource.

Install the Gateway API CRDs:

$ kubectl get crd gateways.gateway.networking.k8s.io || kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.1" | kubectl apply -f -

Install a minimal Istio profile (the built‑in Istio ingress gateway is no longer needed): $ istioctl install --set profile=minimal -y Verify that Istio created a GatewayClass named istio with controller istio.io/gateway-controller:

$ kubectl get gatewayclass
NAME   CONTROLLER                     ACCEPTED   AGE
istio  istio.io/gateway-controller   True       6s

Deploy the sample httpbin service:

$ kubectl apply -f https://raw.githubusercontent.com/istio/istio/1.16.0/samples/httpbin/httpbin.yaml

Create a Gateway and an HTTPRoute that expose httpbin.example.com/get/*:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: gateway
  namespace: istio-ingress
spec:
  gatewayClassName: istio
  listeners:
  - name: default
    hostname: "*.example.com"
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http
  namespace: default
spec:
  parentRefs:
  - name: gateway
    namespace: istio-ingress
  hostnames: ["httpbin.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000

Wait for the gateway to become ready and capture its address:

$ kubectl wait -n istio-ingress --for=condition=ready gateways.gateway.networking.k8s.io gateway
$ export INGRESS_HOST=$(kubectl get gateways.gateway.networking.k8s.io gateway -n istio-ingress -ojsonpath='{.status.addresses[*].value}')

Test the service:

$ curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"
HTTP/1.1 200 OK
...

Update the HTTPRoute to also expose /headers and add a custom request header:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http
  namespace: default
spec:
  parentRefs:
  - name: gateway
    namespace: istio-ingress
  hostnames: ["httpbin.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    - path:
        type: PathPrefix
        value: /headers
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: my-added-header
          value: added-value
    backendRefs:
    - name: httpbin
      port: 8000

Re‑test the new path and see the added header in the response JSON.

Finally, clean up all resources:

$ kubectl delete -f samples/httpbin/httpbin.yaml
$ kubectl delete httproute http
$ kubectl delete gateways.gateway.networking.k8s.io gateway -n istio-ingress
$ istioctl uninstall -y --purge
$ kubectl delete ns istio-system istio-ingress
$ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.1" | kubectl delete -f -

Can Existing Istio Ingress Gateways Be Auto‑Converted?

At present there is no tool that automatically migrates an Istio IngressGateway resource to a Gateway API resource, although the community has started the ingress2gateway project that can translate ingress‑nginx configurations.

Is It Time to Migrate?

If the current Istio IngressGateway meets all your needs, you can continue using it because it is mature and stable. The Ingress API and Gateway API will coexist for the foreseeable future, and Istio’s own APIs (Gateway, VirtualService, DestinationRule) will remain supported. However, for teams that require richer traffic control, vendor‑agnostic portability, or mesh‑level routing, adopting the Kubernetes Gateway API is a forward‑looking choice.

References

Kubernetes Gateway API website: https://gateway-api.sigs.k8s.io/

Gateway API GitHub repository: https://github.com/kubernetes-sigs/gateway-api/

Istio documentation for Gateway API: https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/

Ingress2gateway project: https://github.com/kubernetes-sigs/ingress2gateway