Kubernetes Gateway API vs Ingress: Which One Should You Use?

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 80
• backend-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.

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:

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

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.