add enablement procedure

Author: jldohmann

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

@@ -0,0 +1,65 @@
+// Modules included in the following assemblies:
+//
+// * networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-ingress-gateway-api-enable_{context}"]
+= Enabling Gateway API for the Ingress Operator
+
+When you enable Gateway API, it installs the subscription, the Istio operator, the custom resource defintions (CRDs), and creates the Istio resources. The following procedure describes how to enable Gateway API.
+
+.Procedure
+
+. Create a `GatewayClass` object with the following manifest:
++
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: GatewayClass
+metadata:
+  name: openshift-default
+spec:
+  controllerName: openshift.io/gateway-controller/v1 <1>
+----
+<1> The controller name must be `v1` for the Ingress Operator to manage it. Setting this field to anything else will be ignored by the Ingress Operator, because it is assumed to be a different implementation.
+
+. Create a secret using the default certificate:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress create secret tls gwapi-wildcard --cert=wildcard.crt --key=wildcard.key
+----
+
+. Create a `Gateway` object with the following manifest:
++
+[source,yaml]
+----
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: example-gateway
+  namespace: openshift-ingress
+spec:
+  gatewayClassName: openshift-default <1>
+  listeners: <2>
+  - name: http
+    hostname: "*.gwapi.example.com"
+    port: 80
+    protocol: HTTP
+    allowedRoutes:
+      namespaces:
+        from: All
+  - name: https
+    hostname: "*.gwapi.example.com"
+    port: 443
+    protocol: HTTPS
+    tls:
+      mode: Terminate
+      certificateRefs:
+      - name: gwapi-wildcard <3>
+    allowedRoutes:
+      namespaces:
+        from: All
+----
+<1> The name of the previously created `GatewayClass` object.
+<2> The associated listeners for the `Gateway` object. These listeners are for HTTP and HTTPS, and let you configure ingress to your applications using Gateway API `HTTPRoute` resources.

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

@@ -8,9 +8,9 @@
 
 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.
+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.
+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 Gateway API version supported by {product-title}, and creates an admin-gate that requires your acknowledgment of CRD succession.
 
 [IMPORTANT]
 ====

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

@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="nw-ingress-gateway-api-overview_{context}"]
-= Overview of the Gateway API
+= Overview of 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].
 
@@ -18,18 +18,18 @@ HTTPRoute:: This resource specifies the routing behavior of HTTP requests from a
 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.
+In {product-title}, the implementation of 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
+== Benefits of 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
+== Limitations of 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.

networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc

@@ -17,6 +17,8 @@ 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-enable.adoc[leveloffset=+1]
+
 include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]
 
 .Additional resources