- Project Calico
- Products
- Solutions
- Learn
- Support
- Company
The Kubernetes Gateway API, a new open source project included within the official Kubernetes distribution, was released in November 2023. It is intended to provide a modern interface for managing service networking in Kubernetes environments, designed to overcome the limitations of the older Ingress API by offering more advanced routing capabilities and a more flexible architecture.
The Gateway API provides greater control over how traffic is managed and routed both within and outside of Kubernetes clusters, providing granular configurations for things like load balancing, traffic splitting, and cross-namespace routing.
The Gateway API also introduces a role-oriented architecture, which helps streamline collaboration between different teams such as infrastructure operators and application developers. This separation of concerns allows teams to manage their specific responsibilities, like defining gateways or routing policies, without interfering with each other.
You can get the Kubernetes Gateway API from the official repo here.
This is part of a series of articles about Kubernetes security.
In this article:
The Kubernetes Gateway API is built with several core principles that aim to enhance service networking while ensuring flexibility, control, and expressiveness. A key aspect of this API is its role-oriented architecture, which clearly delineates responsibilities across different personas within an organization. By assigning specific roles and resources, the API allows different teams, such as infrastructure operators and application developers, to collaborate efficiently while maintaining a clear separation of duties.
Portability is another design goal. Like the Ingress API it aims to replace, the Gateway API is built to be supported across various implementations, ensuring users can maintain flexibility in their network configurations without being tied to a specific vendor or solution. This universal specification also facilitates extensibility, as it allows for custom resources and extensions to be integrated at various levels, making it adaptable to diverse use cases.
The Gateway API also introduces expressiveness as a major improvement over ingress. It provides granular control over traffic routing, enabling configurations such as header-based routing and traffic splitting. Additionally, GatewayClasses allow for the formalization of load balancing types, making it easier for users to understand the available capabilities. Another key feature is cross-namespace support, which permits multiple teams to share infrastructure while maintaining separation through independent route resources.
For service meshes, the API supports east-west traffic routing via the GAMMA initiative. This allows routing policies to be applied directly to services, offering a unified way to manage both north-south (ingress) and east-west (service mesh) traffic with the same API, thus simplifying overall network management.
Source: Kubernetes
The Kubernetes Gateway API, API Gateway, and Kubernetes ingress serve different purposes in managing traffic, though they share similarities in routing requests within or outside Kubernetes clusters.
While both APIs handle incoming traffic, ingress is restricted to basic HTTP routing. It relies on annotations for advanced configurations, which can vary across implementations, leading to portability issues. In contrast, the Gateway API is a superset of ingress functionality, supporting more complex traffic management scenarios like load balancing, header-based routing, and cross-namespace routing, all with a consistent and vendor-neutral configuration.
Additionally, the Gateway API introduces a role-based architecture, separating concerns between infrastructure operators and application developers. This separation allows for more organized management of routing configurations and better support for large-scale, multi-team environments. Ingress lacks this separation of roles, making it less suitable for complex, multi-team deployments.
An API Gateway is typically used to manage external API traffic by offering features like rate limiting, authentication, authorization, and API request transformations. It serves as a central entry point for all API requests to a backend, handling traffic management and security at a more granular level. In Kubernetes, API Gateway implementations can be built using the Gateway API, providing the routing and traffic management features required for external APIs, while also allowing for deeper integration with Kubernetes-native constructs.
Whereas the Kubernetes Gateway API is a built-in Kubernetes API primarily focused on managing traffic within Kubernetes clusters (north-south or east-west traffic), an API Gateway offers more functionality for managing external API endpoints beyond simple traffic routing. However, by leveraging service meshes like Istio, the Gateway API can be extended to cover some API Gateway functionalities within Kubernetes environments.
The Kubernetes Gateway API focuses on separating responsibilities among different personas within an organization, ensuring efficient collaboration across teams. These personas typically include infrastructure operators, application developers, and platform engineers.
In this scenario, an application developer has built a microservice application that will be used by external clients. To make the application accessible via the URL https://my.application.com/, she collaborates with a colleague who is responsible for cluster setup. The cluster manager requests an infrastructure operator to provision a cluster with a GatewayClass resource named basic-gateway-class. The cluster is equipped with a gateway controller that manages traffic routing from outside the cluster to the developer’s microservice.
The cluster manager configures a Gateway resource named my-gateway, which listens for TLS traffic on port 443 and is associated with the basic-gateway-class. Once the gateway controller provisions a load balancer and allocates an IP address, the manager creates a DNS record to link the domain to the cluster.
The developer then writes HTTPRoute resources to define how traffic should be routed to the microservices. This setup enables centralized control of policies like TLS, while still allowing the developer to manage the routing logic independently.
This use case is similar to the basic north/south scenario but involves multiple application teams. The first team manages a storefront application in the “store” namespace, while the second team manages a website in the “site” namespace. Both teams deploy their workloads independently and configure their routing using HTTPRoute resources attached to the same gateway.
By sharing the Gateway resource, the cluster manager can enforce centralized policies like TLS for both applications, while the developers maintain control over the specific routing logic for their respective applications. This separation of concerns allows for efficient collaboration between teams without affecting the stability or security of the overall system.
Source: Kubernetes
In this scenario, the application already runs within a cluster that uses a GAMMA-compliant service mesh for east/west traffic routing. The developer needs to secure the service by rejecting incorrect URL paths and enforcing request timeouts. Since the cluster manager and infrastructure operator have already set up the service mesh, the developer doesn’t need their assistance.
The developer writes an HTTPRoute resource that defines the acceptable routes and request timeouts, which is directly linked to the application’s service. The service mesh automatically enforces the policies specified in the HTTPRoute, ensuring secure and efficient internal traffic routing. This enables the developer to implement custom routing policies within the cluster without delays or additional dependencies on the infrastructure team.
In my experience, here are tips that can help you make more effective use of the Kubernetes Gateway API:
While using the default GatewayClasses works for most cases, creating custom GatewayClasses allows you to tailor gateway behavior to your infrastructure’s specific needs. This can help enforce organization-wide policies like rate limiting, access control, or even connection limits.
Before fully rolling out new versions of your services, combine traffic mirroring and traffic splitting via HTTPRoute to shadow live production traffic to the new version. This ensures you can safely validate without fully committing to the new deployment.
If you manage multiple Kubernetes clusters, deploy the Gateway API in a multi-cluster environment for centralized management of traffic between clusters. This can improve scalability and resilience for cross-cluster traffic without needing an external load balancer or complicated configurations.
Although the Gateway API natively supports east-west traffic via service meshes, you can further customize your mesh setup using Custom Resource Definitions (CRDs) to extend traffic control and observability. This ensures deeper integration with service mesh-specific features like circuit breaking or mTLS.
Integrate the Gateway API with Kubernetes-native observability tools like Prometheus and Grafana to track key metrics such as response times, error rates, and traffic patterns. This helps ensure Service Level Objectives (SLOs) are met by adjusting routing and traffic policies dynamically.
The code in the examples below was shared in the official documentation for the Kubernetes API Gateway project.
A GatewayClass is a top-level resource that defines the configuration of gateways managed by a specific controller. Each GatewayClass is responsible for creating and managing Gateway resources, ensuring that traffic routing infrastructure adheres to the specifications of the class. This allows organizations to standardize and manage traffic configurations across different environments while maintaining flexibility in how gateways are implemented.
Here’s a basic example of a GatewayClass:
apiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: name: example-class spec: controllerName: example.com/gateway-controller
In this configuration, the controllerName specifies the controller that will manage this GatewayClass. Any Gateway that references this class will be managed by the controller, ensuring consistency in traffic management. This abstraction is particularly useful for large-scale Kubernetes environments, where multiple teams might need to create and manage gateways independently.
A Gateway represents an actual instance of traffic handling infrastructure, such as a load balancer, proxy, or router. It defines the points where the cluster will accept network traffic, which is then routed based on rules defined in associated route objects like HTTPRoute.
Here’s an example of a minimal Gateway configuration:
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
spec:
gatewayClassName: example-class
listeners:
- name: http
protocol: HTTP
port: 80
In this example, the Gateway is associated with the GatewayClass named example-class. The listeners field defines how the gateway handles incoming traffic—in this case, it listens for HTTP requests on port 80. When this gateway is instantiated, the controller assigns an address or hostname that can be used to route traffic.
The HTTPRoute resource defines how HTTP traffic is routed from the Gateway to backend services. This can include rules for matching URLs, headers, or methods, and directing traffic to different services based on these conditions. It allows for fine-grained traffic control, including load balancing and path-based routing.
Here’s an example of an HTTPRoute:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-httproute
spec:
parentRefs:
- name: example-gateway
hostnames:
- "www.example.com"
rules:
- matches:
- path:
type: PathPrefix
value: /login
backendRefs:
- name: example-svc
port: 8080
In this configuration, any HTTP requests that match the hostname www.example.com and the path /login will be routed to the service example-svc on port 8080. The parentRefs field connects this HTTPRoute to a specific gateway (in this case, example-gateway), ensuring the traffic from the gateway is routed based on the rules defined here.
This setup allows for very specific routing logic to be implemented, accommodating complex traffic requirements across multiple services.
Tigera’s commercial solutions provide Kubernetes security and observability for multi-cluster, multi-cloud, and hybrid-cloud deployments. Both Calico Enterprise and Calico Cloud provide the following features for security and observability:
Security
Observability
Next steps:
