TELCODOCS-754: Added prerequisite and installation modules for AI SaaS..

Author: johnwilkins

_topic_maps/_topic_map.yml

@@ -290,6 +290,10 @@ Topics:
   Topics:
   - Name: Installing an on-premise cluster using the Assisted Installer
     File: installing-on-prem-assisted
+  - Name: Preparing to install
+    File: assisted-installer-preparing-to-install
+  - Name: Installing with the Assisted Installer
+    File: assisted-installer-installing
 - Name: Installing on a single node
   Dir: installing_sno
   Distros: openshift-enterprise

installing/installing_on_prem_assisted/assisted-installer-installing.adoc

@@ -0,0 +1,57 @@
+:_content-type: ASSEMBLY
+[id="installing-with-ai"]
+= Installing with the Assisted Installer
+include::_attributes/common-attributes.adoc[]
+:context: assisted-installer-installing
+
+toc::[]
+
+After you ensure the cluster nodes and network requirements are met, you can begin installing the cluster.
+
+include::modules/assisted-installer-pre-installation-considerations.adoc[leveloffset=+1]
+
+include::modules/assisted-installer-setting-the-cluster-details.adoc[leveloffset=+1]
+
+include::modules/assisted-installer-configuring-host-network-interfaces.adoc[leveloffset=+1]
+
+[role="_additional_resources"]
+.Additional resources
+* xref:../installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#configuring-host-network-interfaces-in-the-install-config-yaml-file_ipi-install-installation-workflow[Configuring network interfaces]
+
+* link:http://nmstate.io[NMState version 2.1.4]
+
+include::modules/assisted-installer-adding-hosts-to-the-cluster.adoc[leveloffset=+1]
+
+include::modules/installing-with-usb-media.adoc[leveloffset=+1]
+
+include::modules/assisted-installer-booting-with-a-usb-drive.adoc[leveloffset=+1]
+
+include::modules/install-booting-from-an-iso-over-http-redfish.adoc[leveloffset=+1]
+
+[role="_additional_resources"]
+.Additional resources
+
+* xref:../installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#bmc-addressing_ipi-install-installation-workflow[BMC addressing].
+
+* xref:../installing_bare_metal_ipi/ipi-install-prerequisites.adoc#ipi-install-firmware-requirements-for-installing-with-virtual-media_ipi-install-prerequisites[Firmware requirements for installing with virtual media]
+
+include::modules/assisted-installer-configuring-hosts.adoc[leveloffset=+1]
+
+include::modules/assisted-installer-configuring-networking.adoc[leveloffset=+1]
+
+include::modules/assisted-installer-installing-the-cluster.adoc[leveloffset=+1]
+
+include::modules/assisted-installer-completing-the-installation.adoc[leveloffset=+1]
+
+
+[role="_additional_resources"]
+[id="ai-saas-installing-additional-resources_{context}"]
+== Additional resources
+
+* xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-installing-cli_cli-developer-commands[Installing the OpenShift CLI].
+
+* xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-logging-in_cli-developer-commands[Logging in to the OpenShift CLI]
+
+* xref:../../post_installation_configuration/preparing-for-users.adoc#creating-cluster-admin_post-install-preparing-for-users[Creating a cluster admin]
+
+* xref:../../post_installation_configuration/preparing-for-users.adoc#removing-kubeadmin_post-install-preparing-for-users[Removing the kubeadmin user]

installing/installing_on_prem_assisted/assisted-installer-preparing-to-install.adoc

@@ -0,0 +1,26 @@
+:_content-type: ASSEMBLY
+[id="preparing-to-install-with-ai"]
+= Preparing to install with the Assisted Installer
+include::_attributes/common-attributes.adoc[]
+:context: assisted-installer-preparing-to-install
+
+toc::[]
+
+Before installing a cluster, you must ensure the cluster nodes and network meet the requirements.
+
+[id="assisted-installer-prerequisites"]
+== 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].
+* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it] so that {ai-full} can access the resources it requires to function.
+
+include::modules/assisted-installer-assisted-installer-prerequisites.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="ai-saas-preparing--to-install-additional-resources_{context}"]
+== Additional resources
+
+* xref:../installing_bare_metal_ipi/ipi-install-prerequisites.adoc#ipi-install-firmware-requirements-for-installing-with-virtual-media_ipi-install-prerequisites[Firmware requirements for installing with virtual media]
+
+* xref:../installing_bare_metal_ipi/ipi-install-prerequisites.html#network-requirements-increase-mtu_ipi-install-prerequisites[Increase the network MTU]

installing/installing_on_prem_assisted/installing-on-prem-assisted.adoc

@@ -2,21 +2,15 @@
 [id="installing-on-prem-assisted"]
 = Installing an on-premise cluster using the {ai-full}
 include::_attributes/common-attributes.adoc[]
-:context: installing-one-prem-assisted
+:context: installing-on-prem-assisted
 
 toc::[]
 
-You can install {product-title} on on-premise hardware or on-premise VMs using the {ai-full}. The {ai-full} provides you with more options for customization than an installer-provisioned installation, while still running pre-flight validations and using smart defaults.
+You can install {product-title} on on-premise hardware or on-premise VMs using the {ai-full}. Installing {product-title} using the {ai-full} supports both x86-64 and arm64 CPU architectures.
 
-Installing {product-title} using the {ai-full} supports both x86-64 and arm64 CPU architectures.
+include::modules/assisted-installer-using-the-assisted-installer.adoc[leveloffset=+1]
 
 [id="assisted-installer-api-support-policy"]
 == API support for the {ai-full}
 
 Supported APIs for the {ai-full} are stable for a minimum of three months from the announcement of deprecation.
-
-
-//Removed per comments in https://issues.redhat.com/browse/TELCODOCS-655
-//include::modules/assisted-installer-release-notes.adoc[leveloffset=+1]
-
-include::modules/assisted-installer-using-the-assisted-installer.adoc[leveloffset=+1]

modules/assisted-installer-adding-hosts-to-the-cluster.adoc

@@ -0,0 +1,25 @@
+// This is included in the following assemblies:
+//
+// assisted-installer-installing.adoc
+
+:_content-type: PROCEDURE
+[id="adding-hosts-to-the-cluster_{context}"]
+= Adding hosts to the cluster
+
+You must add one or more hosts to the cluster. Adding a host to the cluster involves generating a discovery ISO. The discovery ISO runs {op-system-first} in-memory with an agent. Perform the following procedure for each host on the cluster.
+
+.Procedure
+
+. Click the *Add hosts* button and select the installation media.
+
+.. Select *Minimal image file: Provision with virtual media* to download a smaller image that will fetch the data needed to boot. The nodes must have virtual media capability. This is the recommended method.
+
+.. Select *Full image file: Provision with physical media* to download the larger full image.
+
+. Add an SSH public key so that you can connect to the cluster nodes as the `core` user. Having a login to the cluster nodes can provide you with debugging information during the installation.
+
+. Optional: If the cluster hosts are behind a firewall that requires the use of a proxy, select *Configure cluster-wide proxy settings*. Enter the username, password, IP address and port for the HTTP and HTTPS URLs of the proxy server.
+
+. Click *Generate Discovery ISO*.
+
+. Download the discovery ISO.

modules/assisted-installer-assisted-installer-prerequisites.adoc

@@ -0,0 +1,60 @@
+// This is included in the following assemblies:
+//
+// installing-on-prem-assisted.adoc
+:_content-type: CONCEPT
+
+[id='assisted-installer-prerequisites_{context}']
+= Assisted Installer prerequisites
+
+The {ai-full} validates the following prerequisites to ensure successful installation.
+
+== Hardware
+
+For control plane nodes or the {sno} node, nodes must have at least the following resources:
+
+* 8 CPU cores
+* 16.00 GiB RAM
+* 100 GB storage
+* 10ms write speed or less for etcd `wal_fsync_duration_seconds`
+
+For worker nodes, each node must have at least the following resources:
+
+* 4 CPU cores
+* 16.00 GiB RAM
+* 100 GB storage
+
+== Networking
+
+The network must meet the following requirements:
+
+* A DHCP server unless using static IP addressing.
+* A base domain name. You must ensure that the following requirements are met:
+  - There is no wildcard, such as `*.<cluster_name>.<base_domain>`, or the installation will not proceed.
+  - A DNS A/AAAA record for `api.<cluster_name>.<base_domain>`.
+  - A DNS A/AAAA record with a wildcard for `*.apps.<cluster_name>.<base_domain>`.
+* Port `6443` is open for the API URL if you intend to allow users outside the firewall to access the cluster via the `oc` CLI tool.
+* Port `443` is open for the console if you intend to allow users outside the firewall to access the console.
+
+[IMPORTANT]
+====
+DNS A/AAAA record settings at top-level domain registrars can take significant time to update. Ensure the A/AAAA record DNS settings are working before installation to prevent installation delays.
+====
+
+The {product-title} cluster's network must also meet the following requirements:
+
+* Connectivity between all cluster nodes
+* Connectivity for each node to the internet
+* Access to an NTP server for time synchronization between the cluster nodes
+
+== Preflight validations
+
+The {ai-full} ensures the cluster meets the prerequisites before installation, because it eliminates complex post-installation troubleshooting, thereby saving significant amounts of time and effort. Before installing software on the nodes, the {ai-full} conducts the following validations:
+
+* Ensures network connectivity
+* Ensures sufficient network bandwidth
+* Ensures connectivity to the registry
+* Ensures time synchronization between cluster nodes
+* Verifies that the cluster nodes meet the minimum hardware requirements
+* Validates the installation configuration parameters
+
+If the {ai-full} does not successfully validate the foregoing requirements, installation will not proceed.

modules/assisted-installer-booting-with-a-usb-drive.adoc

@@ -0,0 +1,17 @@
+// This is included in the following assemblies:
+//
+// installing_sno/install-sno-installing-sno.adoc
+
+:_content-type: PROCEDURE
+[id="booting-with-a-usb-drive_{context}"]
+= Booting with a USB drive
+
+To register nodes with the {ai-full} using a bootable USB drive, use the following procedure.
+
+.Procedure
+
+. Attach the {op-system} discovery ISO to the target host.
+
+. Configure the boot drive order in the server BIOS settings to boot from the attached discovery ISO, and then reboot the server.
+
+. On the administration host, return to the browser. Wait for the host to appear in the list of discovered hosts.

modules/assisted-installer-completing-the-installation.adoc

@@ -0,0 +1,57 @@
+// This is included in the following assemblies:
+//
+// assisted-installer-installing.adoc
+
+:_content-type: PROCEDURE
+[id="completing-the-installation_{context}"]
+= Completing the installation
+
+After the cluster is installed and initialized, the {ai-full} indicates that the installation is finished. The {ai-full} provides the console URL, the `kubeadmin` username and password, and the `kubeconfig` file. Additionally, the {ai-full} provides cluster details including the {product-title} version, base domain, CPU architecture, API and Ingress IP addresses, and the cluster and service network IP addresses.
+
+.Prerequisites
+
+* You have installed the `oc` CLI tool.
+
+
+.Procedure
+
+. Make a copy of the `kubeadmin` username and password.
+
+. Download the `kubeconfig` file and copy it to the `auth` directory under your working directory:
++
+[source,terminal]
+----
+$ mkdir -p <working_directory>/auth
+----
++
+[source,terminal]
+----
+$ cp kubeadmin <working_directory>/auth
+----
++
+[NOTE]
+====
+The `kubeconfig` file is available for download for 24 hours after completing the installation.
+====
+
+. Add the `kubeconfig` file to your environment:
++
+[source,terminal]
+----
+$ export KUBECONFIG=<your working directory>/auth/kubeconfig
+----
+
+. Login with the `oc` CLI tool:
++
+[source,terminal]
+----
+$ oc login -u kubeadmin -p <password>
+----
++
+Replace `<password>` with the password of the `kubeadmin` user.
+
+. Click on the web console URL or click *Launch OpenShift Console* to open the console.
+
+. Enter the `kubeadmin` username and password. Follow the instructions in the {product-title} console to configure an identity provider and configure alert receivers.
+
+. Add a bookmark of the {product-title} console.

modules/assisted-installer-configuring-host-network-interfaces.adoc

@@ -0,0 +1,31 @@
+// This is included in the following assemblies:
+//
+// assisted-installer-installing.adoc
+
+:_content-type: PROCEDURE
+[id="configuring-host-network-interfaces_{context}"]
+= Optional: Configuring host network interfaces
+
+The {ai-full} supports IPv4 networking and dual stack networking. The {ai-full} also supports configuring host network interfaces with the NMState library, a declarative network manager API for hosts. You can use NMState to deploy hosts with static IP addressing, bonds, VLANs and other advanced networking features. If you chose to configure host network interfaces, you must set network-wide configurations. Then, you must create a host-specific configuration for each host and generate the discovery ISO with the host-specific settings.
+
+.Procedure
+
+. Select the internet protocol version. Valid options are *IPv4* and *Dual stack*.
+
+. If the cluster hosts are on a shared VLAN, enter the VLAN ID.
+
+. Enter the network-wide IP addresses. If you selected *Dual stack* networking, you must enter both IPv4 and IPv6 addresses.
+
+.. Enter the cluster network's IP address range in CIDR notation.
+
+.. Enter the default gateway IP address.
+
+.. Enter the DNS server IP addresss.
+
+. Enter the host-specific configuration.
+
+.. If you are only setting a static IP address that uses a single network interface, use the form view to enter the IP address and the MAC address for the host.
+
+.. If you are using multiple interfaces, bonding, or other advanced networking features, use the YAML view and enter the desired network state for the host using NMState syntax.
+
+.. Add the MAC address and interface name for each interface used in your network configuration.

modules/assisted-installer-configuring-hosts.adoc

@@ -0,0 +1,25 @@
+// This is included in the following assemblies:
+//
+// assisted-installer-installing.adoc
+
+:_content-type: PROCEDURE
+[id="configuring-hosts_{context}"]
+= Configuring hosts
+
+After booting the hosts with the discovery ISO, the hosts will appear in the table at the bottom of the page. You can configure the hostname, role, and installation disk for each host.
+
+.Procedure
+
+. Select a host.
+
+. From the *Actions* list, select *Change hostname*. You must ensure each host has a valid and unique hostname. If necessary, enter a new name for the host and click *Change*.
+
+. For multi-host clusters, in the *Role* column next to the host name, you can click on the menu to change the role of the host.
++
+If you do not select a role, the {ai-full} will assign the role automatically. The minimum hardware requirements for control plane nodes exceed that of worker nodes. If you assign a role to a host, ensure that you assign the control plane role to hosts that meet the minimum hardware requirements.
+
+. To the left of the checkbox next to a host name, click to expand the host details. If you have multiple disk drives, you can select a different disk drive to act as the installation disk.
+
+. Repeat this procedure for each host.
+
+Once all cluster hosts appear with a status of *Ready*, proceed to the next step.