DevOps Dictionary

Kubernetes Gateway API is a Kubernetes Application Programming Interface for defining how traffic enters a cluster and reaches Services. It gives platform teams a standard way to manage gateways, listeners, routing rules, and traffic policies using Kubernetes resources instead of vendor-specific ingress controller configuration.

What Kubernetes Gateway API does

Gateway API manages inbound service traffic, usually HTTP, HTTPS, TCP, TLS, or gRPC. It is commonly used to route external requests from a load balancer or proxy to Services running inside a Kubernetes cluster.

For example, you can define rules such as:

• Send api.example.com to the API Service.
• Send example.com/docs to a documentation frontend.
• Terminate TLS at the gateway using a configured certificate.
• Route gRPC traffic to a backend Service on a specific port.
• Allow one application team to manage routes without letting them change the shared gateway.

How it works

Gateway API uses Kubernetes custom resources. A controller, such as an ingress controller, cloud load balancer controller, or service mesh controller, watches these resources and configures the actual networking infrastructure.

The main resources are:

• GatewayClass: Defines the type of gateway implementation, such as a specific controller or cloud load balancer.
• Gateway: Represents an instance of traffic entry infrastructure. It defines listeners, ports, protocols, hostnames, and TLS settings.
• HTTPRoute: Defines HTTP routing rules, such as host matching, path matching, header matching, redirects, and backend Services.
• GRPCRoute: Defines routing rules for gRPC services.
• TCPRoute: Defines routing rules for raw TCP traffic.
• TLSRoute: Defines routing rules for TLS traffic without necessarily terminating TLS.
• ReferenceGrant: Allows safe cross-namespace references, such as a route in one namespace pointing to a Service in another namespace.

Simple example

A platform team can create a shared Gateway for HTTPS traffic on port 443. An application team can then create an HTTPRoute that attaches to that Gateway and routes traffic for api.example.com to its Kubernetes Service.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: platform
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: example-com-cert
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: apps
spec:
  parentRefs:
    - name: public-gateway
      namespace: platform
  hostnames:
    - "api.example.com"
  rules:
    - backendRefs:
        - name: api-service
          port: 8080

In this setup, the platform team owns the shared Gateway, while the application team owns the route for its service. This separation works well in multi-team clusters.

Common use cases

• North-south traffic routing: Route external traffic into Kubernetes Services.
• Shared platform gateways: Let a platform team manage gateway infrastructure while app teams manage their own routes.
• Advanced HTTP routing: Match on paths, headers, query parameters, methods, and hostnames.
• TLS termination: Configure HTTPS listeners and certificate references through Kubernetes resources.
• Multi-namespace routing: Support safer delegation between platform and application namespaces.
• Service mesh integration: Some service mesh implementations use Gateway API for ingress or mesh traffic configuration.

Gateway API vs Ingress

Kubernetes Ingress is the older built-in API for HTTP and HTTPS routing. It works well for simple routing, but many advanced features depend on controller-specific annotations.

Gateway API was designed to fix several common Ingress limitations:

• More expressive routing: Gateway API supports richer matching and routing models.
• Clearer ownership: Platform teams can own Gateways, while app teams own Routes.
• Better protocol support: Gateway API covers HTTP, gRPC, TLS, and TCP through separate route types.
• Fewer custom annotations: Many features are modeled as structured Kubernetes fields instead of provider-specific annotations.

Ingress is still widely used and supported. Gateway API is usually a better fit when you need shared gateways, advanced routing, or cleaner separation between infrastructure and application teams.

Gateway API vs Service type LoadBalancer

A Kubernetes Service of type LoadBalancer exposes one Service through an external load balancer. It is simple and useful, but it does not provide host-based or path-based routing by itself.

Gateway API can route many hostnames and paths through one gateway. For example, a single external load balancer can route api.example.com, admin.example.com, and example.com/app to different Services.

Benefits

• Standard Kubernetes API: Teams define traffic routing with Kubernetes manifests.
• Role separation: Platform teams can control shared infrastructure while developers manage app-specific routes.
• Portable configuration model: The same resource types can work across different controllers, though implementation details still matter.
• Cleaner routing rules: Routes are easier to review in Git than long annotation blocks.
• Better fit for GitOps: Gateway resources can be versioned, reviewed, and deployed like other Kubernetes objects.

Tradeoffs and limitations

• Controller support varies: Not every Gateway API controller supports every feature or route type.
• Migration takes planning: Moving from Ingress to Gateway API may require DNS, TLS, and load balancer changes.
• Operational ownership must be clear: Teams need to decide who manages GatewayClass, Gateway, certificates, and Routes.
• Cloud behavior can differ: Load balancer provisioning, static IPs, health checks, and TLS integration depend on the controller and cloud provider.

Where it fits in a DevOps workflow

Gateway API is often managed through GitOps, Helm, Kustomize, or Terraform-backed workflows. If your team manages Kubernetes manifests through infrastructure as code, the same review and deployment process can apply to Gateway API resources. For example, teams that deploy Kubernetes resources using Terraform can include Gateway and Route manifests in the same delivery flow.

Gateway API also pairs well with cloud infrastructure automation. If your gateway depends on cloud resources such as DNS records, certificates, or managed load balancers, tools like Crossplane can manage those dependencies. A related pattern is to deploy AWS resources using Crossplane on Kubernetes while keeping application routing inside the cluster API.

During cluster lifecycle work, check Gateway API versions, controller compatibility, and CRD upgrades. This is especially important during EKS, GKE, AKS, or self-managed Kubernetes upgrades. For practical planning, see these Kubernetes upgrade tips for startups.

Practical example

Imagine a startup running three services on Kubernetes:

• frontend-service for the web app.
• api-service for backend APIs.
• admin-service for internal admin users.

The platform team creates one public Gateway for HTTPS traffic. The application teams create separate HTTPRoutes:

• example.com routes to frontend-service.
• api.example.com routes to api-service.
• admin.example.com routes to admin-service, with extra access controls handled by the gateway controller or an adjacent security layer.

This keeps the shared entry point stable while letting each team change its own routing rules through pull requests.

Key takeaway

Kubernetes Gateway API is the modern Kubernetes model for managing traffic into clusters. It gives you structured gateway and routing resources, clearer team ownership, and stronger support for advanced traffic routing than traditional Ingress. It works best when your platform team standardizes the controller, ownership model, certificate process, and deployment workflow.