istio/istio

Kubernetes Gateway API

Active contributors: howardjohn, hzxuzhonghu, keithmattix, stevenctl

What users do

Use the Kubernetes Gateway API (gateway.networking.k8s.io) instead of Istio's Gateway + VirtualService to configure ingress, in-mesh L7 routing, and (in Ambient) waypoints. Istio is one of the reference implementations of the Gateway API.

The relevant GatewayClass names Istio installs:

istio — for ingress/egress gateway Deployments. Provisions a Deployment + Service automatically when a Gateway of this class is created.
istio-waypoint — for Ambient waypoints.
istio-remote — for connecting to an existing Service (no auto-provisioning).

Where it's implemented

pilot/pkg/config/kube/gateway/
├── conversion.go          # The translator: Gateway/HTTPRoute/... → Istio internal config
├── controller.go          # The controller wrapping conversion in a kube watch
├── conditions.go          # Status condition computation
├── deploymentcontroller.go # Auto-provisioning Deployments+Services for the istio GatewayClass
└── ...

Translation model

The controller turns Gateway API resources into the same internal model.Gateway and model.VirtualService types that Istio's own API uses. Once translated, the rest of the pipeline (push context, networking core, xDS) doesn't know the difference.

graph LR
    subgraph KubeGW[Gateway API CRDs]
        gw[Gateway]
        hr[HTTPRoute]
        tr[TCPRoute]
        gtr[GRPCRoute]
        rgp[ReferenceGrant]
    end
    subgraph IstioInternal[Istio internal types]
        g[model.Gateway]
        vs[model.VirtualService]
    end
    KubeGW -->|conversion.go| IstioInternal
    IstioInternal --> push[PushContext]
    push --> core[networking/core]
    core --> envoy[Envoy]

Auto-provisioning

When a user creates a Gateway with gatewayClassName: istio, deploymentcontroller.go creates:

A Deployment running istio-proxy in gateway mode.
A Service of the type matching the listener (LoadBalancer by default).
Necessary ServiceAccount and PodSecurityContext.

The deployment uses the istio-proxy image and is automatically picked up as a Gateway proxy by istiod's Pod-watching service registry.

For istio-waypoint, the same controller provisions a waypoint deployment when a Gateway of that class is created.

Status

Status is reconciled back to the Gateway API resource:

Gateway.status.conditions — Accepted, Programmed, ResolvedRefs.
Gateway.status.listeners — per-listener accepted/programmed conditions.
HTTPRoute.status.parents — per-parent attachment status.

The status writer is pilot/pkg/status/. It uses krt to derive desired status from the active config and writes back via the kube client.

Cross-namespace references

Gateway API requires explicit ReferenceGrant for cross-namespace references between resources (e.g. an HTTPRoute in namespace A referencing a Service in namespace B). The controller validates these grants at conversion time; missing grants result in ResolvedRefs: False on the Route.

Differences from Istio's API

Aspect	Istio API	Gateway API
Provisioning	User creates Deployment + Service	Auto
Cross-namespace	Implicit	ReferenceGrant required
Status	Patchy	Rich, per-listener / per-parent
Routing	VirtualService	HTTPRoute / TCPRoute / etc.
Per-method match	Yes	Yes
Mirror	`mirror[]`	`RequestMirror` filter
Fault injection	Yes	Not in stable API
Retries	Yes	Yes (since v1.0)
Authentication	RequestAuthentication	Not built into routes

The Istio API remains supported; both can coexist in a mesh. New deployments are encouraged to start with Gateway API.

Trade-offs

API surface — Gateway API doesn't yet cover fault injection, mirror weights, or RBAC. For these, mix in Istio resources (e.g. AuthorizationPolicy with targetRef).
Auto-provisioning quirks — the Deployment is owned by the Gateway resource. Editing it manually is cleared on the next reconcile. For custom topology, use a Gateway of class istio-remote and a manually created Deployment.
TCPRoute subtleties — the TCP forwarder in Envoy doesn't have the rich match logic of HTTP. Routes are matched by listener port + SNI only.
Migration cost — there is no automatic migrator from Istio API → Gateway API. Coexistence is the easy path.

Key source files

File	Purpose
`pilot/pkg/config/kube/gateway/conversion.go`	Translator
`pilot/pkg/config/kube/gateway/controller.go`	Controller
`pilot/pkg/config/kube/gateway/conditions.go`	Status computation
`pilot/pkg/config/kube/gateway/deploymentcontroller.go`	Auto-provisioning
`pilot/pkg/networking/core/gateway.go`	Final config compile
`manifests/charts/gateway/`	Helm chart for `istio-proxy` gateway