OSDOCS-14879: add enablement procedure #94480
+227
−11
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,214 @@ | ||
| // 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}"] | ||
| = Getting started with Gateway API for the Ingress Operator | ||
|
|
||
| When you enable Gateway API, it installs the subscription, the Istio operator, the custom resource definitions (CRDs), and creates the Istio resources. | ||
|
|
||
| .Procedure | ||
|
|
||
| . Create a `GatewayClass` object that contains the following information: | ||
| + | ||
| .Example `GatewayClass` CR | ||
| [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. | ||
| + | ||
| [IMPORTANT] | ||
| ==== | ||
| 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. | ||
| ==== | ||
|
|
||
| . Run the following command to create the `GatewayClass` resource: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc create -f <gatewayclass_resource>.yaml | ||
|
There was a problem hiding this comment. <gatewayclass_resource>.yaml isn't defined anywhere. You could mention creating a file instead of manifest in line 15 |
||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| gatewayclass.gateway.networking.k8s.io/openshift-default created | ||
| ---- | ||
|
|
||
|
There was a problem hiding this comment. We could add the following to be a bit more helpful: Behind the scenes, the Ingress Operator installs a pared-down OSSM, an $ oc get deployment -n openshift-ingress If it is ready and available, Gateway API and OSSM have been installed successfully and are ready to use. See the following sections for the next steps. There was a problem hiding this comment. i can add this optional step. does it sit between steps one and two, or is this something a user would do before performing any of the steps in the procedure? There was a problem hiding this comment. actually this seems like it happens after creating the There was a problem hiding this comment. Yes, it verifies that the behind-the-scenes activities took place. |
||
| . Create a secret by using the default certificate by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc -n openshift-ingress create secret tls gwapi-wildcard --cert=wildcard.crt --key=wildcard.key | ||
|
There was a problem hiding this comment. Does it tell them anywhere how to create the wildcard.crt and wildcard.key? There was a problem hiding this comment. we have a lot of existing docs on creating certificates. do you mean something like this? https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/security_and_compliance/configuring-certificates i can link it |
||
| ---- | ||
|
|
||
| . Get the domain of the Ingress Operator by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ DOMAIN=$(oc get ingresses.config/cluster -o jsonpath={.spec.domain}) | ||
| ---- | ||
|
|
||
| . Create a `Gateway` object with the following information: | ||
| + | ||
|
There was a problem hiding this comment. One extra step here, and including the command to get the correct domain: |
||
| .Example `Gateway` CR | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: gateway.networking.k8s.io/v1 | ||
| kind: Gateway | ||
| metadata: | ||
| name: example-gateway | ||
| namespace: openshift-ingress <1> | ||
| spec: | ||
| gatewayClassName: openshift-default <2> | ||
| listeners: | ||
| - name: https <3> | ||
| hostname: "*.gwapi.${DOMAIN}" <4> | ||
| port: 443 | ||
| protocol: HTTPS | ||
| tls: | ||
| mode: Terminate | ||
| certificateRefs: | ||
| - name: gwapi-wildcard <5> | ||
| allowedRoutes: | ||
| namespaces: | ||
| from: All | ||
| ---- | ||
|
|
||
| <1> The `Gateway` object must be created in the `openshift-ingress` namespace. | ||
| <2> The `Gateway` object must reference the name of the previously created `GatewayClass` object. | ||
| <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. | ||
| <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. | ||
| <5> The name of the previously created secret using the default certificate. | ||
|
|
||
| . Apply the resource by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc apply -f <gateway_resource>.yaml | ||
| ---- | ||
|
|
||
| . 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: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc get deployment -n openshift-ingress example-gateway | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| NAME READY UP-TO-DATE AVAILABLE AGE | ||
| example-gateway 1/1 1 1 25s | ||
| ---- | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc get service -n openshift-ingress example-gateway | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE | ||
| example-gateway LoadBalancer 10.1.2.3 <external ipname> <port-info> 47s | ||
| ---- | ||
|
|
||
| . Optional: The Ingress Operator automatically creates a `DNSRecord` CR using the hostname from the listeners, and adds the label `istio.io/gateway-name=example-gateway`. Verify the status of the DNS record by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc get dnsrecord -n openshift-ingress -l istio.io/gateway-name=example-gateway -o yaml | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,yaml] | ||
| ---- | ||
| kind: DNSRecord | ||
| ... | ||
| status: | ||
| ... | ||
| zones: | ||
| - conditions: | ||
| - message: The DNS provider succeeded in ensuring the record | ||
| reason: ProviderSuccess | ||
| status: "True" | ||
| type: Published | ||
| dnsZone: | ||
| tags: | ||
| ... | ||
| - conditions: | ||
| - message: The DNS provider succeeded in ensuring the record | ||
| reason: ProviderSuccess | ||
| status: "True" | ||
| type: Published | ||
| dnsZone: | ||
| id: ... | ||
| ---- | ||
|
|
||
| . Create an `HTTPRoute` resource that directs requests to your application: | ||
| + | ||
| .Example `HTTPRoute` CR | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: gateway.networking.k8s.io/v1 | ||
| kind: HTTPRoute | ||
| metadata: | ||
| name: example-route | ||
| namespace: example-app-ns <1> | ||
| spec: | ||
| parentRefs: <2> | ||
| - name: example-gateway | ||
| namespace: openshift-ingress | ||
| hostnames: ["example.gwapi.${DOMAIN}"] <3> | ||
| rules: <4> | ||
| - backendRefs: | ||
| - name: example-app <5> | ||
| port: 8443 | ||
| ---- | ||
| <1> The namespace you are deploying your application. | ||
| <2> This field must point to the `Gateway` object you previously configured. | ||
| <3> The hostname must match the one specified in the `Gateway` object. In this case, the listeners use a wildcard hostname. | ||
| <4> This field specifies the backend references that point to your service. | ||
| <5> The name of your application. | ||
|
|
||
| . Apply the resource by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc apply -f <http_resource>.yaml | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| httproute.gateway.networking.k8s.io/http created | ||
| ---- | ||
|
|
||
| .Verification | ||
|
|
||
| . Verify that the `Gateway` object is deployed and has the condition `Programmed` by running the following command: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ oc wait -n openshift-ingress --for=condition=Programmed gateways.gateway.networking.k8s.io example-gateway | ||
| ---- | ||
| + | ||
| .Example output | ||
| [source,terminal] | ||
| ---- | ||
| gateway.gateway.networking.k8s.io/example-gateway condition met | ||
| ---- | ||
|
|
||
| . Send a request to the configured `HTTPRoute` object hostname: | ||
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ curl -I -cacert <local cert file> https://example.gwapi.${DOMAIN}:443 | ||
| ---- | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instead of just the manifest, you could also add the command:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sure, i added it as a separate step, PTAL