Gateway API & Istio: Integrate Your Service Mesh

Introduction

The Kubernetes Gateway API is rapidly emerging as the successor to Ingress, offering a more expressive, extensible, and role-oriented approach to managing traffic routing in Kubernetes. While Ingress objects have served the community well, their limitations in handling advanced traffic management, policy enforcement, and multi-team environments have become increasingly apparent. The Gateway API addresses these challenges head-on, providing a robust framework for everything from simple HTTP routing to complex service mesh integrations.

When it comes to sophisticated traffic management and policy enforcement within a Kubernetes cluster, Istio is often the first name that comes to mind. As a powerful service mesh, Istio provides capabilities like traffic routing, resiliency, security, and observability out of the box. Integrating the Gateway API with Istio combines the best of both worlds: the declarative, flexible, and role-based traffic management of the Gateway API with the extensive service mesh features of Istio. This synergy allows platform teams to define clear boundaries and responsibilities, empowering application developers while maintaining centralized control over the network edge and internal service-to-service communication. This guide will walk you through setting up and leveraging this powerful combination.

TL;DR: Istio Gateway API Integration

Seamlessly integrate Kubernetes Gateway API with Istio for advanced traffic management. This guide covers installation, configuration, and practical examples.

# Install Gateway API CRDs (if not already present with Istio)
kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml

# Install Istio (e.g., using istioctl)
istioctl install --set profile=default -y

# Enable Gateway API support in Istio
istioctl install --set profile=default --set components.ingressGateways[0].enabled=false \
  --set components.ingressGateways[1].name=istio-gateway \
  --set components.ingressGateways[1].enabled=true \
  --set components.ingressGateways[1].label.istio='istio-gateway' \
  --set components.ingressGateways[1].label.app='istio-gateway' \
  --set values.gateways.istio-ingressgateway.gatewayControllerMode=Standard \
  --set values.gateways.istio-ingressgateway.customService=true -y

# Example Gateway and HTTPRoute
kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: external-gateway
  namespace: istio-system
spec:
  gatewayClassName: istio
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app-route
  namespace: default
spec:
  parentRefs:
  - name: external-gateway
    namespace: istio-system
  hostnames:
  - "my-app.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: my-app-service
      port: 80
EOF

# Verify
kubectl get gateway -A
kubectl get httproute -A

Prerequisites

Before diving into the integration, ensure you have the following:

• A Kubernetes Cluster: Version 1.22+ is recommended for full Gateway API compatibility. You can use any cloud provider (AWS EKS, GCP GKE, Azure AKS) or a local cluster like Kind or Minikube.
• kubectl: Configured to connect to your Kubernetes cluster.
• helm (optional but recommended): For easier installation of Istio.
• istioctl: The Istio command-line tool, essential for installing and managing Istio. Follow the official Istio documentation for installation.
• Basic understanding of Kubernetes concepts: Pods, Services, Deployments, Namespaces.
• Familiarity with Istio basics: Concepts like Gateways, VirtualServices, DestinationRules will be helpful, though we’ll cover the Gateway API equivalents. For a deeper dive into Istio, consider our Istio Ambient Mesh Production Guide.

Step-by-Step Guide: Integrating Gateway API with Istio

1. Install Gateway API CRDs

The Gateway API is a collection of Custom Resource Definitions (CRDs) that extend Kubernetes to manage ingress traffic. While newer Istio versions might install these CRDs by default, it’s good practice to ensure they are present and up-to-date. This step ensures your cluster understands Gateway, HTTPRoute, TCPRoute, etc., objects.

The official Gateway API project provides standard installation manifests. We’ll apply these to our cluster. This is typically a one-time step per cluster.

# Check if Gateway API CRDs are already installed
kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null

# If not installed, apply the standard manifest for Gateway API CRDs
if [ $? -ne 0 ]; then
  echo "Gateway API CRDs not found. Installing..."
  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
else
  echo "Gateway API CRDs already present."
fi

# Wait for CRDs to be established
kubectl wait --for=condition=Established crd gateways.gateway.networking.k8s.io --timeout=300s
kubectl wait --for=condition=Established crd httproutes.gateway.networking.k8s.io --timeout=300s

Verify:

You should see the Gateway API CRDs listed, indicating they are installed and ready for use.

kubectl get crd | grep gateway.networking.k8s.io

# Expected Output (may vary slightly by version)
gateways.gateway.networking.k8s.io                   2023-10-27T12:00:00Z
grpcroutes.gateway.networking.k8s.io                 2023-10-27T12:00:00Z
httproutes.gateway.networking.k8s.io                 2023-10-27T12:00:00Z
referencegrants.gateway.networking.k8s.io            2023-10-27T12:00:00Z
tcproutes.gateway.networking.k8s.io                  2023-10-27T12:00:00Z
tlsroutes.gateway.networking.k8s.io                  2023-10-27T12:00:00Z
udproutes.gateway.networking.k8s.io                  2023-10-27T12:00:00Z

2. Install Istio with Gateway API Support

Next, we’ll install Istio. Crucially, we need to configure Istio’s ingress gateway to operate in Gateway API mode. This tells Istio to provision and manage its ingress gateway resources based on Gateway API objects (Gateway, HTTPRoute) rather than its native Gateway and VirtualService resources. This switch is key to unlocking the power of the Gateway API with Istio.

We’ll use istioctl with specific overrides. The gatewayControllerMode: Standard setting enables the Gateway API controller, and customService: true ensures that Istio creates a standard Kubernetes Service for the gateway, which is essential for external access.

# Install Istio with default profile
istioctl install --set profile=default -y

# Configure Istio to use Gateway API
# This involves disabling the default Istio Ingress Gateway and enabling a new one
# with 'gatewayControllerMode: Standard'.
# Note: The exact 'components.ingressGateways' index might vary if you have multiple gateways configured.
# We're explicitly setting up one named 'istio-gateway' to be managed by Gateway API.
istioctl install --set profile=default \
  --set components.ingressGateways[0].enabled=false \
  --set components.ingressGateways[1].name=istio-gateway \
  --set components.ingressGateways[1].enabled=true \
  --set components.ingressGateways[1].label.istio='istio-gateway' \
  --set components.ingressGateways[1].label.app='istio-gateway' \
  --set values.gateways.istio-ingressgateway.gatewayControllerMode=Standard \
  --set values.gateways.istio-ingressgateway.customService=true -y

Verify:

Check if the Istio pods are running and if the istio-gateway service is created. The gatewayControllerMode setting doesn’t directly show in kubectl get output, but its effect will be seen in how Istio processes Gateway API objects.

kubectl get po -n istio-system
kubectl get svc -n istio-system | grep istio-gateway

# Expected Output (truncated for brevity)
# Pods
istiod-7b7d7c7c7c-abcde                  1/1     Running   0          5m
istio-gateway-7b7d7c7c7c-fghij           1/1     Running   0          4m

# Services
istio-gateway   LoadBalancer   10.100.0.100   <pending>   15021:30000/TCP,80:30001/TCP,443:30002/TCP   4m

Note the istio-gateway service. On cloud providers, its EXTERNAL-IP will eventually populate, providing external access. For local clusters, you might need to use port-forwarding or a tool like MetalLB with Kind.

3. Deploy a Sample Application

To demonstrate routing, we need a backend service. Let’s deploy a simple httpbin application, a popular tool for testing HTTP requests and responses. We’ll deploy it in the default namespace.

# httpbin-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
  labels:
    app: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
  template:
    metadata:
      labels:
        app: httpbin
    spec:
      containers:
      - name: httpbin
        image: docker.io/kennethreitz/httpbin
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: httpbin
  labels:
    app: httpbin
spec:
  ports:
  - name: http
    port: 80
    targetPort: 80
  selector:
    app: httpbin

kubectl apply -f httpbin-deployment.yaml

Verify:

Ensure the httpbin pod and service are running correctly in the default namespace.

kubectl get po,svc -l app=httpbin

# Expected Output
NAME                           READY   STATUS    RESTARTS   AGE
pod/httpbin-7b7d7c7c7c-abcde   1/1     Running   0          2m

NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
service/httpbin   ClusterIP   10.100.10.100   <none>        80/TCP    2m

4. Create a Gateway Resource

The Gateway resource represents the entry point for traffic into your cluster, similar to an Istio Ingress Gateway or a Kubernetes Ingress resource, but with more flexibility. It defines listening ports, protocols, and which HTTPRoutes (or other route types) are allowed to attach to it. Here, we’ll create a Gateway in the istio-system namespace, referencing the istio GatewayClass, which is provided by our Istio installation.

# external-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: external-gateway
  namespace: istio-system # Gateways are typically in the same namespace as the controller
spec:
  gatewayClassName: istio # This links to the Istio Gateway controller
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    # Enable cross-namespace route attachment for flexibility
    allowedRoutes:
      namespaces:
        from: All # Allows HTTPRoutes from any namespace to attach to this Gateway

kubectl apply -f external-gateway.yaml

Verify:

Check the status of your Gateway. It should eventually show as “Ready” and have an address assigned (the external IP of the Istio ingress gateway service).

kubectl get gateway -n istio-system external-gateway -o yaml

# Expected Output (truncated)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: external-gateway
  namespace: istio-system
spec:
  gatewayClassName: istio
  listeners:
  - allowedRoutes:
      namespaces:
        from: All
    name: http
    port: 80
    protocol: HTTP
status:
  addresses:
  - type: IPAddress
    value: 192.168.1.100 # This will be your external IP or <pending> for local clusters
  conditions:
  - lastTransitionTime: "2023-11-01T10:00:00Z"
    message: Gateway is accepted and ready for traffic.
    observedGeneration: 1
    reason: Accepted
    status: "True"
    type: Accepted
  - lastTransitionTime: "2023-11-01T10:00:00Z"
    message: Listener is running
    observedGeneration: 1
    reason: ListenerReady
    status: "True"
    type: Ready
  listeners:
  - attachedRoutes: 0
    name: http
    supportedKinds:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
    conditions:
    - lastTransitionTime: "2023-11-01T10:00:00Z"
      message: Listener is ready
      observedGeneration: 1
      reason: Ready
      status: "True"
      type: Ready

Note the status.addresses field. This is the IP address or hostname you’ll use to access your application. If it’s <pending>, your cloud provider’s load balancer might still be provisioning, or you’re on a local cluster without an external IP provisioner. In a local environment, you can get the port mapping: kubectl get svc -n istio-system istio-gateway and use localhost:NODE_PORT.

5. Create an HTTPRoute Resource

An HTTPRoute defines how HTTP traffic is routed to backend services. It attaches to a Gateway and specifies hostnames, path matches, and backend services. This is where you define your application’s routing logic. Here, we’ll route traffic for httpbin.example.com to our httpbin service.

# httpbin-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-route
  namespace: default # HTTPRoute typically lives in the application's namespace
spec:
  parentRefs:
  - name: external-gateway # Reference the Gateway we created
    namespace: istio-system # Specify the namespace of the Gateway
  hostnames:
  - "httpbin.example.com" # The hostname for this route
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: / # Match all paths under this hostname
    backendRefs:
    - name: httpbin # Name of our service
      port: 80 # Port of our service

kubectl apply -f httpbin-route.yaml

Verify:

Check the status of your HTTPRoute. It should show as “Accepted” and “ResolvedRefs”, indicating it has successfully attached to the Gateway and referenced the backend service.

kubectl get httproute -n default httpbin-route -o yaml

# Expected Output (truncated)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-route
  namespace: default
spec:
  hostnames:
  - httpbin.example.com
  parentRefs:
  - name: external-gateway
    namespace: istio-system
  rules:
  - backendRefs:
    - name: httpbin
      port: 80
    matches:
    - path:
        type: PathPrefix
        value: /
status:
  parents:
  - controllerName: istio.io/gateway-controller
    parentRef:
      group: gateway.networking.k8s.io
      kind: Gateway
      name: external-gateway
      namespace: istio-system
    conditions:
    - lastTransitionTime: "2023-11-01T10:10:00Z"
      message: Route was successfully attached to the Gateway
      observedGeneration: 1
      reason: Accepted
      status: "True"
      type: Accepted
    - lastTransitionTime: "2023-11-01T10:10:00Z"
      message: All references to backends are valid
      observedGeneration: 1
      reason: ResolvedRefs
      status: "True"
      type: ResolvedRefs

6. Test the Routing

Now that everything is configured, it’s time to test if traffic is correctly routed through the Istio Gateway, managed by the Gateway API. You’ll need the external IP address of your istio-gateway service. If you’re on a local cluster (like Kind), you might need to use kubectl port-forward or ensure a load balancer solution like MetalLB is running.

First, get the external IP:

# Get the external IP of the Istio Gateway
GATEWAY_IP=$(kubectl get svc -n istio-system istio-gateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
if [ -z "$GATEWAY_IP" ]; then
  # Fallback for local clusters without external IP (e.g., Kind without MetalLB)
  # This gets the node port for port 80 and assumes you can curl to your node's IP on that port.
  echo "External IP not found, attempting to get NodePort..."
  NODE_PORT=$(kubectl get svc -n istio-system istio-gateway -o jsonpath='{.spec.ports[?(@.port==80)].nodePort}')
  NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
  GATEWAY_IP="$NODE_IP:$NODE_PORT"
  echo "Using NodePort: $GATEWAY_IP"
fi
echo "Gateway IP: $GATEWAY_IP"

Now, use curl to send a request, specifying the Host header to match our HTTPRoute‘s hostname.

curl -I -H "Host: httpbin.example.com" "http://$GATEWAY_IP/headers"

Verify:

You should receive a successful HTTP 200 OK response from the httpbin service, including headers that confirm the request went through Istio (e.g., server: envoy).

# Expected Output (truncated)
HTTP/1.1 200 OK
server: envoy
date: Wed, 01 Nov 2023 10:15:00 GMT
content-type: application/json
content-length: 379
access-control-allow-origin: *
access-control-allow-credentials: "true"
x-envoy-upstream-service-time: 1

If you see a 404 or other error, double-check your Gateway IP, the Host header, and the status of your Gateway and HTTPRoute resources.

7. Advanced Traffic Management: Header-Based Routing

One of the strengths of the Gateway API, especially with Istio, is advanced traffic management. Let’s create a new version of our httpbin service (e.g., httpbin-v2) and route traffic to it based on a custom header. This showcases how the Gateway API can handle more complex routing rules than traditional Ingress.

# httpbin-v2-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin-v2
  labels:
    app: httpbin
    version: v2
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
      version: v2
  template:
    metadata:
      labels:
        app: httpbin
        version: v2
    spec:
      containers:
      - name: httpbin
        image: docker.io/kennethreitz/httpbin
        env:
        - name: VERSION
          value: "v2" # Add an env var to distinguish
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: httpbin-v2
  labels:
    app: httpbin
    version: v2
spec:
  ports:
  - name: http
    port: 80
    targetPort: 80
  selector:
    app: httpbin
    version: v2

kubectl apply -f httpbin-v2-deployment.yaml

Now, modify the httpbin-route to include a new rule that routes traffic with the header x-version: v2 to httpbin-v2, and all other traffic to the original httpbin service.

# httpbin-route-advanced.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-route
  namespace: default
spec:
  parentRefs:
  - name: external-gateway
    namespace: istio-system
  hostnames:
  - "httpbin.example.com"
  rules:
  - matches:
    - headers:
      - type: Exact
        name: x-version
        value: v2
    backendRefs:
    - name: httpbin-v2 # Route to v2 if header matches
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: / # Default rule for all other traffic
    backendRefs:
    - name: httpbin # Route to original httpbin
      port: 80

kubectl apply -f httpbin-route-advanced.yaml

Verify:

Test with and without the x-version: v2 header. You can check the json output from /headers endpoint to see which service responded (look for the VERSION environment variable if exposed, or other distinguishing features).

# Test with x-version: v2 header
curl -H "Host: httpbin.example.com" -H "x-version: v2" "http://$GATEWAY_IP/headers" | grep "X-Version"

# Expected Output (showing v2 received the request)
    "X-Version": "v2"

# Test without x-version: v2 header
curl -H "Host: httpbin.example.com" "http://$GATEWAY_IP/headers" | grep "X-Version"

# Expected Output (no X-Version header, meaning v1 received it or no specific version was identified)
# (empty output or an output not containing "X-Version")

The httpbin service just reflects headers. If you want to see the service version, you’d typically need your application to expose it. For our httpbin-v2, we added an environment variable VERSION=v2. We can access /env to verify:

curl -H "Host: httpbin.example.com" -H "x-version: v2" "http://$GATEWAY_IP/env" | grep "VERSION"

# Expected Output
    "VERSION": "v2"

curl -H "Host: httpbin.example.com" "http://$GATEWAY_IP/env" | grep "VERSION"

# Expected Output (no VERSION env var for httpbin v1)
# (empty output)

This demonstrates successful header-based routing using Gateway API with Istio. For more advanced traffic management, like weighted routing or fault injection, you can explore Istio’s native policies or custom Gateway API extensions.

Production Considerations

Integrating Gateway API with Istio in a production environment requires careful planning and adherence to best practices:

1. Gateway API Versioning: Always use stable API versions (e.g., v1) for production. Keep an eye on the Gateway API progress and plan upgrades carefully.
2. High Availability: Ensure your Istio control plane (istiod) and ingress gateways (istio-gateway pods) are deployed with multiple replicas across different availability zones for high availability.
3. Resource Limits: Set appropriate CPU and memory limits for Istio components and your application pods to prevent resource starvation or noisy neighbor issues.
4. Monitoring and Logging: Integrate Istio with your existing monitoring (Prometheus/Grafana) and logging (Loki/Fluentd/ELK) stacks. Leverage Istio’s observability features for traffic metrics, tracing, and access logs. Consider leveraging eBPF Observability with Hubble for even deeper network insights, especially if you’re using Cilium.
5. Security:
   • TLS/SSL: Configure TLS on your Gateway listeners for secure communication. You’ll typically use TLSRoute or specify TLS options directly in Gateway for HTTPS.
   • Authentication/Authorization: Leverage Istio’s security policies (AuthenticationPolicy, AuthorizationPolicy) to enforce mTLS and fine-grained access control.
   • Network Policies: While Istio handles L7, Kubernetes Network Policies provide L3/L4 firewall rules for pod-to-pod communication, adding another layer of defense.
   • Supply Chain Security: For container images and deployments, consider integrating Sigstore and Kyverno to ensure only trusted images run in your cluster.
6. Performance Testing: Thoroughly test your ingress and service mesh performance under load to identify bottlenecks and optimize configurations.
7. Cost Optimization: While not directly related to Gateway API, ensuring your underlying cluster resources are efficiently used is key. Tools like Karpenter for cost optimization can help manage node lifecycle based on demand.
8. GitOps: Manage your Gateway API and Istio configurations using GitOps principles (e.g., with Argo CD or Flux CD) for version control, auditing, and automated deployments.
9. Multi-Tenancy: If operating a multi-tenant cluster, use allowedRoutes.namespaces in your Gateway resources to restrict which namespaces can attach routes, enforcing clear separation of concerns.

Troubleshooting

1. Issue: Gateway status.addresses is <pending>.

   Explanation: This typically means the underlying Kubernetes Service of type LoadBalancer (created by Istio for the Gateway) has not yet been assigned an external IP by your cloud provider’s load balancer controller. For local clusters, this is expected without a local load balancer like MetalLB.

   Solution:

   • Cloud Provider: Wait a few minutes. If it persists, check your cloud provider’s load balancer quotas and logs. Ensure your cluster has the necessary IAM permissions for the load balancer controller.
   • Local Cluster (Kind/Minikube):
     • If using Kind, consider installing MetalLB.
     • Alternatively, use NodePort: kubectl get svc -n istio-system istio-gateway. Find the NodePort for port 80/443 and access it via NODE_IP:NODE_PORT. You might need to port-forward the NodePort to your local machine: kubectl port-forward svc/istio-gateway -n istio-system 8080:80 and then access via localhost:8080.
2. Issue: HTTPRoute status.parents[0].conditions shows Reason: NoMatchingParent or status: False for Accepted.

   Explanation: The HTTPRoute cannot attach to the specified Gateway. This usually means there’s a mismatch in the parentRefs or the Gateway’s allowedRoutes configuration.

   Solution:

   • Verify the name and namespace in HTTPRoute.spec.parentRefs exactly match the Gateway resource.
   • Check the Gateway.spec.listeners[].allowedRoutes configuration. If set to namespaces.from: Same, the HTTPRoute must be in the same namespace as the Gateway. For cross-namespace routing, it should be namespaces.from: All or namespaces.from: Selector with a matching label.
   • Ensure the GatewayClass (istio in our case) is correctly referenced in the Gateway.