HCIDOCS-474-OCI: AI installation on OCI bare metal

Author: Talia Shwartzberg

installing/installing_oci/installing-oci-assisted-installer.adoc

@@ -6,7 +6,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-From {product-title} {product-version} and later versions, you can use the {ai-full} to install a cluster on {oci-first} by using infrastructure that you provide.
+You can use the {ai-full} to install a cluster on {oci-first}. This method is recommended for most users, and requires an internet connection.
+
+If you want to set up the cluster manually or using other automation tools, or if you are working in a disconnected environment, you can use the Red Hat Agent-based Installer for the installation. For details, see xref:../../installing/installing_oci/installing-oci-agent-based-installer.adoc#installing-oci-agent-based-installer[Installing a cluster on {oci-first-no-rt} by using the Agent-based Installer].
 
 // The Assisted Installer and OCI overview
 include::modules/installing-oci-about-assisted-installer.adoc[leveloffset=+1]
@@ -15,15 +17,26 @@ include::modules/installing-oci-about-assisted-installer.adoc[leveloffset=+1]
 .Additional resources
 
 * link:https://access.redhat.com/documentation/en-us/assisted_installer_for_openshift_container_platform/[{ai-full} for {product-title}]
+* link:https://docs.oracle.com/en-us/iaas/Content/openshift-on-oci/installing-assisted.htm[Installing a Cluster with Red Hat's {ai-full} (Oracle documentation)]
 * xref:../../installing/installing_platform_agnostic/installing-platform-agnostic.adoc#cluster-entitlements_installing-platform-agnostic[Internet access for {product-title}]
-* link:https://docs.oracle.com/en-us/iaas/Content/Block/Concepts/blockvolumeperformance.htm#vpus[Volume Performance Units (Oracle documentation)]
-* link:https://docs.oracle.com/iaas/Content/openshift-on-oci/installing-agent-about-instance-configurations.htm[Instance Sizing Recommendations for {product-title} on {oci} Nodes (Oracle) documentation]
 
-// Creating OCI resources and services
+// Preparing the OCI environment
 include::modules/creating-oci-resources-services.adoc[leveloffset=+1]
 
 // Using the Assisted Installer to generate an OCI-compatible discovery ISO image
-include::modules/using-assisted-installer-oci-agent-iso.adoc[leveloffset=+1]
+[id="using-assisted-installer-oci-agent-iso_{context}"]
+== Using the {ai-full} to generate an {oci}-compatible discovery ISO image
+
+Create the cluster configuration and generate the discovery ISO image in the {ai-full} web console. 
+
+.Prerequisites
+
+* You created a child compartment and an object storage bucket on {oci}. For details, see _Preparing the {oci} environment_. 
+* You reviewed details about the {product-title} installation and update processes. 
+
+include::modules/using-assisted-installer-oci-create-cluster.adoc[leveloffset=+2]
+
+include::modules/using-assisted-installer-oci-agent-iso.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
@@ -35,7 +48,15 @@ include::modules/using-assisted-installer-oci-agent-iso.adoc[leveloffset=+1]
 include::modules/provision-oci-infrastructure-ocp-cluster.adoc[leveloffset=+1]
 
 // Completing the remaining Assisted Installer steps
-include::modules/complete-assisted-installer-oci.adoc[leveloffset=+1]
+
+[id="completing-assisted-installer-oci_{context}"]
+== Completing the remaining {ai-full} steps
+
+After you provision {oci-first} resources and upload {product-title} custom manifest configuration files to {oci}, you must complete the remaining cluster installation steps on the {ai-full} before you can create an instance {oci}. These steps include assigning node roles and adding custom manifests.
+
+include::modules/complete-assisted-installer-oci-node-roles.adoc[leveloffset=+2]
+
+include::modules/complete-assisted-installer-oci-custom-manifests.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
@@ -52,4 +73,5 @@ include::modules/installing-troubleshooting-assisted-installer-oci.adoc[leveloff
 .Additional resources
 
 * link:https://docs.oracle.com/iaas/Content/openshift-on-oci/openshift-troubleshooting.htm[Troubleshooting {product-title} on {oci} (Oracle documentation)]
+
 * xref:../../installing/installing_on_prem_assisted/installing-on-prem-assisted.adoc#using-the-assisted-installer_installing-on-prem-assisted[Installing an on-premise cluster using the {ai-full}]

modules/complete-assisted-installer-oci-custom-manifests.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="adding-custom-manifests-oci_{context}"]
+= Adding custom manifests
+
+Add the mandatory custom manifests provided by Oracle. For details, see link:https://github.com/dfoster-oracle/oci-openshift/blob/v1.0.0-release-preview/custom_manifests/README.md[Custom Manifests (Oracle documentation).] 
+
+.Prerequisites
+
+* You copied the `dynamic_custom_manifest.yml` file from the Terraform stack in {oci}. For details, see "Provisioning {oci} infrastructure for your cluster". 
+
+.Procedure
+
+. On the *Custom manifests* page, in the *Folder* field, select `manifests`. This is the {ai-full} folder where you want to save the custom manifest file.
+
+. In the *File name* field, enter a filename, for example, `dynamic_custom_manifest.yml`.
+
+. Paste the contents of the `dynamic_custom_manifest.yml` file that you copied from {oci}:
+
+.. In the *Content* section, click the *Paste content* icon. 
+
+.. If you are using Firefox, click *OK* to close the dialog box, and then press *Ctrl+V*. Otherwise, skip this step.  
+
+. Click *Next* to save the custom manifest.
+
+. From the *Review and create* page, click *Install cluster* to create your {product-title} cluster on {oci}.
+
+After the cluster installation and initialization operations, the {ai-full} indicates the completion of the cluster installation operation. For more information, see "Completing the installation" section in the {ai-full} for {product-title} document.

modules/complete-assisted-installer-oci-node-roles.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="assigning-node-roles-oci_{context}"]
+= Assigning node roles
+
+Following host discovery, the role of all nodes appears as *Auto-assign* by default. Change each of the node roles to either *Control Plane node* or *Worker*.
+
+.Prerequisites
+
+* You created and applied the Terraform stack in {oci}. For details, see "Provisioning {oci} infrastructure for your cluster".
+
+.Procedure
+
+. From the {ai-full} user interface, go to the *Host discovery* page.
+
+. Under the *Role* column, select either *Control plane node* or *Worker* for each targeted hostname. Then click *Next*.
++
+[NOTE]
+====
+. Before continuing to the next step, wait for each node to reach `Ready` status.
+. Expand the node to verify that the hardware type is bare metal.
+====
+
+. Accept the default settings for the *Storage* and *Networking* pages. Then click *Next*.

modules/complete-assisted-installer-oci.adoc

@@ -4,16 +4,38 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="creating-oci-resources-services_{context}"]
-= Creating {oci} resources and services
+= Preparing the {oci} environment
 
-Create {oci-first} resources and services so that you can establish infrastructure with governance standards that meets your organization's requirements.
+Before installing {product-title} using Assisted Installer, create the necessary resources and download the configuration file in the {oci} environment.
 
 .Prerequisites
 
-* You configured an {oci} account to host the cluster. See link:https://docs.oracle.com/iaas/Content/openshift-on-oci/install-prereq.htm[Prerequisites (Oracle documentation)].
+* You have an {oci} account to host the cluster. 
+* If you use a firewall and you plan to use a Telemetry service, you configured your firewall to allow {product-title} to access the sites required.
 
 .Procedure
 
 . Log in to your link:https://cloud.oracle.com/a/[{oci-first-no-rt}] account with administrator privileges.
 
-. Download an archive file from an Oracle resource. The archive file includes files for creating cluster resources and custom manifests. The archive file also includes a script, and when you run the script, the script creates {oci} resources, such as DNS records, an instance, and so on. For more information, see link:https://docs.oracle.com/iaas/Content/openshift-on-oci/install-prereq.htm#install-configuration-files[Configuration Files (Oracle documentation)].
+. Configure the account by defining the link:https://docs.oracle.com/iaas/Content/openshift-on-oci/install-prereq.htm[Cloud Accounts and Resources (Oracle documentation)]. Ensure that you create the following resources:
+
+.. Create a child compartment for organizing, restricting access, and setting usage limits to {oci} resources. For the full procedure, see link:https://docs.oracle.com/en-us/iaas/Content/Identity/compartments/To_create_a_compartment.htm#To[Creating a Compartment (Oracle documentation)].
+
+.. Create a new object storage bucket into which you will upload the discovery ISO image. 
+For the full procedure, see link:https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/managingbuckets_topic-To_create_a_bucket.htm#top[Creating an Object Storage Bucket (Oracle documentation)].
+
+. Download the latest version of the `create-cluster-vX.X.X.zip` configuration file from the link:https://github.com/oracle-quickstart/oci-openshift[`oracle-quickstart/oci-openshift`] repository. This file
+provides the infrastructure for the cluster and contains configurations for the following: 
++
+--
+** *Terraform Stacks*: The Terraform stack code for provisioning {oci} resources to create and manage {product-title} clusters on {oci}.  
+
+** *Custom Manifests*: The manifest files needed for the installation of {product-title} clusters on {oci}.
+--
++
+[NOTE]
+====
+To make any changes to the manifests, you can clone the entire Oracle GitHub repository and access the `custom_manifests` and `terraform-stacks` directories directly.
+====
++
+For details, see link:https://docs.oracle.com/iaas/Content/openshift-on-oci/install-prereq.htm#install-configuration-files[Configuration Files (Oracle documentation)].

modules/creating-oci-resources-services.adoc

@@ -4,34 +4,87 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="installing-oci-about-assisted-installer_{context}"]
-= The {ai-full} and {oci} overview
+= About the {ai-full} and {oci} integration
 
 You can run cluster workloads on {oci-first} infrastructure that supports dedicated, hybrid, public, and multiple cloud environments. Both Red{nbsp}Hat and Oracle test, validate, and support running {oci} in an {product-title} cluster on {oci}.
 
-The {ai-full} supports the {oci} platform, and you can use the {ai-full} to access an intuitive interactive workflow for the purposes of automating cluster installation tasks on {oci}.
+This section explains how to use the {ai-full} to install an {product-title} cluster on the {oci} platform. The installation deploys cloud-native components such as {oci-ccm-full} and {oci-csi-full}, and integrates your cluster with {oci} API resources such as instance node, load balancer, and storage. 
 
-.Workflow for using the {ai-full} in a connected environment to install a cluster on {oci}
+The installation process uses the {product-title} discovery ISO image provided by Red Hat, together with the  scripts and manifests provided and maintained by {oci}.
 
-image::684_OpenShift_Installing_on_OCI_0724_assisted.png[Image of a high-level workflow for using the Assisted Installer in a connected environment to install a cluster on {oci}]
+[id="installing-oci-preinstallation-considerations_{context}"]
+== Preinstallation considerations
 
-{oci} provides services that can meet your needs for regulatory compliance, performance, and cost-effectiveness. You can access {oci} Resource Manager configurations to provision and configure {oci} resources.
+Before installing {product-title} on {oci-first-no-rt}, you must consider the following configuration choices.
 
-[IMPORTANT]
-====
-The steps for provisioning {oci} resources are provided as an example only. You can also choose to create the required resources through other methods; the scripts are just an example. Installing a cluster with infrastructure that you provide requires knowledge of the cloud provider and the installation process on {product-title}. You can access {oci} Resource Manager configurations to complete these steps, or use the configurations to model your own custom script.
-====
+.Deployment platforms
 
-Follow the steps in the _Installing a cluster on {oci-first-no-rt} by using the Assisted Installer_ document to understand how to use the {ai-full} to install a {product-title} cluster on {oci}. This document demonstrates the use of the {oci} Cloud Controller Manager (CCM) and Oracle’s Container Storage Interface (CSI) objects to link your {product-title} cluster with the {oci} API.
+The integration between {product-title} and {oci-first-no-rt} is certified on both virtual machines (VMs) and bare-metal (BM) machines. Bare-metal installations using iSCSI boot drives require a secondary vNIC that is automatically created in the Terraform stack provided by Oracle. 
+
+Before you create a virtual machine (VM) or bare-metal (BM) machine, you must identify the relevant {oci} shape. For details, see the following resource: 
+
+* link:https://catalog.redhat.com/cloud/detail/216977[Cloud instance types (Red{nbsp}Hat Ecosystem Catalog portal)].
+
+.VPU sizing recommendations
 
-[IMPORTANT]
-====
 To ensure the best performance conditions for your cluster workloads that operate on {oci}, ensure that volume performance units (VPUs) for your block volume are sized for your workloads. The following list provides guidance for selecting the VPUs needed for specific performance needs:
 
 * Test or proof of concept environment: 100 GB, and 20 to 30 VPUs.
 * Basic environment: 500 GB, and 60 VPUs.
 * Heavy production environment: More than 500 GB, and 100 or more VPUs.
 
-Consider reserving additional VPUs to provide sufficient capacity for updates and scaling activities. For more information about VPUs, see Volume Performance Units (Oracle documentation).
-====
+Consider reserving additional VPUs to provide sufficient capacity for updates and scaling activities. For more information about VPUs, see link:https://docs.oracle.com/en-us/iaas/Content/Block/Concepts/blockvolumeperformance.htm#vpus[Volume Performance Units (Oracle documentation)].
+
+.Instance sizing recommendations
+
+Find recommended values for compute instance CPU, memory, VPU, and volume size for {product-title} nodes. For details, see link:https://docs.oracle.com/en-us/iaas/Content/openshift-on-oci/installing-agent-about-instance-configurations.htm[Instance Sizing Recommendations for {product-title} on {oci} Nodes (Oracle documentation)].
+
+[id="installing-oci-workflow_{context}"]
+== Workflow
+
+////
+Diagram will be updated and replace steps in a future task:
+
+The procedure for using the {ai-full} in a connected environment to install a cluster on {oci} is illustrated in the diagram below. 
+
+image::684_OpenShift_Installing_on_OCI_0724_assisted.png[Image of a high-level workflow for using the Assisted Installer in a connected environment to install a cluster on {oci}]
+////
+
+The procedure for using the {ai-full} in a connected environment to install a cluster on {oci} is outlined below:
+
+. In the {oci} console, configure an {oci} account to host the cluster:
 
-If you are unfamiliar with the {product-title} {ai-full}, see "Assisted Installer for {product-title}".
+.. Create a new child compartment under an existing compartment.
+
+.. Create a new object storage bucket or use one provided by {oci}.
+
+.. Download the stack file template stored locally. 
+
+. In the {ai-full} console, set up a cluster:
+
+.. Enter the cluster configurations.
+
+.. Generate and download the discovery ISO image.
+
+. In the {oci} console, create the infrastructure:
+
+.. Upload the discovery ISO image to the {oci} bucket.
+
+.. Create a Pre-Authenticated Request (PAR) for the ISO image.
+
+.. Upload the stack file template, and use it to create and apply the stack.
+
+.. Copy the custom manifest YAML file from the stack.
+
+. In the {ai-full} console, complete the cluster installation:
+
+.. Set roles for the cluster nodes.
+
+.. Upload the manifests provided by Oracle.
+
+.. Install the cluster.
+
+[IMPORTANT]
+====
+The steps for provisioning {oci} resources are provided as an example only. You can also choose to create the required resources through other methods; the scripts are just an example. Installing a cluster with infrastructure that you provide requires knowledge of the cloud provider and the installation process on {product-title}. You can access {oci} configurations to complete these steps, or use the configurations to model your own custom script. 
+====