Merge pull request openshift#33631 from bmcelvee/OSDOCS-2129

OSDOCS-2129: Add upstream gateway API documentation

_topic_map.yml

@@ -885,6 +885,9 @@ Topics:
 - Name: Understanding the Ingress Operator
   File: ingress-operator
   Distros: openshift-enterprise,openshift-origin
+- Name: About the Contour Operator
+  File: about-contour-operator
+  Distros: openshift-origin
 - Name: Verifying connectivity to an endpoint
   File: verifying-connectivity-endpoint
 - Name: Configuring the node port service range

modules/nw-install-config-gateway-api.adoc

@@ -0,0 +1,132 @@
+// Module included in the following assemblies:
+//
+// * networking/about-contour-operator.adoc
+
+[id="nw-install-config-gateway-api_{context}"]
+= Installing and configuring Contour for Gateway API
+
+[IMPORTANT]
+====
+The following features are in Developer Preview and not currently supported or intended for production use. They are highlighted here to notify users of the important upcoming addition of Gateway API. Limited documentation is available at this time.
+====
+
+The following guide provides instructions for using link:https://gateway-api.sigs.k8s.io/[the Gateway API] with the Contour Operator on {product-title}.
+
+.Prerequisites
+
+* You installed an {product-title} cluster and the `oc` command line.
+* You installed the Contour Operator.
+//* Log in as a user with cluster-admin permission.
+
+.Procedure
+
+. Install Contour configured for Gateway API and dependent resources:
++
+[source,terminal]
+----
+$ oc apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.16.0/examples/gateway/gateway.yaml
+----
++
+[NOTE]
+====
+Envoy pods are exposed using a LoadBalancer service. Replace `gateway.yaml` with `gateway-nodeport.yaml` to use a NodePort service instead.
+====
++
+.Verification
++
+. Verify that all pods in the namespace where you installed Contour are running:
++
+[source,terminal]
+----
+$ oc get pods -n projectcontour
+----
++
+.Example output
++
+[source,terminal]
+----
+NAME                         READY   STATUS      RESTARTS   AGE
+contour-768547cfb8-c2rhn     1/1     Running     0          2m
+contour-768547cfb8-q866f     1/1     Running     0          2m
+contour-certgen-main-rb2h2   0/1     Completed   0          92s
+envoy-d5djm                  2/2     Running     0          2m41s
+envoy-gjwz5                  2/2     Running     0          2m41s
+envoy-hbg6j                  2/2     Running     0          2m41s
+----
++
+The number of Envoy pods depends on how many worker nodes are in your cluster.
++
+. Run a test workload:
++
+[source,terminal]
+----
+$ oc apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.16.0/examples/gateway/kuard/kuard.yaml
+----
++
+.Verification
++
+. Verify the status of the test workload:
++
+[source,terminal]
+----
+$ oc get pods,svc,httproute -n projectcontour -l app=kuard
+----
++
+.Example output
++
+[source,terminal]
+----
+NAME                         READY   STATUS    RESTARTS   AGE
+pod/kuard-798585497b-9mvwh   1/1     Running   0          5s
+pod/kuard-798585497b-kcjnn   1/1     Running   0          5s
+pod/kuard-798585497b-lnhsn   1/1     Running   0          5s
+
+NAME            TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
+service/kuard   ClusterIP   10.96.157.48   <none>        80/TCP    5s
+
+NAME                                  HOSTNAMES
+httproute.networking.x-k8s.io/kuard   ["local.projectcontour.io"]
+----
++
+The application is exposed using an `HTTPRoute` that routes all HTTP requests for `local.projectcontour.io` to service kuard.
++
+. Curl the application hostname:
++
+[source,terminal]
+----
+$ export GATEWAY=$(oc -n projectcontour get svc/envoy -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
+----
++
+[NOTE]
+====
+Replace `hostname` in the json path with `ip` if your cloud provider uses IP addresses instead of hostnames for loadBalancer services.
+====
++
+[source,terminal]
+----
+$ curl -H "Host: local.projectcontour.io" -s -o /dev/null -w "%{http_code}" "http://$GATEWAY/"
+----
++
+If running appropriately, a `200` HTTP status code is returned.
++
+.Verification
++
+. Verify that the curl request was serviced by Envoy:
++
+[source,terminal]
+----
+$ oc logs ds/envoy -c envoy -n projectcontour | grep curl
+----
++
+.Example output
++
+[source,terminal]
+----
+Found 3 pods, using pod/envoy-g86st
+[2021-02-03T17:17:24.009Z] "GET / HTTP/1.1" 200 - 0 1748 1 1 "10.0.79.141" "curl/7.64.1" "2c53c9ba-46a2-4527-8b41-03ea9041bd2d" "a811b15855e1f428d8a834d0a86c3668-573506534.us-east-2.elb.amazonaws.com" "10.129.2.13:8080"
+----
++
+[NOTE]
+====
+The example above defaulted to pod `envoy-g86st` since the daemonset has three running pods. Use a different Envoy pod if the curl request does not appear in the logs.
+====

modules/nw-install-contour-operator.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// * networking/about-contour-operator.adoc
+
+[id="nw-install-contour-operator_{context}"]
+= Installing Contour Operator
+
+[IMPORTANT]
+====
+The following features are in Developer Preview and not currently supported or intended for production use. They are highlighted here to notify users of the important upcoming addition of Gateway API. Limited documentation is available at this time.
+====
+
+Install the Contour Operator on {product-title} to use link:https://gateway-api.sigs.k8s.io/[the Gateway API].
+
+.Prerequisites
+
+* You installed an {product-title} cluster and the `oc` command line.
+//* Log in as a user with cluster-admin permission.
+
+.Procedure
+
+. Install the Contour Operator:
++
+[source,terminal]
+----
+$ oc apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.16.0/examples/operator/operator.yaml
+----
++
+[NOTE]
+====
+It can take a few minutes for the Contour Operator to become available.
+====
++
+.Verification
++
+. Verify the availability of the Operator:
++
+[source,terminal]
+----
+$ oc get deployment/contour-operator -n contour-operator
+----
++
+.Example output
++
+[source,terminal]
+----
+NAME               READY   UP-TO-DATE   AVAILABLE   AGE
+contour-operator   1/1     1            1           12m
+----
+
+. Add `contour` and `contour-certgen` service accounts to the `nonroot` security context constraint (SCC):
++
+[NOTE]
+====
+The example uses `projectcontour` by default as the namespace of the `contour/contour-certgen` service accounts. Replace `projectcontour` with the namespace used for Contour if you deviate from the example.
+====
++
+[source,terminal]
+----
+$ oc adm policy add-scc-to-user nonroot system:serviceaccount:projectcontour:contour
+----
++
+[source,terminal]
+----
+$ oc adm policy add-scc-to-user nonroot system:serviceaccount:projectcontour:contour-certgen
+----

networking/about-contour-operator.adoc

@@ -0,0 +1,27 @@
+[id="about-contour-operator"]
+= About the Contour Operator
+include::modules/common-attributes.adoc[]
+:context: about-contour-operator
+
+toc::[]
+
+//Dev Preview. OKD only.
+
+[IMPORTANT]
+====
+The following features are in Developer Preview and not currently supported or intended for production use. They are highlighted here to notify users of the important upcoming addition of Gateway API. Limited documentation is available at this time.
+====
+
+The Contour Operator can be installed on {product-title} to manage Contour, an Ingress Controller that supports Gateway API, an open-source project that exposes Kubernetes resources such as services to external consumers.
+
+include::modules/nw-install-contour-operator.adoc[leveloffset=+1]
+
+include::modules/nw-install-config-gateway-api.adoc[leveloffset=+1]
+
+[id="about-contour-operator-additional-resources"]
+== Additional resources
+
+For additional details, see:
+
+//* link:https://gateway-api.sigs.k8s.io/[What is the Gateway API]
+* link:https://projectcontour.io/guides/gateway-api/[Using Gateway API with Contour]