--- title: Understand Gateway API --- # Understand Gateway API {#understand-gateway-api_{context}} To optimize network traffic management and implement routing policies in OpenShift Container Platform, use Gateway API. By adopting this community-managed Kubernetes mechanism, you can configure advanced routing at both the transport (L4) and application (L7) layers while leveraging various vendor-supported implementations to meet your specific networking requirements. A well-designed Gateway API deployment helps you achieve a portable, role-oriented routing infrastructure. To successfully plan your Gateway API implementation, review the following concepts: - Understand the benefits and limitations of Gateway API. - Review OpenShift Container Platform implementation specifics to avoid unsupported features. - Choose between shared or dedicated deployment topologies. > [!IMPORTANT] > Gateway API does not support user-defined networks (UDN). ## Gateway API benefits and limitations {#gateway-api-benefits-limitations_understand-gateway-api} To determine if Gateway API is the right routing solution for your cluster, review its benefits and limitations. The project is an effort to provide a standardized ecosystem by using a portable API with broad community support. Understanding these factors ensures your networking infrastructure aligns with your organizational needs and technical capabilities. ### Benefits {#gateway-api-benefits_understand-gateway-api} Gateway API provides the following benefits: - Portability: Where OpenShift Container Platform uses HAProxy to improve Ingress performance, Gateway API does not rely on vendor-specific annotations to provide certain behavior. To get comparable performance to HAProxy, the `Gateway` objects need to be horizontally scaled or their associated nodes need to be vertically scaled. - Separation of concerns: Gateway API uses a role-based approach to its resources, and more neatly fits into how a large organization structures its responsibilities and teams. Platform engineers might focus on `GatewayClass` resources, cluster administrators might focus on configuring `Gateway` resources, and application developers might focus on routing their services with `HTTPRoute` resources. - Extensibility: Additional functionality is developed as a standardized CRD. ### Limitations {#gateway-api-limitations_understand-gateway-api} Gateway API has the following limitations: - Version incompatibilities: The Gateway API ecosystem changes rapidly, and some implementations do not work with others because their featureset is based on differing versions of Gateway API. - Resource overhead: While more flexible, Gateway API uses multiple resource types to achieve an outcome. For smaller applications, the simplicity of traditional Ingress might be a better fit. - On-premise infrastructure dependencies: On-premise deployments, such as bare metal or VMware vSphere environments, do not automatically provision network load balancers or manage external DNS records. To use Gateway API on an on-premise platform, you must explicitly deploy a load balancer controller, such as MetalLB, and manually map your DNS records to the provisioned gateway address. ## Gateway API implementation specifics {#gateway-api-implementation-specifics_understand-gateway-api} To ensure interoperability between external vendor implementations and your networking infrastructure in OpenShift Container Platform, the Ingress Operator manages the lifecycle of Gateway API custom resource definitions (CRDs). Understanding how these CRDs are managed helps you prevent disrupted workloads and security issues caused by incompatible vendor fields. In some situations, Gateway API provides one or more fields that a vendor implementation does not support, but that implementation is otherwise compatible in schema with the rest of the fields. These "dead fields" can result in disrupted Ingress workloads, improperly provisioned applications and services, and security-related issues. Because OpenShift Container Platform uses a specific version of Gateway API CRDs, any use of third-party implementations of Gateway API must conform to the OpenShift Container Platform implementation to ensure that all fields work as expected. Any CRDs created within an OpenShift Container Platform 4.22 cluster are compatibly versioned and maintained by the Ingress Operator. If CRDs are already present but were not previously managed by the Ingress Operator, the Ingress Operator checks whether these configurations are compatible with Gateway API version supported by OpenShift Container Platform, and creates an admin-gate that requires your acknowledgment of CRD succession. > [!IMPORTANT] > If you are updating your cluster from a previous OpenShift Container Platform version that contains Gateway API CRDs, change those resources so that they exactly match the version supported by OpenShift Container Platform. Otherwise, you cannot update your cluster because those CRDs were not managed by OpenShift Container Platform, and could contain functionality that is unsupported by Red Hat. ### Gateway API CRDs for `gateway.networking.x-k8s.io` {#gateway-api-x-k8s-io-crds_understand-gateway-api} In previous versions of OpenShift Container Platform, cluster security policies blocked the deployment of the Gateway API CRD for `gateway.networking.x-k8s.io`. Starting in OpenShift Container Platform 4.22, this restriction is removed, and you can deploy that CRD. > [!NOTE] > Experimental Gateway API CRDs in the `gateway.networking.k8s.io` group remain restricted. > > You can install the `gateway.networking.x-k8s.io` CRD and related objects on the cluster because they are no longer blocked. The built-in Gateway API implementation managed by the Ingress Operator does not reconcile those objects in OpenShift Container Platform. Use a compatible third-party Gateway implementation if you need those APIs reconciled. ## Gateway API deployment topologies {#gateway-api-deployment-topologies_understand-gateway-api} To effectively organize and secure your routing infrastructure, you must choose an appropriate deployment topology for your cluster. Gateway API is designed to accommodate two topologies: shared gateways or dedicated gateways. You can choose a topology based on its own advantages and different security implications. ### Dedicated gateway {#dedicated-gateway_understand-gateway-api} Routes and any load balancers or proxies are served from the same namespace. The `Gateway` object restricts routes to a particular application namespace. This is the default topology when deploying a Gateway API resource in OpenShift Container Platform. The following example shows a dedicated `Gateway` resource, `fin-gateway`: ```yaml {title="Example dedicated Gateway resource"} apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: fin-gateway namespace: openshift-ingress spec: gatewayClassName: openshift-default listeners: - name: http protocol: HTTP port: 80 hostname: "*.example.com" ``` If you do not set `spec.listeners[].allowedRoutes` for a `Gateway` resource, the system implicitly sets the `namespaces.from` field to the value of `Same`. The following example shows the associated `HTTPRoute` resource, `sales-db`, which attaches to the dedicated `Gateway` object: ```yaml {title="Example HTTPRoute resource"} apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: sales-db namespace: openshift-ingress spec: parentRefs: - name: fin-gateway hostnames: - sales-db.example.com rules: - backendRefs: - name: sales-db port: 8080 ``` The `HTTPRoute` resource must have the name of the `Gateway` object as the value for its `parentRefs` field to attach to the gateway. The system implicitly assumes that the route exists in the same namespace as the `Gateway` object. ### Shared gateway {#shared-gateway_understand-gateway-api} Routes are served from multiple namespaces or multiple hostnames. The `Gateway` object allows routes from application namespaces by using the `spec.listeners.allowedRoutes.namespaces` field. The following example shows a `Gateway` resource, `devops-gateway`, that has a `spec.listeners.allowedRoutes.namespaces` label selector set to match any namespaces containing `shared-gateway-access: "true"`: ```yaml {title="Example shared Gateway resource"} apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: devops-gateway namespace: openshift-ingress spec: gatewayClassName: openshift-default listeners: - name: http protocol: HTTP port: 80 hostname: "*.example.com" allowedRoutes: namespaces: from: Selector selector: matchLabels: shared-gateway-access: "true" ``` The following examples show the allowed namespaces for the `devops-gateway` resource: ```yaml {title="Example Namespace resources"} apiVersion: v1 kind: Namespace metadata: name: dev labels: shared-gateway-access: "true" --- apiVersion: v1 kind: Namespace metadata: name: ops labels: shared-gateway-access: "true" ``` In this example, two `HTTPRoute` resources, `dev-portal` and `ops-home`, are in different namespaces but are attached to the shared gateway: ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: dev-portal namespace: dev spec: parentRefs: - name: devops-gateway namespace: openshift-ingress rules: - backendRefs: - name: dev-portal port: 8080 --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: ops-home namespace: ops spec: parentRefs: - name: devops-gateway namespace: openshift-ingress rules: - backendRefs: - name: ops-home port: 8080 ``` With a shared gateway topology, the routes must specify the namespace of the `Gateway` object it wants to attach to. Multiple `Gateway` objects can be deployed and shared across namespaces. When there are multiple shared gateways, this topology becomes conceptually similar to Ingress Controller sharding.