OSDOCS-14879: add enablement procedure by jldohmann · Pull Request #94480 · openshift/openshift-docs

jldohmann · 2025-06-09T20:48:37Z

Version(s): 4.19+

Issue: https://issues.redhat.com/browse/OSDOCS-14879

Link to docs preview: https://94480--ocpdocs-pr.netlify.app/openshift-enterprise/latest/networking/configuring_ingress_cluster_traffic/ingress-gateway-api.html#nw-ingress-gateway-api-enable_ingress-gateway-api

QE review:

QE has approved this change.

Additional information:

openshift-ci-robot · 2025-06-09T20:48:40Z

@jldohmann: This pull request references OSDOCS-14879 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target either version "4.20." or "openshift-4.20.", but it targets "openshift-4.19" instead.

Details

In response to this:

Version(s): 4.19+

Issue: https://issues.redhat.com/browse/OSDOCS-14879

Link to docs preview:

QE review:

QE has approved this change.

Additional information:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

ocpdocs-previewbot · 2025-06-09T21:20:10Z

🤖 Fri Jun 13 19:10:27 - Prow CI generated the docs preview:

https://94480--ocpdocs-pr.netlify.app/openshift-enterprise/latest/networking/configuring_ingress_cluster_traffic/ingress-gateway-api.html

openshift-ci-robot · 2025-06-09T21:29:34Z

@jldohmann: This pull request references OSDOCS-14879 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target either version "4.20." or "openshift-4.20.", but it targets "openshift-4.19" instead.

Details

In response to this:

Version(s): 4.19+

Issue: https://issues.redhat.com/browse/OSDOCS-14879

Link to docs preview: https://94480--ocpdocs-pr.netlify.app/openshift-enterprise/latest/networking/configuring_ingress_cluster_traffic/ingress-gateway-api.html#nw-ingress-gateway-api-enable_ingress-gateway-api

QE review:

QE has approved this change.

Additional information:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

jldohmann · 2025-06-10T14:21:22Z

@rhamini3 could you PTAL at this docs PR for QE ack? thank you

lahinson

Nice work! Just a few nits for your consideration.

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

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

rhamini3 · 2025-06-10T21:08:57Z

one small suggestion, otherwise
/label qe-approved

openshift-ci-robot · 2025-06-10T21:09:04Z

@jldohmann: This pull request references OSDOCS-14879 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target either version "4.20." or "openshift-4.20.", but it targets "openshift-4.19" instead.

Details

In response to this:

Version(s): 4.19+

Issue: https://issues.redhat.com/browse/OSDOCS-14879

Link to docs preview: https://94480--ocpdocs-pr.netlify.app/openshift-enterprise/latest/networking/configuring_ingress_cluster_traffic/ingress-gateway-api.html#nw-ingress-gateway-api-enable_ingress-gateway-api

QE review:

QE has approved this change.

Additional information:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

candita · 2025-06-11T16:31:50Z

/assign @candita
/assign @grzpiotrowski

@jldohmann would you mind waiting to merge until the two of us lgtm and approve?

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

candita · 2025-06-11T16:54:14Z

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

+
+[source,terminal]
+----
+$ oc -n openshift-ingress create secret tls gwapi-wildcard --cert=wildcard.crt --key=wildcard.key


Does it tell them anywhere how to create the wildcard.crt and wildcard.key?

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

In the tech preview guides we had this bit of context about the creation of a secret:

Certificates are handled differently in Gateway API compared to OpenShift Route objects. Gateway API uses references to Kubernetes Secret objects whereas the OpenShift Route API embeds the certificate and key strings in the Route object.

WDYT about including it here @candita?

I think we could do this in a followup.

Actually after seeing What's New in 4.19, I think that the statement I quoted is not longer true as Routes can reference Secrets too.

@grzpiotrowski @candita so to clarify, is the request to add that snippet within this doc or create a new procedure for handling secrets for Gateway API?

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

grzpiotrowski · 2025-06-13T16:04:29Z

/lgtm
I'm ok with the changes I suggested to be included as a follow-up. Leaving the approve as @candita and @rhamini3 are going to have another pass too before merge.

rhamini3 · 2025-06-13T16:16:50Z

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

+= 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.
+


This part is a bit confusing for me, If the user is using 4.19+ gatewayAPI is already enabled with the proper CRDs. From my understanding, the subscription, and operator are only installed after a gatewayclass is created.
CC @candita

I think this is ok for now, but we could follow up after the docs freeze. The reader doesn't need to know all the specifics.

Suggestion in https://github.com/openshift/openshift-docs/pull/94480/files#r2145713754

rhamini3 · 2025-06-13T16:18:48Z

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

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


the gateway does not have to be in openshift-ingress namespace, might be better to change this to if it isn't created in openshift-ingress there will be no DNS management

In the Getting Started guide, it's ok to get them started without extra work for DNS.

rhamini3 · 2025-06-13T16:19:48Z

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

+      type: Published
+    dnsZone:
+      id: ...
+----


not finding the right output when using that command, this command has correct output
oc -n openshift-ingress get dnsrecord -l gateway.networking.k8s.io/gateway-name=example-gateway -o yaml

@kalexand-rh @jldohmann Can this be fixed before merge?

rhamini3 · 2025-06-13T16:55:46Z

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

+----
+NAME              TYPE           CLUSTER-IP   EXTERNAL-IP         PORT(S)      AGE
+example-gateway   LoadBalancer   10.1.2.3     <external_ipname>   <port_info>  47s
+----


the example output and oc command should be updated, the name of the service and deployment is not the same as the gateway name, it has a post-fix openshift-default (gatewayClass name)

iamin@iamin-mac Downloads % oc -n openshift-ingress get deployment NAME READY UP-TO-DATE AVAILABLE AGE example-gateway-openshift-default 1/1 1 1 3m52s istiod-openshift-gateway 1/1 1 1 16m router-default 2/2 2 2 80m iamin@iamin-mac Downloads % oc -n openshift-ingress get service NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE example-gateway-openshift-default LoadBalancer 172.30.168.184 a31cac2304a8249b697976d111041eeb-1454708237.us-east-2.elb.amazonaws.com 15021:30345/TCP,443:31776/TCP 4m16s istiod-openshift-gateway ClusterIP 172.30.211.131 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 16m router-default LoadBalancer 172.30.15.214 a20263ea8928442b1986ef3c08bfc7bb-1704144520.us-east-2.elb.amazonaws.com 80:30266/TCP,443:31405/TCP 80m router-internal-default ClusterIP 172.30.225.70 <none>

@kalexand-rh @jldohmann is there any way this can be fixed before docs freeze?

These commands would also need to change:
[source,terminal]

$ oc get deployment -n openshift-ingress example-gateway-openshift-default

[source,terminal]

$ oc get service -n openshift-ingress example-gateway-openshift-default

rhamini3 · 2025-06-13T17:10:11Z

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

+
+[source,terminal]
+----
+$ curl -I -cacert <local cert file> https://example.gwapi.${DOMAIN}:443


Suggested change

$ curl -I -cacert <local cert file> https://example.gwapi.${DOMAIN}:443

$ curl -I --cacert /tmp/gwapi/ca.crt https://example.gwapi.${DOMAIN}:443

Hm, the "-k" means don't validate certs. Is it really needed?

I noticed that in my cluster without the -k I get error:

curl: (60) SSL: certificate subject name '*.apps.iamin-aws0613.qe.devcluster.openshift.com' does not match target host name 'example.gwapi.apps.iamin-aws0613.qe.devcluster.openshift.com' More details here: https://curl.se/docs/sslcerts.html curl failed to verify the legitimacy of the server and therefore could not establish a secure connection to it. To learn more about this situation and how to fix it, please visit the web page mentioned above.

-k not needed

@kalexand-rh the "--cacert" is needed, please accept @rhamini3 's suggestion.

candita · 2025-06-13T17:29:37Z

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

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


This would need to change per https://github.com/openshift/openshift-docs/pull/94480/files#r2145462579:

Suggested change

.. 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:

.. 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:

candita · 2025-06-13T17:30:09Z

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

+
+[source,terminal]
+----
+$ oc get dnsrecord -n openshift-ingress -l istio.io/gateway-name=example-gateway -o yaml


https://github.com/openshift/openshift-docs/pull/94480/files#r2145462579 should be here.

candita · 2025-06-13T17:46:18Z

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

 [source,terminal]
 ----
-httproute.gateway.networking.k8s.io/http created
+httproute.gateway.networking.k8s.io/http example-route


Should be:
httproute.gateway.networking.k8s.io/example-route created

candita · 2025-06-13T17:56:47Z

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

+
+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.
+
+.. Optional: Verify that the new deployment, `istio-ingressgateway` is ready and available:


Suggested change

.. Optional: Verify that the new deployment, `istio-ingressgateway` is ready and available:

.. Optional: Verify that the new deployment, `istiod-openshift-gateway` is ready and available:

candita · 2025-06-13T17:57:52Z

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

+router-default             2/2     2            2           6h4m
+----
+
+. Create a secret by using the default certificate by running the following command:


Suggested change

. Create a secret by using the default certificate by running the following command:

. Create a secret by running the following command:

candita · 2025-06-13T18:01:35Z

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

+[source,terminal]
+----
+$ oc get service -n openshift-ingress example-gateway-openshift-default
+----
+
+.Example output
+[source,terminal]
+----
+NAME              READY   UP-TO-DATE   AVAILABLE   AGE
+example-gateway   1/1     1            1           25s
+----


nit: might want to swap the positions of these two, putting the example output with the corresponding command.

They should both be named "example-gateway-openshift-default" in the output.

candita · 2025-06-13T18:07:30Z

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

+[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.


Suggested change

When you enable Gateway API, it installs the subscription, the Istio operator, the custom resource definitions (CRDs), and creates the Istio resources.

When you create a GatewayClass as shown in the first step, it configures Gateway API for use on your cluster.

candita · 2025-06-13T18:31:39Z

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

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


This can be handled in a follow up.

Suggested change

<5> The name of the previously created secret using the default certificate.

<5> The name of the previously created secret.

candita · 2025-06-13T18:33:45Z

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

+[source,terminal]
+----
+NAME              READY   UP-TO-DATE   AVAILABLE   AGE
+example-gateway   1/1     1            1           25s


Suggested change

example-gateway 1/1 1 1 25s

example-gateway-openshift-default 1/1 1 1 25s

candita · 2025-06-13T18:36:06Z

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

+  rules: <4>
+  - backendRefs:


Suggested change

rules: <4>

- backendRefs:

rules:

- backendRefs: <4>

candita · 2025-06-13T18:41:09Z

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

+      id: ...
+----
+
+. Create an `HTTPRoute` resource that directs requests to your application:


Suggested change

. Create an `HTTPRoute` resource that directs requests to your application:

. Create an `HTTPRoute` resource that directs requests to your already-created namespace and application called `example-app/example-app`:

candita · 2025-06-13T18:57:11Z

Thanks @kalexand-rh !

/lgtm
/approve

openshift-ci · 2025-06-13T18:59:36Z

New changes are detected. LGTM label has been removed.

candita · 2025-06-13T19:03:00Z

/lgtm

openshift-ci · 2025-06-13T19:11:12Z

@jldohmann: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

kalexand-rh · 2025-06-13T19:14:15Z

/cherrypick enterprise-4.19

openshift-cherrypick-robot · 2025-06-13T19:15:32Z

@kalexand-rh: new pull request created: #94790

Details

In response to this:

/cherrypick enterprise-4.19

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

jldohmann added this to the Planned for 4.19 GA milestone Jun 9, 2025

jldohmann added the branch/enterprise-4.19 label Jun 9, 2025

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Jun 9, 2025

openshift-ci bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Jun 9, 2025

jldohmann force-pushed the OSDOCS-14879 branch from 4cfe574 to b5cf8dc Compare June 9, 2025 20:52

jldohmann added the peer-review-needed Signifies that the peer review team needs to review this PR label Jun 10, 2025

lahinson added peer-review-in-progress Signifies that the peer review team is reviewing this PR and removed peer-review-needed Signifies that the peer review team needs to review this PR labels Jun 10, 2025

lahinson reviewed Jun 10, 2025

View reviewed changes

lahinson added peer-review-done Signifies that the peer review team has reviewed this PR and removed peer-review-in-progress Signifies that the peer review team is reviewing this PR labels Jun 10, 2025

candita reviewed Jun 10, 2025

View reviewed changes

modules/nw-ingress-gateway-api-enable.adoc Outdated Show resolved Hide resolved

candita reviewed Jun 10, 2025

View reviewed changes

modules/nw-ingress-gateway-api-enable.adoc Outdated Show resolved Hide resolved

candita reviewed Jun 10, 2025

View reviewed changes

modules/nw-ingress-gateway-api-overview.adoc Outdated Show resolved Hide resolved

candita reviewed Jun 10, 2025

View reviewed changes

modules/nw-ingress-gateway-api-overview.adoc Outdated Show resolved Hide resolved

openshift-ci bot added the qe-approved Signifies that QE has signed off on this PR label Jun 10, 2025

openshift-ci bot assigned candita and grzpiotrowski Jun 11, 2025

candita reviewed Jun 11, 2025

View reviewed changes

modules/nw-ingress-gateway-api-enable.adoc Show resolved Hide resolved

candita reviewed Jun 11, 2025

View reviewed changes

modules/nw-ingress-gateway-api-enable.adoc Show resolved Hide resolved

candita reviewed Jun 11, 2025

View reviewed changes

modules/nw-ingress-gateway-api-enable.adoc Outdated Show resolved Hide resolved

candita reviewed Jun 11, 2025

View reviewed changes

modules/nw-ingress-gateway-api-enable.adoc Show resolved Hide resolved

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Jun 13, 2025

rhamini3 reviewed Jun 13, 2025

View reviewed changes

candita reviewed Jun 13, 2025

View reviewed changes

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Jun 13, 2025

candita reviewed Jun 13, 2025

View reviewed changes

kalexand-rh force-pushed the OSDOCS-14879 branch from 637777d to 5901380 Compare June 13, 2025 17:52

candita reviewed Jun 13, 2025

View reviewed changes

openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Jun 13, 2025

add enablement procedure

d38c6f6

kalexand-rh force-pushed the OSDOCS-14879 branch from 46d0486 to d38c6f6 Compare June 13, 2025 18:59

openshift-ci bot removed the lgtm Indicates that a PR is ready to be merged. label Jun 13, 2025

kalexand-rh merged commit 7f121b4 into openshift:main Jun 13, 2025
2 checks passed

openshift-cherrypick-robot mentioned this pull request Jun 13, 2025

[enterprise-4.19] OSDOCS-14879: add enablement procedure #94790

Merged

jldohmann deleted the OSDOCS-14879 branch June 17, 2025 15:21

		= 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.

	$ curl -I -cacert <local cert file> https://example.gwapi.${DOMAIN}:443
	$ curl -I --cacert /tmp/gwapi/ca.crt https://example.gwapi.${DOMAIN}:443

	.. 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:
	.. 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:

	.. Optional: Verify that the new deployment, `istio-ingressgateway` is ready and available:
	.. Optional: Verify that the new deployment, `istiod-openshift-gateway` is ready and available:

	. Create a secret by using the default certificate by running the following command:
	. Create a secret by running the following command:

	When you enable Gateway API, it installs the subscription, the Istio operator, the custom resource definitions (CRDs), and creates the Istio resources.
	When you create a GatewayClass as shown in the first step, it configures Gateway API for use on your cluster.

	<5> The name of the previously created secret using the default certificate.
	<5> The name of the previously created secret.

	example-gateway 1/1 1 1 25s
	example-gateway-openshift-default 1/1 1 1 25s

	. Create an `HTTPRoute` resource that directs requests to your application:
	. Create an `HTTPRoute` resource that directs requests to your already-created namespace and application called `example-app/example-app`:

Conversation

jldohmann commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Jun 9, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Jun 9, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jldohmann commented Jun 10, 2025

Uh oh!

lahinson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rhamini3 commented Jun 10, 2025

Uh oh!

openshift-ci-robot commented Jun 10, 2025 • edited by openshift-ci bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

candita commented Jun 11, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

grzpiotrowski commented Jun 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

candita Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rhamini3 Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jldohmann commented Jun 9, 2025 •

edited

Loading

openshift-ci-robot commented Jun 9, 2025 •

edited by openshift-ci bot

Loading

ocpdocs-previewbot commented Jun 9, 2025 •

edited

Loading

openshift-ci-robot commented Jun 9, 2025 •

edited by openshift-ci bot

Loading

openshift-ci-robot commented Jun 10, 2025 •

edited by openshift-ci bot

Loading

candita Jun 13, 2025 •

edited

Loading

rhamini3 Jun 13, 2025 •

edited

Loading