Introduction to Gateway API

What is Gateway API?

Gateway API is the next-generation standard for Kubernetes service networking. It's designed to replace and improve upon the Ingress resource, providing a more expressive, extensible, and role-oriented model for managing traffic in Kubernetes clusters.

Think of Gateway API as the evolution of Ingress Controllers - it solves many of the limitations that Ingress resources have, especially when using Nginx Ingress Controllers.

Why Gateway API Exists

Gateway API was created to solve fundamental limitations of the Ingress API that became apparent as Kubernetes networking evolved. It was designed as the next-generation standard to address issues that Ingress controllers (like Nginx Ingress) struggled with.

Limitations of Ingress Controllers (Nginx Ingress)

If you've worked with Nginx Ingress Controllers, you've likely encountered these challenges:

1. Single Resource for Everything: All configuration goes into one Ingress resource
2. Vendor-Specific Annotations: Advanced features require Nginx-specific annotations like:
   • nginx.ingress.kubernetes.io/rewrite-target
   • nginx.ingress.kubernetes.io/canary
   • nginx.ingress.kubernetes.io/rate-limit
3. Limited Role Separation: Infrastructure and application teams often need to modify the same resource
4. Portability Issues: Annotations don't work across different Ingress implementations
5. Limited Expressiveness: Hard to express complex routing rules, traffic splitting, and policies

How Gateway API Solves These Problems

Gateway API addresses these limitations by:

1. Role-Oriented Design: Separates infrastructure (Gateway) from application (HTTPRoute) concerns
2. Standardized API: Works across different implementations (Nginx, Istio, Contour, etc.)
3. More Expressive: Native support for advanced routing, traffic splitting, and policies
4. Extensible: Policy attachments and extension points for custom features
5. Multi-Protocol: Gateway API specification supports HTTP, TCP, UDP, and TLS routing (implementation support varies - see provider docs)

Note: This site focuses on NGINX Gateway Fabric (NGF), which supports HTTP and HTTPS protocols only. Other Gateway API implementations may support additional protocols like TCP, UDP, or TLS passthrough.

Architecture Comparison

The diagram below shows a side-by-side comparison of Nginx Ingress Controller (traditional approach) and Gateway API (modern approach). This visual comparison highlights the key architectural differences and improvements.

Key Differences:

• Nginx Ingress: Uses a single Ingress resource with vendor-specific annotations
• Gateway API: Separates concerns with Gateway (infrastructure) and HTTPRoute (application)

See the interactive diagram below for a visual comparison.

Key Benefits

1. Role Separation

Nginx Ingress:

• Both infrastructure and application teams modify the same Ingress resource
• Can lead to conflicts and permission issues

Gateway API:

• Infrastructure team manages Gateway (ports, TLS, infrastructure)
• Application team manages HTTPRoute (routing rules, backends)
• Clear separation of concerns

2. Portability

Nginx Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/rate-limit: "100"

These annotations only work with Nginx Ingress!

Gateway API:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
spec:
  filters:
    - type: URLRewrite

This works with any Gateway API implementation!

3. Better Expressiveness

Nginx Ingress:

• Traffic splitting requires canary annotations
• Header-based routing needs complex annotations
• Limited support for advanced matching

Gateway API:

• Native weighted routing in backendRefs
• Built-in header, query parameter, and method matching
• Rich filter system for request/response modifications

When to Use Gateway API vs Ingress

Use Gateway API When:

• ✅ You're using Ingress NGINX (retiring March 2026 - migration recommended)
• ✅ You need advanced routing features (traffic splitting, header matching)
• ✅ You want portability across different implementations
• ✅ You have multiple teams (infrastructure vs application)
• ✅ You need fine-grained policy control
• ✅ You're starting a new project
• ✅ You want a future-proof solution with active development

Use Ingress When:

• ⚠️ Only if you're using a non-NGINX Ingress controller that will continue to be maintained
• ⚠️ Your cluster doesn't support Gateway API yet (consider upgrading)
• ⚠️ You have simple routing needs and are using a maintained Ingress controller

Note: If you're currently using Ingress NGINX, you should plan to migrate to Gateway API before March 2026. SIG Network recommends Gateway API as the preferred migration path.

Gateway API Versions

Gateway API has evolved through several versions:

v1alpha2 (Early)

• Initial experimental release
• Basic routing features
• Limited implementation support

v1beta1 (Stable Beta)

• More stable API
• Better implementation support
• Common features standardized

v1 (Current Stable)

• Production-ready
• Core features are stable
• Widely supported by implementations

Note: Always check which version your Gateway API implementation supports. Most modern implementations support v1beta1 or v1.

Implementation Providers

Gateway API is a standard, not a specific implementation. You can use it with:

• Nginx Gateway Fabric: Nginx's official Gateway API implementation
• Istio: Service mesh with Gateway API support
• Contour: Envoy-based Gateway API implementation
• Kong: API gateway with Gateway API support
• Traefik: Cloud-native router with Gateway API support

Next Steps

Now that you understand what Gateway API is and why it exists, let's dive into the core concepts:

👉 Next: Core Concepts →

Related Examples

• See 01 Basic Setup for basic Gateway API setup
• Compare with ingress-equivalent.yaml to see the difference