OSDOCS-4638: documenting the agent-tui

_topic_maps/_topic_map.yml

@@ -322,11 +322,11 @@ Topics:
   Dir: installing_with_agent_based_installer
   Distros: openshift-enterprise
   Topics:
-  - Name: Preparing to install with Agent-based installer
+  - Name: Preparing to install with Agent-based Installer
     File: preparing-to-install-with-agent-based-installer
   - Name: Understanding disconnected installation mirroring
     File: understanding-disconnected-installation-mirroring
-  - Name: Installing a cluster with Agent-based installer
+  - Name: Installing a cluster with Agent-based Installer
     File: installing-with-agent-based-installer
   - Name: Preparing an Agent-based installed cluster for the multicluster engine for Kubernetes
     File: preparing-an-agent-based-installed-cluster-for-mce

installing/installing_with_agent_based_installer/installing-with-agent-based-installer.adoc

@@ -6,18 +6,32 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+Use the following procedures to install an {product-title} cluster using the Agent-based Installer.
+
 [id="prerequisites_installing-with-agent-based-installer"]
 == Prerequisites
 
 * You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 
-include::modules/installing-ocp-agent.adoc[leveloffset=+1]
+// This anchor ID is extracted/replicated from the former installing-ocp-agent.adoc module to preserve links.
+[id="installing-ocp-agent_installing-with-agent-based-installer"]
+== Installing {product-title} with the Agent-based Installer
+
+The following procedures deploy a single-node {product-title} in a disconnected environment. You can use these procedures as a basis and modify according to your requirements.
+
+include::modules/installing-ocp-agent-download.adoc[leveloffset=+2]
+
+include::modules/installing-ocp-agent-boot.adoc[leveloffset=+2]
+
+include::modules/installing-ocp-agent-tui.adoc[leveloffset=+2]
+
+include::modules/installing-ocp-agent-verify.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
-* See xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#ipi-install-installation-workflow[Deploying with dual-stack networking].
+* See xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#modifying-install-config-for-dual-stack-network_ipi-install-installation-workflow[Deploying with dual-stack networking].
-* See xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#ipi-install-installation-workflow[Configuring the install-config yaml file].
+* See xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#configuring-the-install-config-file_ipi-install-installation-workflow[Configuring the install-config yaml file].
 * See xref:../../installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc#installation-three-node-cluster_installing-restricted-networks-bare-metal[Configuring a three-node cluster] to deploy three-node clusters in bare metal environments.
 * See xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.adoc#root-device-hints_preparing-to-install-with-agent-based-installer[About root device hints].
 * See link:https://nmstate.io/examples.html[NMState state examples].

modules/installing-ocp-agent-boot.adoc

@@ -3,34 +3,13 @@
 // * installing-with-agent/installing-with-agent.adoc
 
 :_content-type: PROCEDURE
-[id="installing-ocp-agent_{context}"]
+[id="installing-ocp-agent-boot_{context}"]
-= Installing {product-title} with the Agent-based Installer
+= Creating and booting the agent image
 
-The following procedure deploys a single-node {product-title} in a disconnected environment. You can use this procedure as a basis and modify according to your requirements.
+Use this procedure to boot the agent image on your machines.
 
 .Procedure
 
-. Log in to the {product-title} web console using your login credentials.
-
-. Navigate to link:https://console.redhat.com/openshift/create/datacenter[Datacenter].
-+
-image::agent_install.png[]
-
-. Click *Run Agent-based Installer locally*. You are directed to the *Install {product-title} on Bare Metal locally with Agent* page.
-
-. Optional: Alternatively, you can also click *Bare Metal (x86_64)* on the *Select an {product-title} cluster type to create* page. You are directed to the *Create an {product-title} Cluster: Bare Metal* page.
-Then, select *Local Agent-based* to go to the *Install {product-title} on Bare Metal locally with Agent* page.
-+
-image::agent_install_bare_metal.png[]
-
-. Select the operating system and architecture.
-
-. Click *Download Installer* to download and extract the install program.
-
-. You can either download or copy the pull secret by clicking on *Download pull secret* or *Copy pull secret*.
-
-. Click *Download command-line tools* and place the `openshift-install` binary in a directory that is on your `PATH`.
-
 . Install `nmstate` dependency by running the following command:
 +
 [source,terminal]
@@ -66,7 +45,7 @@ compute:
   name: worker
   replicas: 0
 controlPlane:
-  architecture: amd64  
+  architecture: amd64
   hyperthreading: Enabled
   name: master
   replicas: 1
@@ -90,7 +69,7 @@ sshKey: |
 ----
 +
 <1> Specify the system architecture, valid values are `amd64` and `arm64`.
-<2> Required. Specify your cluster name. 
+<2> Required. Specify your cluster name.
 <3> State the cluster network plugin to install. The supported values are `OVNKubernetes` and `OpenShiftSDN`. The default value is `OVNKubernetes`.
 <4> Specify your pull secret.
 <5> Specify your ssh public key.
@@ -104,6 +83,9 @@ If you set the platform to `vSphere` or `baremetal`, you can configure IP addres
 * IPv6
 * IPv4 and IPv6 in parallel (dual-stack)
 
+IPv6 is supported only on bare metal platforms.
+====
++
 .Example of dual-stack networking
 [source,yaml]
 ----
@@ -129,8 +111,6 @@ platform:
     - 192.168.11.4
     - 2001:DB8::5
 ----
-IPv6 is supported only on bare metal platforms.
-====
 
 . Create the `agent-config.yaml` file:
 +
@@ -193,82 +173,3 @@ $ openshift-install --dir <install_directory> agent create image
 NOTE: Red Hat Enterprise Linux CoreOS (RHCOS) supports multipathing on the primary disk, allowing stronger resilience to hardware failure to achieve higher host availability. Multipathing is enabled by default in the agent ISO image, with a default `/etc/multipath.conf` configuration.
 
 . Boot the `agent.x86_64.iso` or `agent.aarch64.iso` image on the bare metal machines.
-
-. Optional: To know when the bootstrap host (which is the rendezvous host) reboots, run the following command:
-
-+
-[source,terminal]
-----
-$ ./openshift-install --dir <install_directory> agent wait-for bootstrap-complete \ <1>
-    --log-level=info <2>
-----
-<1> For `<install_directory>`, specify the path to the directory where the agent ISO was generated.
-<2> To view different installation details, specify `warn`, `debug`, or `error` instead of `info`.
-
-+
-.Example output
-[source,terminal]
-----
-...................................................................
-...................................................................
-INFO Bootstrap configMap status is complete
-INFO cluster bootstrap is complete
-----
-+
-The command succeeds when the Kubernetes API server signals that it has been bootstrapped on the control plane machines.
-
-. To track the progress and verify sucessful installation, run the following command:
-+
-[source,terminal]
-----
-$ openshift-install --dir <install_directory> agent wait-for install-complete <1>
-----
-<1> For `<install_directory>` directory, specify the path to the directory where the agent ISO was generated.
-
-+
-.Example output
-[source,terminal]
-----
-...................................................................
-...................................................................
-INFO Cluster is installed
-INFO Install complete!
-INFO To access the cluster as the system:admin user when using 'oc', run
-INFO     export KUBECONFIG=/home/core/installer/auth/kubeconfig
-INFO Access the OpenShift web-console here: https://console-openshift-console.apps.sno-cluster.test.example.com
-----
-
-
-[NOTE]
-====
-If you are using the optional method of ZTP manifests, you can configure IP address endpoints for cluster nodes through the `AgentClusterInstall.yaml` file in three ways:
-
-* IPv4
-* IPv6
-* IPv4 and IPv6 in parallel (dual-stack)
-
-.Example of dual-stack networking
-[source,yaml]
-----
-apiVIP: 192.168.11.3
-ingressVIP: 192.168.11.4
-clusterDeploymentRef:
-  name: mycluster
-imageSetRef:
-  name: openshift-4.12
-networking:
-  clusterNetwork:
-  - cidr: 172.21.0.0/16
-    hostPrefix: 23
-  - cidr: fd02::/48
-    hostPrefix: 64
-  machineNetwork:
-  - cidr: 192.168.11.0/16
-  - cidr: 2001:DB8::/32
-  serviceNetwork:
-  - 172.22.0.0/16
-  - fd03::/112
-  networkType: OVNKubernetes
-----
-IPv6 is supported only on bare metal platforms.
-====

modules/installing-ocp-agent-download.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * installing-with-agent/installing-with-agent.adoc
+
+:_content-type: PROCEDURE
+[id="installing-ocp-agent-retrieve_{context}"]
+= Downloading the Agent-based Installer
+
+.Procedure
+
+Use this procedure to download the Agent-based Installer and the CLI needed for your installation.
+
+. Log in to the {product-title} web console using your login credentials.
+
+. Navigate to link:https://console.redhat.com/openshift/create/datacenter[Datacenter].
+
+. Click *Run Agent-based Installer locally*.
+
+. Select the operating system and architecture for the *OpenShift Installer* and *Command line interface*.
+
+. Click *Download Installer* to download and extract the install program.
+
+. You can either download or copy the pull secret by clicking on *Download pull secret* or *Copy pull secret*.
+
+. Click *Download command-line tools* and place the `openshift-install` binary in a directory that is on your `PATH`.

modules/installing-ocp-agent-tui.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * installing-with-agent/installing-with-agent.adoc
+
+:_content-type: PROCEDURE
+[id="installing-ocp-agent-tui_{context}"]
+= Verifying that the current installation host can pull release images
+
+After you boot the agent image and network services are made available to the host, the agent console application performs a pull check to verify that the current host can retrieve release images.
+
+If the primary pull check passes, you can quit the application to continue with the installation. If the pull check fails, the application performs additional checks, as seen in the `Additional checks` section of the TUI, to help you troubleshoot the problem. A failure for any of the additional checks is not necessarily critical as long as the primary pull check succeeds.
+
+If there are host network configuration issues that might cause an installation to fail, you can use the console application to make adjustments to your network configurations.
+
+[IMPORTANT]
+====
+If the agent console application detects host network configuration issues, the installation workflow will be halted until the user manually stops the console application and signals the intention to proceed.
+====
+
+.Procedure
+
+. Wait for the agent console application to check whether or not the configured release image can be pulled from a registry.
+
+. If the agent console application states that the installer connectivity checks have passed, wait for the prompt to time out to continue with the installation.
++
+[NOTE]
+====
+You can still choose to view or change network configuration settings even if the connectivity checks have passed.
+
+However, if you choose to interact with the agent console application rather than letting it time out, you must manually quit the TUI to proceed with the installation.
+====
+
+. If the agent console application checks have failed, which is indicated by a red icon beside the `Release image URL` pull check, use the following steps to reconfigure the host's network settings:
+
+.. Read the `Check Errors` section of the TUI.
+This section displays error messages specific to the failed checks.
++
+image::agent-tui-home.png[The home screen of the agent console application  displaying check errors, indicating a failed check]
+
+.. Select *Configure network* to launch the NetworkManager TUI.
+
+.. Select *Edit a connection* and select the connection you want to reconfigure.
+
+.. Edit the configuration and select *OK* to save your changes.
+
+.. Select *Back* to return to the main screen of the NetworkManager TUI.
+
+.. Select *Activate a Connection*.
+
+.. Select the reconfigured network to deactivate it.
+
+.. Select the reconfigured network again to reactivate it.
+
+.. Select *Back* and then select *Quit* to return to the agent console application.
+
+.. Wait at least five seconds for the continuous network checks to restart using the new network configuration.
+
+.. If the `Release image URL` pull check succeeds and displays a green icon beside the URL, select *Quit* to exit the agent console application and continue with the installation.

modules/installing-ocp-agent-verify.adoc

@@ -0,0 +1,90 @@
+// Module included in the following assemblies:
+//
+// * installing-with-agent/installing-with-agent.adoc
+
+:_content-type: PROCEDURE
+[id="installing-ocp-agent-verify_{context}"]
+= Tracking and verifying installation progress
+
+Use the following procedure to track installation progress and to verify a successful installation.
+
+.Procedure
+
+. Optional: To know when the bootstrap host (rendezvous host) reboots, run the following command:
+
++
+[source,terminal]
+----
+$ ./openshift-install --dir <install_directory> agent wait-for bootstrap-complete \ <1>
+    --log-level=info <2>
+----
+<1> For `<install_directory>`, specify the path to the directory where the agent ISO was generated.
+<2> To view different installation details, specify `warn`, `debug`, or `error` instead of `info`.
+
++
+.Example output
+[source,terminal]
+----
+...................................................................
+...................................................................
+INFO Bootstrap configMap status is complete
+INFO cluster bootstrap is complete
+----
++
+The command succeeds when the Kubernetes API server signals that it has been bootstrapped on the control plane machines.
+
+. To track the progress and verify successful installation, run the following command:
++
+[source,terminal]
+----
+$ openshift-install --dir <install_directory> agent wait-for install-complete <1>
+----
+<1> For `<install_directory>` directory, specify the path to the directory where the agent ISO was generated.
+
++
+.Example output
+[source,terminal]
+----
+...................................................................
+...................................................................
+INFO Cluster is installed
+INFO Install complete!
+INFO To access the cluster as the system:admin user when using 'oc', run
+INFO     export KUBECONFIG=/home/core/installer/auth/kubeconfig
+INFO Access the OpenShift web-console here: https://console-openshift-console.apps.sno-cluster.test.example.com
+----
+
+
+[NOTE]
+====
+If you are using the optional method of ZTP manifests, you can configure IP address endpoints for cluster nodes through the `AgentClusterInstall.yaml` file in three ways:
+
+* IPv4
+* IPv6
+* IPv4 and IPv6 in parallel (dual-stack)
+
+IPv6 is supported only on bare metal platforms.
+====
+.Example of dual-stack networking
+[source,yaml]
+----
+apiVIP: 192.168.11.3
+ingressVIP: 192.168.11.4
+clusterDeploymentRef:
+  name: mycluster
+imageSetRef:
+  name: openshift-4.13
+networking:
+  clusterNetwork:
+  - cidr: 172.21.0.0/16
+    hostPrefix: 23
+  - cidr: fd02::/48
+    hostPrefix: 64
+  machineNetwork:
+  - cidr: 192.168.11.0/16
+  - cidr: 2001:DB8::/32
+  serviceNetwork:
+  - 172.22.0.0/16
+  - fd03::/112
+  networkType: OVNKubernetes
+----