Skip to content

Commit d38c6f6

Browse files
jldohmannkalexand-rh
jldohmann
authored and
kalexand-rh
committed
add enablement procedure
1 parent 78e193e commit d38c6f6

File tree

4 files changed

+252
-11
lines changed

4 files changed

+252
-11
lines changed

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

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
// Modules included in the following assemblies:
2+
//
3+
// * networking/configuring_ingress_cluster_traffic/ingress-gateway-api.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="nw-ingress-gateway-api-enable_{context}"]
7+
= Getting started with Gateway API for the Ingress Operator
8+
9+
When you create a GatewayClass as shown in the first step, it configures Gateway API for use on your cluster.
10+
11+
.Procedure
12+
13+
. Create a `GatewayClass` object:
14+
15+
.. Create a YAML file, `openshift-default.yaml`, that contains the following information:
16+
+
17+
.Example `GatewayClass` CR
18+
[source,yaml]
19+
----
20+
apiVersion: gateway.networking.k8s.io/v1
21+
kind: GatewayClass
22+
metadata:
23+
name: openshift-default
24+
spec:
25+
controllerName: openshift.io/gateway-controller/v1 <1>
26+
----
27+
<1> The controller name.
28+
+
29+
[IMPORTANT]
30+
====
31+
The controller name must be exactly as shown for the Ingress Operator to manage it. If you set this field to anything else, the Ingress Operator ignores the `GatewayClass` object and all associated `Gateway`, `GRPCRoute`, and `HTTPRoute` objects. The controller name is tied to the implementation of Gateway API in {product-title}, and `openshift.io/gateway-controller/v1` is the only controller name allowed.
32+
====
33+
34+
.. Run the following command to create the `GatewayClass` resource:
35+
+
36+
[source,terminal]
37+
----
38+
$ oc create -f openshift-default.yaml
39+
----
40+
+
41+
.Example output
42+
[source,terminal]
43+
----
44+
gatewayclass.gateway.networking.k8s.io/openshift-default created
45+
----
46+
+
47+
During the creation of the `GatewayClass` resource, the Ingress Operator installs a lightweight version of {SMProductName}, an Istio custom resource, and a new deployment in the `openshift-ingress` namespace.
48+
49+
.. Optional: Verify that the new deployment, `istiod-openshift-gateway` is ready and available:
50+
+
51+
[source,terminal]
52+
----
53+
$ oc get deployment -n openshift-ingress
54+
----
55+
+
56+
.Example output
57+
[source,terminal]
58+
----
59+
NAME READY UP-TO-DATE AVAILABLE AGE
60+
istiod-openshift-gateway 1/1 1 1 55s
61+
router-default 2/2 2 2 6h4m
62+
----
63+
64+
. Create a secret by running the following command:
65+
+
66+
[source,terminal]
67+
----
68+
$ oc -n openshift-ingress create secret tls gwapi-wildcard --cert=wildcard.crt --key=wildcard.key
69+
----
70+
71+
. Get the domain of the Ingress Operator by running the following command:
72+
+
73+
[source,terminal]
74+
----
75+
$ DOMAIN=$(oc get ingresses.config/cluster -o jsonpath={.spec.domain})
76+
----
77+
78+
. Create a `Gateway` object:
79+
80+
.. Create a YAML file, `example-gateway.yaml`, that contains the following information:
81+
+
82+
.Example `Gateway` CR
83+
[source,yaml]
84+
----
85+
apiVersion: gateway.networking.k8s.io/v1
86+
kind: Gateway
87+
metadata:
88+
name: example-gateway
89+
namespace: openshift-ingress <1>
90+
spec:
91+
gatewayClassName: openshift-default <2>
92+
listeners:
93+
- name: https <3>
94+
hostname: "*.gwapi.${DOMAIN}" <4>
95+
port: 443
96+
protocol: HTTPS
97+
tls:
98+
mode: Terminate
99+
certificateRefs:
100+
- name: gwapi-wildcard <5>
101+
allowedRoutes:
102+
namespaces:
103+
from: All
104+
----
105+
<1> The `Gateway` object must be created in the `openshift-ingress` namespace.
106+
<2> The `Gateway` object must reference the name of the previously created `GatewayClass` object.
107+
<3> The HTTPS listener listens for HTTPS requests that match a subdomain of the cluster domain. You use this listener to configure ingress to your applications by using Gateway API `HTTPRoute` resources.
108+
<4> The hostname must be a subdomain of the Ingress Operator domain. If you use a domain, the listener tries to serve all traffic in that domain.
109+
<5> The name of the previously created secret.
110+
111+
.. Apply the resource by running the following command:
112+
+
113+
[source,terminal]
114+
----
115+
$ oc apply -f example-gateway.yaml
116+
----
117+
118+
.. Optional: When you create a `Gateway` object, {SMProductName} automatically provisions a deployment and service with the same name. Verify this by running the following commands:
119+
*** To verify the deployment, run the following command:
120+
+
121+
[source,terminal]
122+
----
123+
$ oc get deployment -n openshift-ingress example-gateway-openshift-default
124+
----
125+
+
126+
.Example output
127+
[source,terminal]
128+
----
129+
NAME READY UP-TO-DATE AVAILABLE AGE
130+
example-gateway-openshift-default 1/1 1 1 25s
131+
----
132+
*** To verify the service, run the following command:
133+
+
134+
[source,terminal]
135+
----
136+
$ oc get service -n openshift-ingress example-gateway-openshift-default
137+
----
138+
+
139+
.Example output
140+
[source,terminal]
141+
----
142+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
143+
example-gateway-openshift-default LoadBalancer 10.1.2.3 <external_ipname> <port_info> 47s
144+
----
145+
146+
.. Optional: The Ingress Operator automatically creates a `DNSRecord` CR using the hostname from the listeners, and adds the label `gateway.networking.k8s.io/gateway-name=example-gateway`. Verify the status of the DNS record by running the following command:
147+
+
148+
[source,terminal]
149+
----
150+
$ oc -n openshift-ingress get dnsrecord -l gateway.networking.k8s.io/gateway-name=example-gateway -o yaml
151+
----
152+
+
153+
.Example output
154+
[source,yaml]
155+
----
156+
kind: DNSRecord
157+
...
158+
status:
159+
...
160+
zones:
161+
- conditions:
162+
- message: The DNS provider succeeded in ensuring the record
163+
reason: ProviderSuccess
164+
status: "True"
165+
type: Published
166+
dnsZone:
167+
tags:
168+
...
169+
- conditions:
170+
- message: The DNS provider succeeded in ensuring the record
171+
reason: ProviderSuccess
172+
status: "True"
173+
type: Published
174+
dnsZone:
175+
id: ...
176+
----
177+
178+
. Create an `HTTPRoute` resource that directs requests to your already-created namespace and application called `example-app/example-app`:
179+
180+
.. Create a YAML file, `example-route.yaml`, that contains the following information:
181+
+
182+
.Example `HTTPRoute` CR
183+
[source,yaml]
184+
----
185+
apiVersion: gateway.networking.k8s.io/v1
186+
kind: HTTPRoute
187+
metadata:
188+
name: example-route
189+
namespace: example-app-ns <1>
190+
spec:
191+
parentRefs: <2>
192+
- name: example-gateway
193+
namespace: openshift-ingress
194+
hostnames: ["example.gwapi.${DOMAIN}"] <3>
195+
rules:
196+
- backendRefs: <4>
197+
- name: example-app <5>
198+
port: 8443
199+
----
200+
<1> The namespace you are deploying your application.
201+
<2> This field must point to the `Gateway` object you previously configured.
202+
<3> The hostname must match the one specified in the `Gateway` object. In this case, the listeners use a wildcard hostname.
203+
<4> This field specifies the backend references that point to your service.
204+
<5> The name of the `Service` for your application.
205+
206+
.. Apply the resource by running the following command:
207+
+
208+
[source,terminal]
209+
----
210+
$ oc apply -f example-route.yaml
211+
----
212+
+
213+
.Example output
214+
[source,terminal]
215+
----
216+
httproute.gateway.networking.k8s.io/example-route created
217+
----
218+
219+
.Verification
220+
221+
. Verify that the `Gateway` object is deployed and has the condition `Programmed` by running the following command:
222+
+
223+
[source,terminal]
224+
----
225+
$ oc wait -n openshift-ingress --for=condition=Programmed gateways.gateway.networking.k8s.io example-gateway
226+
----
227+
+
228+
.Example output
229+
[source,terminal]
230+
----
231+
gateway.gateway.networking.k8s.io/example-gateway condition met
232+
----
233+
234+
. Send a request to the configured `HTTPRoute` object hostname:
235+
+
236+
[source,terminal]
237+
----
238+
$ curl -I --cacert <local cert file> https://example.gwapi.${DOMAIN}:443
239+
----

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88

99
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.
1010

11-
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.
11+
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.
1212

13-
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.
13+
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.
1414

1515
[IMPORTANT]
1616
====

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,33 +4,33 @@
44

55
:_mod-docs-content-type: CONCEPT
66
[id="nw-ingress-gateway-api-overview_{context}"]
7-
= Overview of the Gateway API
7+
= Overview of Gateway API
88

9-
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].
9+
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].
1010

1111
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.
1212

13-
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:
13+
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:
1414

1515
Gateway:: This resource describes how traffic can be translated to services within the cluster. For example, a specific load balancer configuration.
1616
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.
1717
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.
1818
GRPCRoute:: This resource specifies the routing behavior of gRPC requests.
1919
ReferenceGrant:: This resource enables cross-namespace references. For example, it enables routes to forward traffic to backends that are in a different namespace.
2020

21-
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.
21+
In {product-title}, the implementation of Gateway API is based on `gateway.networking.k8s.io/v1`, and all fields in this version are supported.
2222

2323
[id="gateway-api-benefits_{context}"]
24-
== Benefits of the Gateway API
25-
The Gateway API provides the following benefits:
24+
== Benefits of Gateway API
25+
Gateway API provides the following benefits:
2626

2727
* 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.
2828
* 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.
2929
* Extensibility: Additional functionality is developed as a standardized CRD.
3030

3131
[id="gateway-api-limitations_{context}"]
32-
== Limitations of the Gateway API
33-
The Gateway API has the following limitations:
32+
== Limitations of Gateway API
33+
Gateway API has the following limitations:
3434

35-
* 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.
35+
* 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.
3636
* 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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ include::modules/nw-ingress-gateway-api-overview.adoc[leveloffset=+1]
1717

1818
include::modules/nw-ingress-gateway-api-implementation.adoc[leveloffset=+1]
1919

20+
include::modules/nw-ingress-gateway-api-enable.adoc[leveloffset=+1]
21+
2022
include::modules/nw-ingress-gateway-api-deployment-topologies.adoc[leveloffset=+1]
2123

2224
.Additional resources

0 commit comments

Comments
 (0)