Skip to content

Commit ad72fa7

Browse files
bscott-rhbscott-rh
authored
Merge pull request #110719 from openshift-cherrypick-robot/cherry-pick-108507-to-enterprise-4.22
[enterprise-4.22] OSDOCS-18134: JTBD Docs Enhancement Gateway API Statuses
2 parents 4916184 + 1d25b02 commit ad72fa7

14 files changed

Lines changed: 477 additions & 0 deletions

‎_topic_maps/_topic_map.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1793,6 +1793,10 @@ Topics:
17931793
File: ingress-controller-dnsmgt
17941794
- Name: Gateway API with OpenShift Container Platform networking
17951795
File: ingress-gateway-api
1796+
- Name: Configuring Gateway API
1797+
Dir: configuring_gateway_api
1798+
Distros: openshift-enterprise,openshift-origin
1799+
Topics:
17961800
- Name: Controlling incoming traffic with Gateway listeners
17971801
File: controlling-incoming-traffic-gateway-listeners
17981802
- Name: Assigning network addresses to gateways
@@ -1801,6 +1805,8 @@ Topics:
18011805
File: routing-http-requests-to-services
18021806
- Name: Routing gRPC requests to services
18031807
File: routing-grpc-requests-to-services
1808+
- Name: Verifying Gateway infrastructure status
1809+
File: verifying-gateway-infrastructure-status
18041810
- Name: Load balancing on OpenStack
18051811
File: load-balancing-openstack
18061812
- Name: Load balancing with MetalLB

‎modules/gateway-listener-status-conditions.adoc‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/verifying-gateway-infrastructure-status.adoc
4+
//
5+
:_mod-docs-content-type: REFERENCE
6+
[id="gateway-listener-status-conditions_{context}"]
7+
= Gateway and listener status conditions reference
8+
9+
[role="_abstract"]
10+
To verify that your gateway is configured in the data plane and ready to route traffic, review its gateway-level and listener-level `status` conditions. A healthy `Gateway` custom resource (CR) reports a status of `True` for its `Accepted` and `Programmed` conditions.
11+
12+
[IMPORTANT]
13+
====
14+
The `Conflicted` listener condition uses negative polarity. This means that a status of `False` indicates a healthy state, while a status of `True` indicates an error.
15+
====
16+
17+
.Gateway-level status conditions
18+
[cols="1,1,3",options="header"]
19+
|===
20+
|Condition |Status |Description and common reasons
21+
22+
|`Accepted`
23+
|`True`
24+
|The gateway configuration is valid and working properly.
25+
26+
|`Accepted`
27+
|`False`
28+
|The configuration has errors. Common reasons include `ListenersNotValid` (one or more listeners have issues) or `InvalidParameters` (the configuration is invalid).
29+
30+
|`Accepted`
31+
|`Unknown`
32+
|The controller has not evaluated the gateway yet.
33+
34+
|`Programmed`
35+
|`True`
36+
|The infrastructure is provisioned and the gateway is configured in the data plane, such as a load balancer or proxy.
37+
38+
|`Programmed`
39+
|`False`
40+
|Programming failed or the data plane is not ready. Common reasons include `NoResources` (insufficient resources or pods unavailable), `Invalid` (cannot apply to the data plane), or `Pending`.
41+
42+
|`Programmed`
43+
|`Unknown`
44+
|Programming is currently in progress.
45+
46+
|`LoadBalancerReady`
47+
|`True`
48+
|The cloud load balancer service for the gateway is successfully provisioned.
49+
50+
|`LoadBalancerReady`
51+
|`False`
52+
|The load balancer service failed to provision or is pending. Common reasons include `ServiceNotFound`, `LoadBalancerPending`, or `SyncLoadBalancerFailed`.
53+
54+
|`DNSReady`
55+
|`True`
56+
|DNS records for all listeners are functioning correctly.
57+
58+
|`DNSReady`
59+
|`False`
60+
|One or more listeners have DNS provisioning issues.
61+
|===
62+
63+
.Listener-level status conditions
64+
[cols="1,1,3",options="header"]
65+
|===
66+
|Condition |Status |Description and common reasons
67+
68+
|`Accepted`
69+
|`True`
70+
|The listener configuration is valid and working properly.
71+
72+
|`Accepted`
73+
|`False`
74+
|The listener configuration has errors.
75+
76+
|`Programmed`
77+
|`True`
78+
|The listener is successfully configured in the data plane.
79+
80+
|`Programmed`
81+
|`False`
82+
|The listener configuration failed in the data plane.
83+
84+
|`ResolvedRefs`
85+
|`True`
86+
|All references, such as TLS certificates, are found and valid.
87+
88+
|`ResolvedRefs`
89+
|`False`
90+
|At least one reference is invalid. Common reasons include `InvalidCertificateRef` (a TLS certificate was not found or is invalid) or `RefNotPermitted` (a cross-namespace reference is not allowed).
91+
92+
|`Conflicted` (Negative polarity)
93+
|`False`
94+
|Healthy state. There are no conflicts.
95+
96+
|`Conflicted` (Negative polarity)
97+
|`True`
98+
|The listener conflicts with another listener. Common reasons include `ProtocolConflict` (multiple listeners on the same port with incompatible protocols) or `HostnameConflict` (overlapping hostnames).
99+
100+
|`DNSReady`
101+
|`True`
102+
|The DNS record for this listener's hostname is successfully provisioned in all reported zones.
103+
104+
|`DNSReady`
105+
|`False`
106+
|The DNS record failed to provision. Common reasons include `FailedZones`, `NoDNSZones`, or `RecordNotFound`.
107+
108+
|`DNSReady`
109+
|`Unknown`
110+
a|The DNS status cannot be determined or is unmanaged.
111+
112+
[NOTE]
113+
====
114+
Listeners without a configured hostname will not have DNS conditions added to their `status`.
115+
====
116+
|===
117+
118+
.Example `Gateway` CR status output showing a DNS failure on one listener
119+
[source,yaml]
120+
----
121+
# ...
122+
status:
123+
  # Gateway-level conditions (LoadBalancer and aggregate DNS status)
124+
  conditions:
125+
  - type: LoadBalancerReady
126+
    status: "True"
127+
    reason: LoadBalancerProvisioned
128+
    message: "The LoadBalancer service is provisioned"
129+
    observedGeneration: 1
130+
    lastTransitionTime: "2025-01-12T10:00:00Z"
131+
  - type: DNSReady
132+
    status: "False"
133+
    reason: SomeListenersNotReady
134+
    message: "One or more listeners have DNS provisioning issues"
135+
    observedGeneration: 1
136+
    lastTransitionTime: "2025-01-12T10:00:00Z"
137+
138+
  # Listener-level conditions (DNS status per listener)
139+
  listeners:
140+
  - name: <stage_http>
141+
    conditions:
142+
    - type: DNSReady
143+
      status: "True"
144+
      reason: NoFailedZones
145+
      message: "The record is provisioned in all reported zones."
146+
      observedGeneration: 1
147+
      lastTransitionTime: "2025-01-12T10:00:00Z"
148+
  - name: <prod_https>
149+
    conditions:
150+
    - type: DNSReady
151+
      status: "False"
152+
      reason: FailedZones
153+
      message: "The record failed to provision in some zones: [<prod.example.com>]"
154+
      observedGeneration: 1
155+
      lastTransitionTime: "2025-01-12T10:00:00Z"
156+
----

‎modules/gatewayclass-status-conditions.adoc‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/verifying-gateway-infrastructure-status.adoc
4+
//
5+
:_mod-docs-content-type: REFERENCE
6+
[id="gatewayclass-status-conditions_{context}"]
7+
= GatewayClass status conditions reference
8+
9+
[role="_abstract"]
10+
To verify that your `GatewayClass` custom resource (CR) is valid and ready to provision gateways, review its `status` conditions. A healthy `GatewayClass` CR reports a status of `True` for core conditions like `Accepted` and `SupportedVersion`.
11+
12+
.`GatewayClass` CR status conditions
13+
[cols="1,1,3",options="header"]
14+
|===
15+
|Condition |Status |Description and common reasons
16+
17+
|`Accepted`
18+
|`True`
19+
|The `GatewayClass` CR is valid and the controller has claimed it.
20+
21+
|`Accepted`
22+
|`False`
23+
|The configuration has errors or was rejected. Common reasons include `InvalidParameters` (referenced parameters are invalid or not found), `Pending` (the controller has not processed the resource yet), or `Unknown` (an unsupported `controllerName` was provided).
24+
25+
|`Accepted`
26+
|`Unknown`
27+
|The `GatewayClass` CR is waiting for the controller to process it.
28+
29+
|`SupportedVersion`
30+
|`True`
31+
|The installed Gateway API version is compatible with the controller.
32+
33+
|`SupportedVersion`
34+
|`False`
35+
|There is a version mismatch. A common reason is `UnsupportedVersion`, which indicates that the custom resource definition (CRD) version does not match the controller requirements.
36+
37+
|`ControllerInstalled`
38+
|`True`
39+
|The Cluster Ingress Operator successfully installed the Gateway API controller.
40+
41+
|`ControllerInstalled`
42+
|`False`
43+
|The installation failed.
44+
45+
|`ControllerInstalled`
46+
|`Unknown`
47+
|The controller has not started the installation yet.
48+
49+
|`CRDsReady`
50+
|`True`
51+
|The Istio CRDs are installed and actively managed by either the Cluster Ingress Operator or OLM.
52+
53+
|`CRDsReady`
54+
|`False`
55+
|The CRDs were installed by a third party or have mixed ownership, preventing the controller from managing them.
56+
57+
|`CRDsReady`
58+
|`Unknown`
59+
|The CRDs are not installed yet.
60+
|===

‎modules/querying-gateway-status-cli.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * networking/ingress_load_balancing/configuring_ingress_cluster_traffic/verifying-gateway-infrastructure-status.adoc
4+
//
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="querying-gateway-status-cli_{context}"]
7+
= Query Gateway infrastructure status using the CLI
8+
9+
[role="_abstract"]
10+
To quickly check the health of your gateway infrastructure, query specific `status` fields using the {product-title} CLI. You can validate your deployment, check route attachments, and retrieve IP addresses without parsing lengthy YAML manifests.
11+
12+
.Prerequisites
13+
14+
* You have access to the cluster as a user with the `cluster-admin` role.
15+
* You have installed the {oc-first}.
16+
* Your gateway is deployed in the `openshift-ingress` namespace.
17+
* Your gateway is managed by the gateway controller (`openshift.io/gateway-controller/v1`).
18+
19+
.Procedure
20+
21+
* Run the relevant command for the status information you need to retrieve:
22+
+
23+
--
24+
** To list all `GatewayClass` custom resources (CRs) in your cluster, run the following command:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc get gatewayclass
29+
----
30+
31+
** To check if a specific `GatewayClass` CR has been accepted by the controller, run the following command:
32+
+
33+
[source,terminal]
34+
----
35+
$ oc get gatewayclass <gatewayclass_name> -o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}'
36+
----
37+
*** `<gatewayclass_name>`: Specify the name of your gateway class.
38+
39+
** To list all `Gateway` custom resources (CRs) across all namespaces, run the following command:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc get gateway -A
44+
----
45+
46+
** To check if a specific `Gateway` CR is successfully programmed in the data plane, run the following command:
47+
+
48+
[source,terminal]
49+
----
50+
$ oc get gateway <gateway_name> -n openshift-ingress -o jsonpath='{.status.conditions[?(@.type=="Programmed")].status}'
51+
----
52+
*** `<gateway_name>`: Specify the name of your gateway.
53+
54+
** To retrieve the IP address assigned to a specific `Gateway` CR, run the following command:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc get gateway <gateway_name> -n openshift-ingress -o jsonpath='{.status.addresses[0].value}'
59+
----
60+
*** `<gateway_name>`: Specify the name of your gateway.
61+
62+
** To check the total number of routes attached to a specific `Gateway` CR, run the following command:
63+
+
64+
[source,terminal]
65+
----
66+
$ oc get gateway <gateway_name> -n openshift-ingress -o jsonpath='{.status.listeners[*].attachedRoutes}'
67+
----
68+
*** `<gateway_name>`: Specify the name of your gateway.
69+
70+
** To watch a specific `Gateway` CR for real-time status changes, run the following command:
71+
+
72+
[source,terminal]
73+
----
74+
$ oc get gateway <gateway_name> -n openshift-ingress -w
75+
----
76+
*** `<gateway_name>`: Specify the name of your gateway.
77+
--

‎networking/ingress_load_balancing/configuring_gateway_api/_attributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../_attributes

‎networking/ingress_load_balancing/configuring_gateway_api/assigning-network-addresses-gateways.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="assigning-network-addresses-gateways"]
3+
= Assigning network addresses to gateways
4+
include::_attributes/common-attributes.adoc[]
5+
:context: assigning-network-addresses-gateways
6+
7+
toc::[]
8+
9+
[role="_abstract"]
10+
You can configure network addresses for your gateway to provide a predictable entry point for external traffic. This ensures that clients can reliably resolve and route requests to your load balancers.
11+
12+
The Gateway API uses addresses to define the specific network locations that are assigned to your `Gateway` resource. In {product-title}, you rely on the Gateway controller to automatically provision and bind the necessary network addresses, such as an external load balancer IP, to your gateway. The controller then populates the `status.addresses` field of the `Gateway` resource with the assigned addresses once they are available.
13+
14+
To successfully assign network addresses to your gateway, complete the following tasks:
15+
16+
* Understand gateway address assignment and types to plan your DNS and load balancer configuration.
17+
* Configure automatic address assignment for a gateway to successfully deploy it without violating manual address constraints.
18+
19+
include::modules/understand-gateway-address-assignment.adoc[leveloffset=+1]
20+
21+
include::modules/configuring-automatic-address-assignment-gateway.adoc[leveloffset=+1]

‎networking/ingress_load_balancing/configuring_gateway_api/controlling-incoming-traffic-gateway-listeners.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="controlling-incoming-traffic-gateway-listeners"]
3+
= Control incoming traffic with gateway listeners
4+
include::_attributes/common-attributes.adoc[]
5+
:context: controlling-incoming-traffic-gateway-listeners
6+
7+
toc::[]
8+
9+
[role="_abstract"]
10+
To control network traffic flow, you can configure Gateway API listeners to define the designated port, protocol, and hostname for your gateway. By configuring listeners, you can specify secure TLS connections, dictate how traffic is terminated, and restrict which application routes are permitted to attach to the gateway.
11+
12+
To successfully manage your incoming traffic with gateway listeners, complete the following tasks:
13+
14+
* Configure listener routing and security settings to define the ports, protocols, hostnames, and TLS certificates for your incoming traffic.
15+
* Understand listener routing conflicts by applying conflict management rules to ensure overlapping hostnames or ports are routed correctly.
16+
* Troubleshoot listener connections by monitoring listener status conditions to identify and resolve configuration errors.
17+
18+
include::modules/configuring-listener-routing-security.adoc[leveloffset=+1]
19+
20+
include::modules/gateway-listener-configuration-reference.adoc[leveloffset=+2]
21+
22+
include::modules/resolving-listener-routing-conflicts.adoc[leveloffset=+1]
23+
24+
include::modules/troubleshooting-listener-conditions.adoc[leveloffset=+1]
25+
26+
include::modules/gateway-listener-troubleshooting-reference.adoc[leveloffset=+2]
27+
28+
[role="_additional-resources"]
29+
[id="additional-resources_{context}"]
30+
== Additional resources
31+
32+
* link:https://gateway-api.sigs.k8s.io/concepts/api-overview/#distinctiveness[Gateway API documentation: Protocol-specific distinctiveness rules]
33+
* link:https://gateway-api.sigs.k8s.io/concepts/hostnames/[Gateway API documentation: Hostnames]

‎networking/ingress_load_balancing/configuring_gateway_api/images‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../images

‎networking/ingress_load_balancing/configuring_gateway_api/modules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../modules

0 commit comments

Comments
 (0)