osdocs18136 scrubbing GWAPI docs of OLM subscription references

Author: DCChadwick

_topic_maps/_topic_map.yml

@@ -1798,6 +1798,8 @@ Topics:
     Dir: configuring_gateway_api
     Distros: openshift-enterprise,openshift-origin
     Topics:
+    - Name: Understand the Gateway API
+      File: understand-gateway-api
     - Name: Controlling incoming traffic with Gateway listeners
       File: controlling-incoming-traffic-gateway-listeners
     - Name: Assigning network addresses to gateways

modules/gateway-api-benefits-limitations.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_gateway_api/understand-gateway-api.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="gateway-api-benefits-limitations_{context}"]
+= Gateway API benefits and limitations
+
+[role="_abstract"]
+To determine if the 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 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 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 has the following limitations:
+
+* Version incompatibilities: 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. 

modules/gateway-api-deployment-topologies.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_gateway_api/understand-gateway-api.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="gateway-api-deployment-topologies_{context}"]
+= Gateway API deployment topologies
+
+[role="_abstract"]
+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:: 
+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}. 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 `HTTPRoute` resource must have the name of the `Gateway` object as the value for its `parentRefs` field in order to attach to the gateway. The system implicitly assumes that the route exists in the same namespace as the `Gateway` object.
+
+Shared gateway:: 
+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. 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/gateway-api-implementation-specifics.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress_load_balancing/configuring_gateway_api/understand-gateway-api.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="gateway-api-implementation-specifics_{context}"]
+= Gateway API implementation specifics
+
+[role="_abstract"]
+To ensure interoperability between external vendor implementations and your networking infrastructure in {product-title}, 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 {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. 
+====

networking/ingress_load_balancing/configuring_gateway_api/understand-gateway-api.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="understand-gateway-api_{context}"]
+= Understand the Gateway API
+include::_attributes/common-attributes.adoc[]
+:context: understand-gateway-api
+
+toc::[]
+
+[role="_abstract"]
+To optimize network traffic management and implement routing policies in {product-title}, use the 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-architected 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 the Gateway API.
+* Review {product-title} implementation specifics to avoid unsupported features.
+* Choose between shared or dedicated deployment topologies.
+
+[IMPORTANT]
+====
+Gateway API does not support user-defined networks (UDN).
+====
+
+include::modules/gateway-api-benefits-limitations.adoc[leveloffset=+1]
+
+include::modules/gateway-api-implementation-specifics.adoc[leveloffset=+1]
+
+include::modules/gateway-api-deployment-topologies.adoc[leveloffset=+1]