When you deploy applications on Kubernetes, you need a way to route external HTTP and HTTPS traffic to the correct services. For a small application, a basic routing configuration may be enough. As the number of services grows, you may need path-based routing, hostname rules, TLS termination, traffic splitting, and clearer separation between platform and application teams.
Kubernetes Ingress has been used for years to manage HTTP and HTTPS access to services. However, the Ingress API has limitations when applications need more advanced routing and traffic management. The Kubernetes Gateway API addresses many of these requirements with a more expressive and extensible model.
Choosing between them is not simply a matter of selecting the newer option. Your decision depends on your existing cluster, ingress controller, routing requirements, and operational responsibilities.
This article compares Kubernetes Gateway API and Ingress, demonstrates their configurations, and explains when each approach makes sense.
What Is Kubernetes Ingress?
Kubernetes Ingress is an API resource that defines rules for routing external HTTP and HTTPS traffic to services inside a cluster.
For example, an application might expose two services:
/api routes requests to a backend API./ routes requests to a frontend application.
An Ingress resource describes these routing rules. An Ingress controller watches the resource and implements the required behavior.
Common controller choices include NGINX-based implementations and cloud-provider-specific controllers. Their supported features and configuration methods can differ.
Example: Create an Ingress Resource
Consider a cluster containing two services:
frontend-service on port 80backend-service on port 8080
The following Ingress resource routes requests based on their paths:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: application-ingress
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: backend-service
port:
number: 8080
- path: /
pathType: Prefix
backend:
service:
name: frontend-service
port:
number: 80
This configuration assumes that a compatible controller associated with the nginx IngressClass is installed and configured.
The /api path sends matching requests to the backend service, while other matching requests go to the frontend service. The controller must also be configured to expose the application through an appropriate external address.
Important: Creating an Ingress resource does not automatically make an application accessible from the internet. A compatible Ingress controller must be running and able to implement the resource.
What Is Kubernetes Gateway API?
Kubernetes Gateway API is a collection of resources for configuring network traffic routing in Kubernetes. It provides a more structured model for separating infrastructure responsibilities from application routing rules.
Its main resources include:
- GatewayClass: Identifies a class of gateways implemented by a controller.
- Gateway: Defines a gateway instance and its listeners.
- HTTPRoute: Defines HTTP routing rules, including matches and backend references.
- ReferenceGrant: Allows certain cross-namespace references when required and permitted.
Additional route types and capabilities are available depending on the Gateway API version and implementation.
A typical setup separates responsibilities. A platform team manages the gateway infrastructure and listeners, while application teams manage the routes that connect their applications to the gateway.
This model is particularly useful when multiple teams share the same cluster or gateway infrastructure.
Gateway API vs Ingress: Key Differences
Although both APIs can route HTTP traffic to Kubernetes services, they differ in their resource models and extensibility.
| Feature | Kubernetes Ingress | Kubernetes Gateway API |
|---|
| Main routing resource | Ingress | HTTPRoute and other route types |
| Infrastructure configuration | Controller-specific configuration often handles advanced needs | GatewayClass and Gateway provide dedicated resources |
| Separation of responsibilities | Possible, but often relies on controller-specific conventions | Explicit resource relationships support role separation |
| Basic host and path routing | Supported | Supported |
| Advanced traffic routing | Often depends on controller-specific annotations | Provides structured routing features, subject to implementation support |
| Traffic splitting | Usually controller-specific | Supports weighted backend references where implemented |
| Extensibility | Depends on controller behavior and configuration | Designed with extension points and additional route types |
| Existing ecosystem | Widely deployed | Adoption and support vary by controller and environment |
| Migration effort | No change for an existing working setup | Requires supported controllers, configuration, and testing |
Neither API guarantees every feature simply because a resource is accepted by Kubernetes. The controller implementing the API determines which capabilities are available and how they behave.
Configure a Gateway API Example
Suppose you want to route traffic to the same frontend and backend services used in the Ingress example.
A Gateway API configuration typically requires a supported Gateway API installation and a controller that implements the required resources.
Step 1: Define a Gateway
The following example defines an HTTP listener for the application hostname:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: application-gateway
namespace: default
spec:
gatewayClassName: example-gateway-class
listeners:
- name: http
hostname: app.example.com
port: 80
protocol: HTTP
allowedRoutes:
namespaces:
from: Same
The gatewayClassName value must match a GatewayClass provided by the installed controller. example-gateway-class is a placeholder, not a built-in class available in every cluster.
The listener accepts HTTP traffic for app.example.com. The allowedRoutes setting permits routes from the same namespace as the Gateway.
For a production environment, you might allow routes from selected namespaces instead. That choice should follow your cluster's ownership and security model.
Step 2: Define an HTTPRoute
Create an HTTPRoute to send API requests to the backend and other requests to the frontend.
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: application-route
namespace: default
spec:
parentRefs:
- name: application-gateway
hostnames:
- app.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /api
backendRefs:
- name: backend-service
port: 8080
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: frontend-service
port: 80
The parentRefs field connects the route to the Gateway. The hostnames field limits the route to the intended hostname, and the rules determine which service receives each request.
As with Ingress, the referenced services must exist and expose the specified ports.
Step 3: Apply and Inspect the Resources
Save the manifests and apply them:
kubectl apply -f gateway.yaml
kubectl apply -f route.yaml
Then inspect their status:
kubectl get gateway
kubectl get httproute
kubectl describe gateway application-gateway
kubectl describe httproute application-route
Check the conditions reported by the controller. A resource may exist in Kubernetes without being accepted or programmed successfully by the controller.
For example, an HTTPRoute may fail to attach because the Gateway does not allow routes from its namespace. A Gateway may also remain unprogrammed if the controller cannot provision or configure the required infrastructure.
The precise status conditions and troubleshooting steps depend on the implementation.
When Should You Choose Ingress?
Ingress remains a reasonable choice for applications that need straightforward HTTP and HTTPS routing.
Consider keeping Ingress when:
- Your existing controller already meets your routing requirements.
- Your application uses only hostname and path-based routing.
- Your team has established monitoring and operational procedures around its current controller.
- Your cloud platform or deployment tooling is built around an existing Ingress implementation.
- Migration would add complexity without solving a current problem.
A working Ingress deployment does not need to be replaced solely because Gateway API is newer.
However, review the controller-specific annotations used by your application. An Ingress resource that relies on custom rewrite rules, authentication, rate limiting, or other controller extensions may not behave the same way when migrated to another implementation.
When Should You Choose Gateway API?
Gateway API becomes more attractive when routing requirements grow or infrastructure responsibilities need clearer separation.
Consider it when:
Multiple Teams Share a Gateway
A platform team can manage Gateway resources and listeners, while application teams manage HTTPRoute resources for their services. Namespace permissions and route attachment policies can help define which teams may attach routes.
You Need Traffic Splitting
Gateway API supports weighted backend references for traffic distribution when the controller implements the capability.
For example, a route might direct most requests to a stable version and a smaller share to a new version. This can support controlled rollout strategies, although production canary deployments also require monitoring, rollback rules, and application-level validation.
Your Routing Requirements Are Expanding
If you repeatedly add controller-specific annotations to support increasingly complex routing, Gateway API may offer a clearer configuration model.
Before adopting it, confirm that your chosen controller supports the required features. Support can vary between implementations and releases.
You Want a More Explicit Resource Model
GatewayClass, Gateway, and route resources represent different responsibilities. This structure can make ownership and configuration easier to understand in larger Kubernetes environments.
Migration Considerations
Moving from Ingress to Gateway API is not necessarily a direct YAML conversion. The resource models differ, and controller-specific behavior may need to be redesigned.
Before migrating, review the following areas:
| Area | What to verify |
|---|
| Controller support | Confirm the controller implements the required Gateway API resources and features |
| Host and path routing | Compare current rules with the proposed HTTPRoute configuration |
| TLS certificates | Verify listener configuration, certificate references, and certificate management |
| Rewrites and redirects | Confirm equivalent support in the selected implementation |
| Authentication and rate limiting | Check whether the controller supports the required policies |
| Cross-namespace routing | Review namespace permissions and route attachment rules |
| Observability | Validate access logs, metrics, tracing, and alerting |
| Rollback | Keep a tested recovery plan for the existing routing configuration |
Do not assume that every Ingress annotation has a direct Gateway API equivalent. Some capabilities may be provided by implementation-specific policies or extensions rather than the core API.
A safer migration process starts with a non-production environment. Recreate the required routes, verify controller status, run HTTP tests, and compare behavior before directing production traffic to the new configuration.
Common Mistakes to Avoid
Installing Gateway API Resources Without a Controller
The API resource definitions and a compatible controller are separate requirements. Installing the definitions alone does not provide a functioning gateway implementation.
Assuming Every Controller Supports Every Feature
Gateway API defines common behavior, but implementation support varies. Check the controller's compatibility information and the status conditions of your resources.
Ignoring Namespace Boundaries
A route may be rejected if its namespace is not permitted by the Gateway listener. Cross-namespace backend references can also require additional authorization through resources such as ReferenceGrant.
Migrating Annotations Without Testing
Custom annotations may control behavior that is not represented in the original Ingress resource. Inventory these settings and verify their replacements before migration.
Treating Resource Creation as Successful Routing
A successful kubectl apply only confirms that Kubernetes accepted the resource request. It does not prove that traffic reaches the intended service. Inspect Gateway and route status, then test actual requests.
Best Practices for Production
Use the following practices when designing Kubernetes traffic routing:
- Choose based on requirements: Keep Ingress if it meets your needs; consider Gateway API when its resource model or routing features provide a clear benefit.
- Verify implementation support: Confirm that the selected controller supports the exact features you plan to use.
- Separate responsibilities: Define who manages gateways, listeners, and application routes.
- Apply least privilege: Restrict route attachment and cross-namespace references according to your security model.
- Test real traffic: Validate status codes, headers, redirects, TLS behavior, and backend selection.
- Monitor routing health: Track controller status, request errors, latency, and backend availability.
- Plan migrations carefully: Preserve rollback options until the new configuration has been validated under realistic conditions.
Advantages and Disadvantages
| Approach | Advantages | Disadvantages |
|---|
| Ingress | Familiar resource model, broad existing adoption, straightforward routing | Advanced features often rely on controller-specific extensions |
| Gateway API | Clearer separation of responsibilities, extensible resource model, structured routing capabilities | Requires a compatible controller and may involve migration work |
The best choice depends on your infrastructure and team. Ingress is often sufficient for simple applications, while Gateway API offers a more structured approach for environments with multiple teams and more demanding traffic-management requirements.
Summary
Kubernetes Ingress and Gateway API both help expose applications through HTTP and HTTPS routing, but they serve different operational needs.
Ingress remains a practical option for established deployments and straightforward routing. Gateway API provides dedicated resources for gateways and routes, making it useful when teams need clearer ownership, more expressive routing, or a path toward additional traffic-management capabilities.
Before choosing, check your controller's feature support, security requirements, and migration costs. Test the configuration in a non-production environment and verify actual traffic rather than relying only on successful resource creation.
The goal is not to adopt the newest API by default. It is to choose a routing model that your team can operate, secure, and maintain reliably.
Join the conversation! Your thoughts help the community grow.