Istio + Gateway API: Master Service Mesh

Introduction

In the evolving landscape of Kubernetes networking, managing ingress traffic and service-to-service communication efficiently and securely is paramount. For years, Kubernetes Ingress has been the de-facto standard for exposing HTTP/S routes to services, but its limitations in expressiveness and vendor-specific annotations often led to complex configurations and a lack of portability. Enter the Kubernetes Gateway API, a more powerful, flexible, and extensible alternative designed to address these challenges. The Gateway API provides a role-oriented design, separating infrastructure concerns from application routing, making it easier for platform operators to define shared gateways and for application developers to configure their routes.

While the Gateway API defines the primitives for traffic routing, it needs an implementation to bring it to life. This is where service meshes like Istio shine. Istio is a robust, open-source service mesh that provides a comprehensive set of features for traffic management, security, and observability. By integrating the Gateway API with Istio, you can leverage Istio’s advanced capabilities—such as L7 traffic routing, fault injection, circuit breaking, and mTLS—through the standardized and portable Gateway API resources. This combination offers the best of both worlds: a declarative, role-based API for ingress and internal traffic management, backed by a production-grade service mesh. For a deeper dive into migrating from Ingress to Gateway API, check out our Kubernetes Gateway API vs Ingress: The Complete Migration Guide.

# Install Istio with Gateway API support
istioctl install --set profile=default -y --set values.pilot.env.GATEWAY_API_ENABLED=true

# Deploy a Gateway
kubectl apply -f https://raw.githubusercontent.com/kubezilla/examples/main/istio-gateway-api/gateway.yaml

# Deploy a sample application
kubectl apply -f https://raw.githubusercontent.com/kubezilla/examples/main/istio-gateway-api/httpbin.yaml

# Deploy an HTTPRoute
kubectl apply -f https://raw.githubusercontent.com/kubezilla/examples/main/istio-gateway-api/httproute.yaml

# Get Gateway address
kubectl get gateway httpbin-gateway -n default -o jsonpath='{.status.addresses[0].value}'

# Test routing
curl -H "Host: httpbin.example.com" http://<GATEWAY_IP>/headers

Prerequisites

Before we dive into the integration, ensure you have the following:

• Kubernetes Cluster: A running Kubernetes cluster (v1.20+ recommended for Gateway API). You can use Minikube, Kind, or any cloud provider’s managed Kubernetes service (EKS, GKE, AKS).
• kubectl: The Kubernetes command-line tool, configured to connect to your cluster. Refer to the official Kubernetes documentation for installation instructions.
• istioctl: The Istio command-line tool. Download and install it from the Istio releases page.
• Basic understanding of Kubernetes concepts: Pods, Deployments, Services, and Namespaces.
• Familiarity with Istio concepts: Gateways, VirtualServices (though we’ll use Gateway API here), and basic traffic management. For a deeper dive into Istio, consider our Istio Ambient Mesh Production Guide.

Step-by-Step Guide

1. Install Istio with Gateway API Support

The first step is to install Istio on your Kubernetes cluster, ensuring that Gateway API support is explicitly enabled. While newer Istio versions often have this enabled by default or via a specific profile, it’s good practice to confirm. We’ll use istioctl for a straightforward installation.

The --set values.pilot.env.GATEWAY_API_ENABLED=true flag is crucial here. It tells Istio’s Pilot component to enable the necessary controllers to watch and reconcile Gateway API resources like Gateway and HTTPRoute. Without this, Istio will not process these resources, and your traffic routing will not work as expected. We’re also using the default profile, which provides a good balance of features for most use cases.

istioctl install --set profile=default -y --set values.pilot.env.GATEWAY_API_ENABLED=true

Verify: After the installation completes, you should see output similar to this, indicating that Istio has been successfully installed.

✔ Istio core installed
✔ Istiod installed
✔ Egress gateways installed
✔ Ingress gateways installed
✔ Installation complete

You can also check the status of Istio pods in the istio-system namespace:

kubectl get pods -n istio-system

Expected Output:

NAME                                    READY   STATUS    RESTARTS   AGE
istio-ingressgateway-67b789d79c-abcde   1/1     Running   0          2m
istiod-7b89c7d8f-fghij                   1/1     Running   0          2m

2. Deploy a Gateway Resource

The Gateway resource in the Gateway API acts as the entry point for traffic into your cluster. It defines the listener ports and protocols, much like an Ingress Controller. When using Istio, the Gateway resource references an Istio-managed ingress gateway deployment. This separation allows platform operators to define shared gateways that application teams can then attach their routes to.

In this example, we’re creating a Gateway named httpbin-gateway that listens on port 80 for HTTP traffic. The gatewayClassName: istio specifies that this Gateway should be managed by Istio’s Gateway controller. The spec.addresses field allows you to specify a fixed IP address or hostname for the gateway, though in many cloud environments, this will be dynamically provisioned. The spec.listeners define the ports and protocols the gateway will expose. We’re creating a simple HTTP listener.

# gateway.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: httpbin-gateway
  namespace: default
spec:
  gatewayClassName: istio
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All

kubectl apply -f gateway.yaml

Verify: Check the status of the Gateway. It should eventually show an address assigned, indicating that Istio has provisioned an ingress gateway for it.

kubectl get gateway httpbin-gateway -n default

Expected Output:

NAME              CLASS   ADDRESS         PROGRAMMED   AGE
httpbin-gateway   istio   192.168.1.100   True         30s

Note: The ADDRESS will be an external IP or hostname provided by your cloud provider or local Kubernetes setup. This is the IP you’ll use to access your services.

3. Deploy a Sample Application

To demonstrate routing, we need a backend service. We’ll use the popular httpbin.org application, which is excellent for testing HTTP requests and responses. This application will be deployed in the default namespace.

This YAML defines a Deployment for the httpbin application and a corresponding Service to expose it within the cluster. Istio will automatically inject a sidecar proxy into the httpbin pod because the default namespace is typically enabled for automatic sidecar injection (or you can manually label it with istio-injection=enabled).

# httpbin.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin
  namespace: default
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
  namespace: default
spec:
  ports:
  - name: http
    port: 8000
    targetPort: 80
  selector:
    app: httpbin

kubectl apply -f httpbin.yaml

Verify: Ensure the httpbin pod and service are running correctly.

kubectl get pods -l app=httpbin -n default
kubectl get service httpbin -n default

Expected Output:

NAME                      READY   STATUS    RESTARTS   AGE
httpbin-74b5c777d-ghjkl   2/2     Running   0          40s

NAME      TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
httpbin   ClusterIP   10.43.123.456   <none>        8000/TCP   40s

Notice the 2/2 in the pod status, indicating that both the application container and the Istio sidecar proxy are running.

4. Deploy an HTTPRoute Resource

The HTTPRoute resource defines how HTTP requests are routed from a Gateway to backend services. This is where you specify hostnames, paths, headers, and other matching criteria, along with the backend services to which traffic should be directed. Multiple HTTPRoute resources can attach to a single Gateway, enabling multi-tenancy and delegated routing.

Our HTTPRoute will attach to the httpbin-gateway we created earlier. It specifies a hostname (httpbin.example.com) and defines a single rule that matches all requests (path.type: PathPrefix with path.value: /) and forwards them to the httpbin service on port 8000. This demonstrates a basic but complete routing configuration.

# httproute.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httpbin-route
  namespace: default
spec:
  parentRefs:
  - name: httpbin-gateway
    namespace: default
  hostnames:
  - "httpbin.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: httpbin
      port: 8000

kubectl apply -f httproute.yaml

Verify: Check the status of the HTTPRoute. It should show that it’s accepted by the Gateway.

kubectl get httproute httpbin-route -n default

Expected Output:

NAME            HOSTNAMES             AGE
httpbin-route   ["httpbin.example.com"]   10s

You can get more detailed status information:

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

Look for a status condition like Accepted: True and a ParentRef status indicating it’s attached to your Gateway.

5. Test Traffic Routing

Now that everything is set up, let’s test if our traffic is correctly routed through the Istio Gateway API. We’ll need the external IP address of our Gateway and then use curl to make a request, ensuring we set the Host header to match the hostname specified in our HTTPRoute.

First, retrieve the external IP of your Istio ingress gateway:

export GATEWAY_IP=$(kubectl get gateway httpbin-gateway -n default -o jsonpath='{.status.addresses[0].value}')
echo "Gateway IP: $GATEWAY_IP"

Expected Output:

Gateway IP: 192.168.1.100 # (Your actual IP will vary)

Now, send a request to the httpbin service through the Gateway, ensuring to set the Host header:

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

Expected Output: You should see a JSON response from the httpbin service, including the headers sent. This confirms that the request was successfully routed through the Istio Gateway and the HTTPRoute to your backend service.

{
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.example.com",
    "User-Agent": "curl/7.81.0",
    "X-Forwarded-For": "10.42.0.1",
    "X-Forwarded-Proto": "http",
    "X-Request-Id": "..."
  }
}

Congratulations! You have successfully integrated the Kubernetes Gateway API with Istio to manage ingress traffic to your services.

Production Considerations

While the basic setup is functional, deploying this in a production environment requires additional considerations:

• TLS/SSL Termination: For production, you’ll undoubtedly need HTTPS. The Gateway API supports TLS configuration directly within the Gateway resource, allowing you to specify TLS certificates (e.g., from Kubernetes Secrets) for secure communication. You can also integrate with cert-manager for automated certificate provisioning.
• Advanced Traffic Management: Istio, combined with Gateway API, unlocks powerful traffic management features. Explore HTTPRoute capabilities like traffic splitting for A/B testing or canary deployments, fault injection, and request retries.
• Observability: Leverage Istio’s built-in telemetry for metrics, logs, and traces. Integrate with tools like Prometheus, Grafana, and Jaeger to monitor your gateway and services. For advanced eBPF-based observability, consider tools like Hubble, which we discuss in our eBPF Observability: Building Custom Metrics with Hubble guide.
• Security: Implement Istio’s security features such as Mutual TLS (mTLS) for all service-to-service communication, authorization policies to control access, and rate limiting. For more on securing your clusters, refer to our Kubernetes Network Policies: Complete Security Hardening Guide and for supply chain security, Securing Container Supply Chains with Sigstore and Kyverno.
• High Availability: Ensure your Istio ingress gateway deployments are configured for high availability with multiple replicas and appropriate resource limits.
• Resource Management: Define proper resource requests and limits for Istio components (istiod, ingress gateway) and your application pods to prevent resource starvation and ensure stable performance.
• Cost Optimization: Monitor your cluster’s resource usage. Tools like Karpenter can help optimize node provisioning and reduce costs, especially for dynamic workloads.
• Custom Resources (CRDs): Be aware that Istio still uses its own CRDs (like VirtualService and DestinationRule) for features not yet covered by the Gateway API. The Gateway API is still evolving, and you might need a hybrid approach for complex scenarios.
• Version Management: Keep your Istio and Kubernetes Gateway API versions up to date. Regularly check for new releases and security patches.

Troubleshooting

1. Gateway Status Not Programmed: True or Address Missing

   Issue: The Gateway resource remains in a pending state or doesn’t get an external IP.

   Solution:

   • Ensure Istio is correctly installed and Gateway API support is enabled. Check istiod and istio-ingressgateway logs in the istio-system namespace for errors.
   • Verify the gatewayClassName: istio is correctly set.
   • In cloud environments, external IPs might take some time to provision. If using a local cluster (Minikube/Kind), ensure your environment supports LoadBalancer services or use NodePort. For Minikube, you might need to run minikube tunnel in a separate terminal.

   kubectl logs -n istio-system -l app=istiod
   kubectl logs -n istio-system -l app=istio-ingressgateway
   kubectl describe gateway httpbin-gateway -n default
   

2. HTTPRoute Status Not Accepted

   Issue: The HTTPRoute resource is not being accepted by the Gateway, or its status shows warnings/errors.

   Solution:

   • Check the parentRefs in your HTTPRoute to ensure they correctly point to your Gateway name and namespace.
   • Verify that the Gateway has allowedRoutes.namespaces.from: All or specifies the namespace where your HTTPRoute resides.
   • Inspect the HTTPRoute status for detailed error messages.

   kubectl describe httproute httpbin-route -n default
   

3. curl Command Fails or Returns 404/503

   Issue: Requests to the Gateway IP with the correct Host header result in a 404 Not Found or 503 Service Unavailable.

   Solution:

   • 404 Not Found:
     • Ensure the Host header in your curl command exactly matches a hostname defined in your HTTPRoute.
     • Verify the path matching in your HTTPRoute. Is the requested path covered by the route?
   • 503 Service Unavailable:
     • Check if your backend service (httpbin in this case) is running and healthy.
     • Ensure the backendRefs.name and port in your HTTPRoute correctly point to your service.
     • Verify that the Istio sidecar is injected into your application pods (kubectl get pods -n default -l app=httpbin should show 2/2 containers).
     • Check Istio’s proxy logs for routing errors: kubectl logs -f $(kubectl get pod -l app=istio-ingressgateway -n istio-system -o jsonpath='{.items[0].metadata.name}') -c istio-proxy -n istio-system.
4. Traffic Not Reaching Application (Timeout)

   Issue: Requests time out before reaching the application.

   Solution:

   • Check network connectivity to the Gateway IP. Can you ping it? (Though ping might be blocked).
   • Verify any network policies or firewalls that might be blocking traffic to the ingress gateway. For more details, see our Network Policies Security Guide.
   • If using a CNI like Cilium, ensure it’s not interfering with Istio’s traffic redirection. For advanced Cilium configurations, check out Cilium WireGuard Encryption.
5. Istio Sidecar Injection Issues

   Issue: Application pods are running but only show 1/1 containers, indicating the Istio sidecar was not injected.

   Solution:

   • Ensure the namespace where your application is deployed is labeled for Istio injection: kubectl get namespace default -L istio-injection. If not, label it: kubectl label namespace default istio-injection=enabled and then redeploy your application.
   • Check istiod logs for issues related to webhook injection.

FAQ Section

1. What is the main difference between Kubernetes Ingress and Gateway API?

   The Gateway API is a successor to Ingress, offering a more expressive, extensible, and role-oriented design. Ingress is primarily for HTTP/S routing, while Gateway API supports more protocols (TCP, TLS Passthrough) and allows for more advanced traffic management features out-of-the-box, without relying on vendor-specific annotations. It separates concerns between infrastructure providers (GatewayClass, Gateway) and application developers (HTTPRoute, TCPRoute, etc.). For a detailed comparison, see our Kubernetes Gateway API vs Ingress: The Complete Migration Guide.

2. Why integrate Gateway API with Istio?

   The Gateway API defines the “what” (how traffic should be routed), and Istio provides the “how” (the actual implementation). By integrating, you get the standardized, portable, and role-based API of Gateway API combined with Istio’s powerful service mesh features like advanced L7 traffic management, mTLS, authorization policies, and comprehensive observability. It centralizes ingress and internal mesh traffic management under a single, unified control plane.

3. Can I use Gateway API for internal service-to-service routing within the mesh?

   Yes, absolutely! While often showcased for ingress, the Gateway API is designed to manage traffic both at the cluster edge (ingress) and within the cluster (mesh internal traffic). You can define internal Gateways and attach routes to them for fine-grained control over inter-service communication, including advanced routing, retries, and circuit breaking.

4. Is Gateway API production-ready?

   The Gateway API has reached GA (General Availability) for its core resources (GatewayClass, Gateway, HTTPRoute) as of Kubernetes v1.26. This means it’s stable and recommended for production use. Implementations like Istio, NGINX, and others are actively supporting and developing against it.

5. What if I need features not yet supported by Gateway API but available in Istio’s CRDs (e.g., VirtualService)?

   The Gateway API is still evolving, and some advanced Istio features (like certain types of fault injection, advanced load balancing, or specific outlier detection configurations) might not have direct Gateway API equivalents yet. In such cases, you can use a hybrid approach: use Gateway API for your primary ingress and routing, and then apply Istio’s native VirtualService and DestinationRule resources to the backend services for the more granular, mesh-specific controls. Istio’s Gateway API implementation is designed to work alongside its traditional CRDs.

Cleanup Commands

To remove all resources created during this tutorial, execute the following commands:

# Delete HTTPRoute
kubectl delete -f httproute.yaml

# Delete sample application
kubectl delete -f httpbin.yaml

# Delete Gateway
kubectl delete -f gateway.yaml

# Uninstall Istio (This will remove the istio-system namespace and all Istio components)
istioctl uninstall -y --purge

# Remove Istio injection label from namespace if applied manually
kubectl label namespace default istio-injection-

# Optional: Delete the istio-system namespace if it persists
kubectl delete namespace istio-system

Next Steps / Further Reading

You’ve successfully integrated Gateway API with Istio! Here are some next steps to deepen your understanding and explore more advanced features:

• Explore more advanced HTTPRoute features: Learn about header matching, query parameter matching, traffic splitting, and more in the Gateway API documentation.
• Implement TLS: Secure your ingress with HTTPS by configuring TLS certificates in your Gateway resource.
• Experiment with other Gateway API resources: Investigate TCPRoute, TLSRoute, and UDPRoute for non-HTTP traffic.
• Dive deeper into Istio’s traffic management: Explore VirtualServices and DestinationRules for fine-grained control over internal mesh traffic, even if you’re primarily using Gateway API for ingress.
• Service Mesh Observability: Set up Prometheus, Grafana, and Jaeger to gain deep insights into your service mesh traffic and performance.
• Istio Security: Implement authorization policies and mTLS for robust security within your mesh.
• Check out the official Istio Gateway API documentation for more examples and best practices.

Conclusion

The integration of the Kubernetes Gateway API with Istio marks a significant leap forward in managing ingress and internal traffic within your Kubernetes clusters. By embracing the Gateway API’s role-oriented design, you gain a more standardized, portable, and expressive way to define your routing rules, while Istio provides the powerful, production-grade implementation details for traffic management, security, and observability. This combination empowers both platform operators and application developers, simplifying complex networking configurations and paving the way for more resilient and scalable microservice architectures. As the Kubernetes ecosystem continues to evolve, the Gateway API with Istio is poised to become the cornerstone of modern cloud-native networking.