Skip to content

Commit c42a895

Browse files
bmcelveebmcelvee
authored
Merge pull request #33631 from bmcelvee/OSDOCS-2129
OSDOCS-2129: Add upstream gateway API documentation
2 parents db9cf36 + 5a03a75 commit c42a895

File tree

4 files changed

+228
-0
lines changed

4 files changed

+228
-0
lines changed

‎_topic_map.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -885,6 +885,9 @@ Topics:
885885
- Name: Understanding the Ingress Operator
886886
File: ingress-operator
887887
Distros: openshift-enterprise,openshift-origin
888+
- Name: About the Contour Operator
889+
File: about-contour-operator
890+
Distros: openshift-origin
888891
- Name: Verifying connectivity to an endpoint
889892
File: verifying-connectivity-endpoint
890893
- Name: Configuring the node port service range

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

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/about-contour-operator.adoc
4+
5+
[id="nw-install-config-gateway-api_{context}"]
6+
= Installing and configuring Contour for Gateway API
7+
8+
[IMPORTANT]
9+
====
10+
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.
11+
====
12+
13+
The following guide provides instructions for using link:https://gateway-api.sigs.k8s.io/[the Gateway API] with the Contour Operator on {product-title}.
14+
15+
.Prerequisites
16+
17+
* You installed an {product-title} cluster and the `oc` command line.
18+
* You installed the Contour Operator.
19+
//* Log in as a user with cluster-admin permission.
20+
21+
.Procedure
22+
23+
. Install Contour configured for Gateway API and dependent resources:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.16.0/examples/gateway/gateway.yaml
28+
----
29+
+
30+
[NOTE]
31+
====
32+
Envoy pods are exposed using a LoadBalancer service. Replace `gateway.yaml` with `gateway-nodeport.yaml` to use a NodePort service instead.
33+
====
34+
+
35+
.Verification
36+
+
37+
. Verify that all pods in the namespace where you installed Contour are running:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc get pods -n projectcontour
42+
----
43+
+
44+
.Example output
45+
+
46+
[source,terminal]
47+
----
48+
NAME READY STATUS RESTARTS AGE
49+
contour-768547cfb8-c2rhn 1/1 Running 0 2m
50+
contour-768547cfb8-q866f 1/1 Running 0 2m
51+
contour-certgen-main-rb2h2 0/1 Completed 0 92s
52+
envoy-d5djm 2/2 Running 0 2m41s
53+
envoy-gjwz5 2/2 Running 0 2m41s
54+
envoy-hbg6j 2/2 Running 0 2m41s
55+
----
56+
+
57+
The number of Envoy pods depends on how many worker nodes are in your cluster.
58+
+
59+
. Run a test workload:
60+
+
61+
[source,terminal]
62+
----
63+
$ oc apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.16.0/examples/gateway/kuard/kuard.yaml
64+
----
65+
+
66+
.Verification
67+
+
68+
. Verify the status of the test workload:
69+
+
70+
[source,terminal]
71+
----
72+
$ oc get pods,svc,httproute -n projectcontour -l app=kuard
73+
----
74+
+
75+
.Example output
76+
+
77+
[source,terminal]
78+
----
79+
NAME READY STATUS RESTARTS AGE
80+
pod/kuard-798585497b-9mvwh 1/1 Running 0 5s
81+
pod/kuard-798585497b-kcjnn 1/1 Running 0 5s
82+
pod/kuard-798585497b-lnhsn 1/1 Running 0 5s
83+
84+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
85+
service/kuard ClusterIP 10.96.157.48 <none> 80/TCP 5s
86+
87+
NAME HOSTNAMES
88+
httproute.networking.x-k8s.io/kuard ["local.projectcontour.io"]
89+
----
90+
+
91+
The application is exposed using an `HTTPRoute` that routes all HTTP requests for `local.projectcontour.io` to service kuard.
92+
+
93+
. Curl the application hostname:
94+
+
95+
[source,terminal]
96+
----
97+
$ export GATEWAY=$(oc -n projectcontour get svc/envoy -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
98+
----
99+
+
100+
[NOTE]
101+
====
102+
Replace `hostname` in the json path with `ip` if your cloud provider uses IP addresses instead of hostnames for loadBalancer services.
103+
====
104+
+
105+
[source,terminal]
106+
----
107+
$ curl -H "Host: local.projectcontour.io" -s -o /dev/null -w "%{http_code}" "http://$GATEWAY/"
108+
----
109+
+
110+
If running appropriately, a `200` HTTP status code is returned.
111+
+
112+
.Verification
113+
+
114+
. Verify that the curl request was serviced by Envoy:
115+
+
116+
[source,terminal]
117+
----
118+
$ oc logs ds/envoy -c envoy -n projectcontour | grep curl
119+
----
120+
+
121+
.Example output
122+
+
123+
[source,terminal]
124+
----
125+
Found 3 pods, using pod/envoy-g86st
126+
[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"
127+
----
128+
+
129+
[NOTE]
130+
====
131+
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.
132+
====

‎modules/nw-install-contour-operator.adoc‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/about-contour-operator.adoc
4+
5+
[id="nw-install-contour-operator_{context}"]
6+
= Installing Contour Operator
7+
8+
[IMPORTANT]
9+
====
10+
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.
11+
====
12+
13+
Install the Contour Operator on {product-title} to use link:https://gateway-api.sigs.k8s.io/[the Gateway API].
14+
15+
.Prerequisites
16+
17+
* You installed an {product-title} cluster and the `oc` command line.
18+
//* Log in as a user with cluster-admin permission.
19+
20+
.Procedure
21+
22+
. Install the Contour Operator:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.16.0/examples/operator/operator.yaml
27+
----
28+
+
29+
[NOTE]
30+
====
31+
It can take a few minutes for the Contour Operator to become available.
32+
====
33+
+
34+
.Verification
35+
+
36+
. Verify the availability of the Operator:
37+
+
38+
[source,terminal]
39+
----
40+
$ oc get deployment/contour-operator -n contour-operator
41+
----
42+
+
43+
.Example output
44+
+
45+
[source,terminal]
46+
----
47+
NAME READY UP-TO-DATE AVAILABLE AGE
48+
contour-operator 1/1 1 1 12m
49+
----
50+
51+
. Add `contour` and `contour-certgen` service accounts to the `nonroot` security context constraint (SCC):
52+
+
53+
[NOTE]
54+
====
55+
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.
56+
====
57+
+
58+
[source,terminal]
59+
----
60+
$ oc adm policy add-scc-to-user nonroot system:serviceaccount:projectcontour:contour
61+
----
62+
+
63+
[source,terminal]
64+
----
65+
$ oc adm policy add-scc-to-user nonroot system:serviceaccount:projectcontour:contour-certgen
66+
----

‎networking/about-contour-operator.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[id="about-contour-operator"]
2+
= About the Contour Operator
3+
include::modules/common-attributes.adoc[]
4+
:context: about-contour-operator
5+
6+
toc::[]
7+
8+
//Dev Preview. OKD only.
9+
10+
[IMPORTANT]
11+
====
12+
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.
13+
====
14+
15+
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.
16+
17+
include::modules/nw-install-contour-operator.adoc[leveloffset=+1]
18+
19+
include::modules/nw-install-config-gateway-api.adoc[leveloffset=+1]
20+
21+
[id="about-contour-operator-additional-resources"]
22+
== Additional resources
23+
24+
For additional details, see:
25+
26+
//* link:https://gateway-api.sigs.k8s.io/[What is the Gateway API]
27+
* link:https://projectcontour.io/guides/gateway-api/[Using Gateway API with Contour]

0 commit comments

Comments
 (0)