OSDOCS-13509: add assembly, topic map, and concept

_topic_maps/_topic_map.yml

@@ -1705,6 +1705,9 @@ Topics:
   - Name: Allocating load balancers to specific subnets
     File: allocating-load-balancers
     Distros: openshift-enterprise,openshift-origin
+  - Name: Gateway API with OpenShift Container Platform networking
+    File: ingress-gateway-api
+    Distros: openshift-enterprise
   # Kubernetes NMState (TECHNOLOGY PREVIEW)
 - Name: Kubernetes NMState
   Dir: k8s_nmstate

modules/nw-ingress-gateway-api-deployment-topologies.adoc

@@ -0,0 +1,138 @@
+// Modules included in the following assemblies:
+//
+// * networking/gateway-api.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-ingress-gateway-api-deployment_{context}"]
+= Gateway API deployment topologies
+
+Gateway API is designed to accomodate two topologies: shared gateways or dedicated gateways. Each topology has its own advantages and different security implications.
+
+Dedicated gateway:: 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 {product-title}.
+
+Shared gateway:: Routes are served from multiple namespaces or with multiple hostnames. The `Gateway` object filters allow routes from application namespaces by using the `spec.listeners.allowedRoutes.namespaces` field.
+
+[id="dedicated-gateway-example_{context}"]
+== Dedicated gateway example
+The following example shows a dedicated `Gateway` resource, `fin-gateway`:
+
+.Example dedicated `Gateway` resource
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: fin-gateway
+  namespace: openshift-ingress
+spec:
+  listeners: <1>
+  - name: http
+    protocol: HTTP
+    port: 8080
+    hostname: "example.com"
+----
+<1> Creating a `Gateway` resource without setting `spec.listeners[].allowedRoutes` results in implicitly setting the `namespaces.from` field to have the value `Same`.
+
+The following example shows the associated `HTTPRoute` resource, `sales-db`, which attaches to the dedicated `Gateway` object:
+
+.Example `HTTPRoute` resource
+[source,yaml]
+----
+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 in order to attach to the gateway. Implicitly, the route is assumed to be in the same namespace as the `Gateway` object.
+
+[id="shared-gateway-example_{context}"]
+== Shared gateway example
+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"`:
+
+.Example shared `Gateway` resource
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: devops-gateway
+  namespace: openshift-ingress
+listeners:
+  - name: https
+    protocol: HTTPS
+    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:
+
+.Example `Namespace` resources
+[source,yaml]
+----
+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:
+
+[source,yaml]
+----
+apiVersion: 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: 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.
+

modules/nw-ingress-gateway-api-implementation.adoc

@@ -0,0 +1,19 @@
+// Modules included in the following assemblies:
+//
+// * networking/gateway-api.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-ingress-gateway-api-implementation_{context}"]
+= Gateway API implementation for {product-title}
+
+The Ingress Operator manages the lifecycle of Gateway API CRDs in a way that enables other vendor implementations to make use of CRDs defined in an {product-title} cluster.
+
+In some situations, the 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 {product-title} uses a specific version of Gateway API CRDs, any use of third-party implementations of Gateway API must conform to the {product-title} implementation to ensure that all fields work as expected.
+
+Any CRDs created within an {product-title} {product-version} 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 the Gateway API version supported by {product-title}, and creates an admin-gate that requires your acknowledgment of CRD succession.
+
+[IMPORTANT]
+====
+If you are updating your cluster from a previous {product-title} version that contains Gateway API CRDs change those resources so that they exactly match the version supported by {product-title}. Otherwise, you cannot update your cluster because those CRDs were not managed by {product-title}, and could contain functionality that is unsupported by Red{nbsp}Hat.
+====
+

modules/nw-ingress-gateway-api-overview.adoc

@@ -0,0 +1,36 @@
+// Modules included in the following assemblies:
+//
+// * networking/gateway-api.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-ingress-gateway-api-overview_{context}"]
+= Overview of the Gateway API
+
+The Gateway API is an open source, community-managed, Kubernetes networking mechanism. It focuses on routing within the transport layer, L4, and the application layer, L7, for clusters. A variety of vendors offer many link:https://gateway-api.sigs.k8s.io/implementations/[implementations of Gateway API].
+
+The project is an effort to provide a standardized ecosystem by using a portable API with broad community support. By integrating Gateway API functionality into the Ingress Operator, it enables a networking solution that aligns with existing community and upstream development efforts.
+
+The Gateway API extends the functionality of the Ingress Operator to handle more granular cluster traffic and routing configurations. With these capabilities, you can create instances of Gateway APIs custom resource definitions (CRDs). For {product-title} clusters, the Ingress Operator creates the following resources:
+
+Gateway:: This resource describes how traffic can be translated to services within the cluster. For example, a specific load balancer configuration.
+GatewayClass:: This resource defines a set of `Gateway` objects that share a common configuration and behavior. For example, two separate `GatewayClass` objects might be created to distinguish a set of `Gateway` resources used for public or private applications.
+HTTPRoute:: This resource specifies the routing behavior of HTTP requests from a Gateway to a service, and is especially useful for multiplexing HTTP or terminated HTTPS connections.
+GRPCRoute:: This resource specifies the routing behavior of gRPC requests.
+ReferenceGrant:: This resource enables cross-namespace references. For example, it enables routes to forward traffic to backends that are in a different namespace.
+
+In {product-title}, the implementation of the Gateway API is based on `gateway.networking.k8s.io/v1`, and all fields in this version are supported.
+
+[id="gateway-api-benefits_{context}"]
+== Benefits of the Gateway API
+The Gateway API provides the following benefits:
+
+* Portability: While {product-title} uses HAProxy to improve Ingress performance, Gateway API does not rely on vendor-specific annotations to provide certain behavior. To get comparable performance as 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 admins 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.
+
+[id="gateway-api-limitations_{context}"]
+== Limitations of the Gateway API
+The Gateway API has the following limitations:
+
+* Version incompatibilites: 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.

networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ingress-gateway-api"]
+= Gateway API with {product-title} Networking
+include::_attributes/common-attributes.adoc[]
+:context: ingress-gateway-api
+
+toc::[]
+
+{product-title} provides additional ways of configuring network traffic by using Gateway API with the Ingress Operator.
+
+[IMPORTANT]
+====
+Gateway API does not support user-defined networks (UDN).
+====
+
+include::modules/nw-ingress-gateway-api-overview.adoc[leveloffset=+1]
+
+include::modules/nw-ingress-gateway-api-implementation.adoc[leveloffset=+1]
+
+include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]
+
+.Additional resources
+* xref:configuring-ingress-cluster-traffic-ingress-controller.adoc#nw-ingress-sharding-concept_configuring-ingress-cluster-traffic-ingress-controller[Ingress Controller sharding].