Merge pull request #103887 from openshift-cherrypick-robot/cherry-pick-103701-to-enterprise-4.21

[enterprise-4.21] [OSDOCS-17528]: Adding troubleshooting docs for HCP subnets

hosted_control_planes/hcp-troubleshooting.adoc

@@ -77,4 +77,16 @@ include::modules/hosted-control-planes-pause-reconciliation.adoc[leveloffset=+1]
 
 include::modules/scale-down-data-plane.adoc[leveloffset=+1]
 
-include::modules/agent-service-failure.adoc[leveloffset=+1]
+include::modules/agent-service-failure.adoc[leveloffset=+1]
+
+include::modules/hcp-ts-internal-subnets.adoc[leveloffset=+1]
+
+include::modules/hcp-ts-ovnkubernetes.adoc[leveloffset=+2]
+
+include::modules/hcp-ts-identical-subnet-fields.adoc[leveloffset=+2]
+
+include::modules/hcp-ts-subnet-cidr-format.adoc[leveloffset=+2]
+
+include::modules/hcp-ts-cidr-overlap.adoc[leveloffset=+2]
+
+include::modules/hcp-ts-nodes-not-ready.adoc[leveloffset=+2]

modules/hcp-ts-cidr-overlap.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-ts-cidr-overlap_{context}"]
+= Avoiding an overlap between OVN subnets and CIDR values
+
+If the configured OVN subnets overlap with the machine classless inter-domain routing (CIDR), service CIDR, cluster network CIDR, or with each other, an error occurs.
+
+.Procedure
+
+* Use subnets that do not overlap with any network CIDR. You can use a CIDR calculator to verify that no overlaps exist.
++
+.Example of configuration with no overlaps
+[source,yaml]
+----
+spec:
+  networking:
+    machineCIDR: 10.0.0.0/16
+    serviceCIDR: 172.30.0.0/16
+    clusterNetwork:
+    - cidr: 10.128.0.0/14
+
+  operatorConfiguration:
+    clusterNetworkOperator:
+      ovnKubernetesConfig:
+        ipv4:
+          internalJoinSubnet: "100.99.0.0/16"
+          internalTransitSwitchSubnet: "100.69.0.0/16"
+----

modules/hcp-ts-identical-subnet-fields.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-ts-identical-subnet-fields_{context}"]
+= Setting CIDR values in internal subnet fields
+
+If the `internalJoinSubnet` field and the `internalTransitSwitchSubnet` field are set to the same CIDR values, an error occurs.
+
+.Procedure
+
+* Use different subnets for each field, as shown in the following example:
++
+[source,yaml]
+----
+# ...
+ovnKubernetesConfig:
+  ipv4:
+    internalJoinSubnet: "100.99.0.0/16"
+    internalTransitSwitchSubnet: "100.69.0.0/16"
+# ...
+----

modules/hcp-ts-internal-subnets.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-ts-internal-subnets_{context}"]
+= Troubleshooting internal subnets for hosted clusters
+
+If you encounter issues releated to subnets on {hcp}, the following information can help you determine the cause and find a resolution. 
+
+The following known limitations exist related to internal subnets on hosted clusters:
+
+* IPv6 subnets are not supported.
+* The {hcp} command-line interface, `hcp`, might not have native flags for the subnet fields. Manual YAML editing or `oc patch` is required.
+* Modifying OVN subnets after you create a cluster triggers a rollout of OVN components, which might cause brief network disruptions.
+* You cannot modify OVN subnet configuration while a cluster update is in progress or scheduled.

modules/hcp-ts-nodes-not-ready.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-ts-nodes-not-ready_{context}"]
+= Resolving a stuck OVN rollout
+
+After you change an existing configuration, the OVN component rollout might take a long time or encounter issues.
+
+.Procedure
+
+. Check the status of the `ovnkube-node` DaemonSet rollout by entering the following command:
++
+[source,terminal]
+----
+$ oc rollout status daemonset/ovnkube-node \
+  -n openshift-ovn-kubernetes \
+  --kubeconfig=hosted-kubeconfig
+----
+
+. Check the pod logs for errors by entering the following command:
++
+[source,terminal]
+----
+$ oc logs -n openshift-ovn-kubernetes \
+  -l app=ovnkube-node \
+  --kubeconfig=hosted-kubeconfig
+----
+
+If the rollout is stuck, you might need to revert the configuration change.

modules/hcp-ts-ovnkubernetes.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-ts-ovnkubernetes_{context}"]
+= Configuring the ovnKubernetesConfig object fails with an error
+
+When you try to configure the `ovnKubernetesConfig` object on a hosted cluster by using a different network type, such as `OpenShiftSDN`, an error occurs because {hcp} works only with the `OVNKubernetes` network type.
+
+.Procedure
+
+* Verify the network type of your hosted cluster by entering the following command:
++
+[source,terminal]
+----
+$ oc get hostedcluster <hosted_cluster_name> -n <hosted_control_plane_namespace> \
+  -o jsonpath='{.spec.networking.networkType}'
+----

modules/hcp-ts-subnet-cidr-format.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-troubleshooting.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-ts-subnet-cidr-format_{context}"]
+= Ensuring a valid IPv4 CIDR format
+
+If you do not specify subnets in a valid CIDR format, an error occurs.
+
+.Procedure
+
+* Ensure that the CIDR format follows the following format:
++
+[source,text]
+----
+X.X.X.X/Y
+----
++
+where:
++
+`X`:: is a value from `0` to `255`. The first octet must not be `0`.
+`Y`:: is a value from `0` to `30`.
+
+.Valid examples
+[source,text]
+----
+100.99.0.0/16
+192.168.1.0/24
+----
+
+.Invalid examples
+[source,text]
+----
+100.99.0.0
+256.1.1.0/16
+0.99.0.0/16
+----