Adjust install and Cilium migration how-tos to work with pre-configured Cilium k8sServiceHost Helm value

docs/modules/ROOT/pages/how-tos/network/migrate-to-cilium.adoc

@@ -143,20 +143,26 @@ yq eval -i '.parameters.networkpolicy.ignoredNamespaces = ["openshift-oauth-apis
   "${CLUSTER_ID}.yml"
 ----
 
-. Configure component `cilium`.
-We explicitly configure the K8s API endpoint to ensure that the Cilium operator doesn't access the API through the cluster network during the migration.
+. Verify that the cluster's `api-int` DNS record exists
 +
-TIP: When running Cilium with `kubeProxyReplacement=partial`, the API endpoint configuration can be removed after the migration is completed.
+[source,bash]
+----
+export CLUSTER_DOMAIN=$(kubectl get dns cluster -ojsonpath='{.spec.baseDomain}')
+kubectl --as=cluster-admin -n openshift-dns exec ds/node-resolver -- nslookup api-int.${CLUSTER_DOMAIN}
+----
 +
-.Explicitly configure the K8s API endpoint
+[TIP]
+====
+If the command doesn't return a valid record for `api-int`, the Cilium config needs to be adjusted to use the `api` record to ensure that the Kubernetes API can be accessed.
+
 [source,bash]
 ----
-yq -i '.parameters.cilium.cilium_helm_values.k8sServiceHost="api-int.${openshift:baseDomain}"' \
-  "${CLUSTER_ID}.yml" <1>
-yq -i '.parameters.cilium.cilium_helm_values.k8sServicePort="6443"' \
+yq -i '.parameters.cilium.cilium_helm_values.k8sServiceHost="api.${openshift:baseDomain}"' \
   "${CLUSTER_ID}.yml"
 ----
-<1> On vSphere clusters, you may need to use `api.${openshift:baseDomain}`.
+====
+
+. Configure component `cilium`.
 +
 .Configure the cluster Pod and Service CIDRs
 [source,bash]

docs/modules/ROOT/partials/install/install-config-cloudscale-exoscale.adoc

@@ -14,8 +14,8 @@ mkdir -p "${INSTALLER_DIR}"
 cat > "${INSTALLER_DIR}/install-config.yaml" <<EOF
 apiVersion: v1
 metadata:
-  name: ${CLUSTER_ID}
-baseDomain: ${BASE_DOMAIN}
+  name: ${CLUSTER_ID} <1>
+baseDomain: ${BASE_DOMAIN} <1>
 platform:
   none: {}
 networking:
@@ -25,3 +25,5 @@ pullSecret: |
 sshKey: "$(cat $SSH_PUBLIC_KEY)"
 EOF
 ----
+<1> Make sure that the values here match the value of `$CLUSTER_DOMAIN` when combined as `<metadata.name>.<baseDomain>`.
+Otherwise, the installation will most likely fail.

docs/modules/ROOT/partials/install/install-config-openstack.adoc

@@ -24,9 +24,9 @@ EOF
 cat > "${INSTALLER_DIR}/install-config.yaml" <<EOF
 apiVersion: v1
 metadata:
-  name: ${CLUSTER_ID}
-baseDomain: ${BASE_DOMAIN}
-compute: <1>
+  name: ${CLUSTER_ID} <1>
+baseDomain: ${BASE_DOMAIN} <1>
+compute: <2>
   - architecture: amd64
     hyperthreading: Enabled
     name: worker
@@ -37,7 +37,7 @@ compute: <1>
         rootVolume:
           size: 100
           type: __DEFAULT__ # TODO: is this generally applicable?
-        additionalSecurityGroupIDs: <2>
+        additionalSecurityGroupIDs: <3>
           - ${CILIUM_SECURITY_GROUP_ID}
 controlPlane:
   architecture: amd64
@@ -50,11 +50,11 @@ controlPlane:
       rootVolume:
         size: 100
         type: __DEFAULT__ # TODO: is this generally applicable?
-      additionalSecurityGroupIDs: <2>
+      additionalSecurityGroupIDs: <3>
         - ${CILIUM_SECURITY_GROUP_ID}
 platform:
   openstack:
-    cloud: shiftstack <3>
+    cloud: shiftstack <4>
     externalNetwork: ${EXTERNAL_NETWORK_NAME}
     apiFloatingIP: ${API_VIP}
     ingressFloatingIP: ${INGRESS_VIP}
@@ -67,9 +67,11 @@ pullSecret: |
 sshKey: "$(cat $SSH_PUBLIC_KEY)"
 EOF
 ----
-<1> We only provision a single compute machine set.
+<1> Make sure that the values here match the value of `$CLUSTER_DOMAIN` when combined as `<metadata.name>.<baseDomain>`.
+Otherwise, the installation will most likely fail.
+<2> We only provision a single compute machine set.
 The final machine sets will be configured through Project Syn.
-<2> We attach the Cilium security group to both the control plane and the worker nodes.
+<3> We attach the Cilium security group to both the control plane and the worker nodes.
 This ensures that there's no issues with Cilium traffic during bootstrapping.
-<3> This field must match the entry in `clouds` in the `clouds.yaml` file.
+<4> This field must match the entry in `clouds` in the `clouds.yaml` file.
 If you're following this guide, you shouldn't need to adjust this.

docs/modules/ROOT/partials/install/install-config-vsphere.adoc

@@ -12,9 +12,9 @@ mkdir -p "${INSTALLER_DIR}"
 cat > "${INSTALLER_DIR}/install-config.yaml" <<EOF
 apiVersion: v1
 metadata:
-  name: ${CLUSTER_ID}
-baseDomain: ${BASE_DOMAIN}
-compute: <1>
+  name: ${CLUSTER_ID} <1>
+baseDomain: ${BASE_DOMAIN} <1>
+compute: <2>
   - architecture: amd64
     hyperthreading: Enabled
     name: worker
@@ -60,5 +60,7 @@ pullSecret: |
 sshKey: "$(cat $SSH_PUBLIC_KEY)"
 EOF
 ----
-<1> We only provision a single compute machine set.
+<1> Make sure that the values here match the value of `$CLUSTER_DOMAIN` when combined as `<metadata.name>.<baseDomain>`.
+Otherwise, the installation will most likely fail.
+<2> We only provision a single compute machine set.
 The final machine sets will be configured through Project Syn.

docs/modules/ROOT/partials/install/prepare-commodore.adoc

@@ -18,12 +18,51 @@ mkdir -p inventory/classes/
 git clone $(curl -sH"Authorization: Bearer $(commodore fetch-token)" "${COMMODORE_API_URL}/tenants/${TENANT_ID}" | jq -r '.gitRepo.url') inventory/classes/${TENANT_ID}
 ----
 
-. Add Cilium to cluster configuration
+. Configure the cluster's domain in Project Syn
++
+[source,bash]
+----
+export CLUSTER_DOMAIN="${CLUSTER_ID}.${BASE_DOMAIN}" <1>
+----
+<1> Adjust this as necessary if you're using a non-standard cluster domain.
++
+[IMPORTANT]
+====
+The cluster domain configured here must be correct.
+The value is used to configure how Cilium connects to the cluster's K8s API.
+====
 +
 [source,bash]
 ----
 pushd "inventory/classes/${TENANT_ID}/"
 
+yq eval -i ".parameters.openshift.baseDomain = \"${CLUSTER_DOMAIN}\"" \
+  ${CLUSTER_ID}.yml
+
+git commit -a -m "Configure cluster domain for ${CLUSTER_ID}"
+----
+
+. Add Cilium to cluster configuration
++
+[NOTE]
+====
+These instructions assume that Cilium is configured to use `api-int.${CLUSTER_DOMAIN}:6443` to connect to the cluster's K8s API.
+To ensure that that's the case, add the configuration shown below somewhere in the Project Syn config hierarchy.
+
+[source,yaml]
+----
+parameters:
+  cilium:
+    cilium_helm_values:
+      k8sServiceHost: api-int.${openshift:baseDomain}
+      k8sServicePort: "6443"
+----
+
+For VSHN, this configuration is set in the https://git.vshn.net/syn/commodore-defaults/-/merge_requests/1789[Commodore global defaults (internal)].
+====
++
+[source,bash]
+----
 yq eval -i '.applications += ["cilium"]' ${CLUSTER_ID}.yml
 
 yq eval -i '.parameters.networkpolicy.networkPlugin = "cilium"' ${CLUSTER_ID}.yml

docs/modules/ROOT/partials/install/prepare-syn-config.adoc

@@ -18,9 +18,6 @@ fi
 +
 [source,bash,subs="attributes+"]
 ----
-yq eval -i ".parameters.openshift.baseDomain = \"${CLUSTER_DOMAIN}\"" \
-  ${CLUSTER_ID}.yml
-
 yq eval -i ".parameters.openshift.infraID = \"$(jq -r .infraID "${INSTALLER_DIR}/metadata.json")\"" \
   ${CLUSTER_ID}.yml
 

docs/modules/ROOT/partials/install/run-installer.adoc

@@ -25,12 +25,17 @@ yq w -i "${INSTALLER_DIR}/manifests/cluster-ingress-02-config.yml" \
 cp catalog/manifests/cilium/olm/* target/manifests/
 ----
 
-. Extract the cluster domain from the generated manifests
+. Verify that the generated cluster domain matches the desired cluster domain
 +
 [source,bash]
 ----
-export CLUSTER_DOMAIN=$(yq e '.spec.baseDomain' \
+GEN_CLUSTER_DOMAIN=$(yq e '.spec.baseDomain' \
   "${INSTALLER_DIR}/manifests/cluster-dns-02-config.yml")
+if [ "$GEN_CLUSTER_DOMAIN" != "$CLUSTER_DOMAIN" ]; then
+  echo -e "\033[0;31mGenerated cluster domain doesn't match expected cluster domain: Got '$GEN_CLUSTER_DOMAIN', want '$CLUSTER_DOMAIN'\033[0;0m"
+else
+  echo -e "\033[0;32mGenerated cluster domain matches expected cluster domain.\033[0;0m"
+fi
 ----
 
 . Prepare install manifests and ignition config