Merge pull request #69901 from dfitzmau/OSDOCS-8210

stevsmit · web-flow · commit 82e86a3b3e05 · 2024-02-16T09:04:36.000-05:00
OSDOCS-8210: Created an OCI doc book for the AI install route
diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc
@@ -254,6 +254,8 @@ endif::[]
 //Oracle
 :oci-first: Oracle(R) Cloud Infrastructure (OCI)
 :oci: OCI
+:ocid-first: Oracle(R) Cloud Identifier (OCID)
+:ocid: OCID
 :ocvs-first: Oracle(R) Cloud VMware Solution (OCVS)
 :ocvs: OCVS
 // Cluster Observability Operator
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -475,6 +475,12 @@ Topics:
     File: uninstalling-openstack-user
   - Name: Installation configuration parameters for OpenStack
     File: installation-config-parameters-openstack
+- Name: Installing on OCI
+  Dir: installing_oci
+  Distros: openshift-origin,openshift-enterprise
+  Topics:
+  - Name: Using the Assisted Installer to install a cluster on OCI
+    File: installing-oci-assisted-installer
 - Name: Installing on vSphere
   Dir: installing_vsphere
   Distros: openshift-origin,openshift-enterprise
diff --git a/images/ingress_load_balancer_warning_message.png b/images/ingress_load_balancer_warning_message.png
diff --git a/installing/installing_oci/_attributes b/installing/installing_oci/_attributes
@@ -0,0 +1 @@
+../../_attributes/
diff --git a/installing/installing_oci/images b/installing/installing_oci/images
@@ -0,0 +1 @@
+../../images
diff --git a/installing/installing_oci/installing-oci-assisted-installer.adoc b/installing/installing_oci/installing-oci-assisted-installer.adoc
@@ -0,0 +1,55 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="installing-oci-assisted-installer"]
+= Using the Assisted Installer to install a cluster on OCI
+include::_attributes/common-attributes.adoc[]
+:context: installing-oci-assisted-installer
+
+toc::[]
+
+From {product-title} {product-version} and later versions, you can use the Assisted Installer to install a cluster on {oci-first} by using infrastructure that you provide.
+
+// The Assisted Installer and OCI overview
+include::modules/installing-oci-about-assisted-installer.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/assisted_installer_for_openshift_container_platform/2024[Assisted Installer for {product-title}]
+* 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]
+ 
+
+// Creating OCI resources
+include::modules/creating-oci-resources-services.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+See the following Oracle web-based documents:
+
+* link:https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/managingcompartments.htm[Managing compartments]
+* link:https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/objectstorageoverview.htm[Overview of Object Storage]
+
+// Using the Assisted Installer to generate an OCI-compatible Agent ISO image
+include::modules/using-assisted-installer-oci-agent-iso.adoc[leveloffset=+1]
+
+// Downloading manifest files and deployment resources
+include::modules/downloading-manifest-files-resources-oci.adoc[leveloffset=+1]
+
+// Completing the remaining Assisted Installer steps
+include::modules/complete-assisted-installer-oci.adoc[leveloffset=+1]
+
+// Verifying a successful cluster installation on OCI
+include::modules/verifying-cluster-install-ai-oci.adoc[leveloffset=+1]
+
+// Troubleshooting installation of a cluster on OCI
+include::modules/installing-troubleshooting-assisted-installer-oci.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* 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 Assisted Installer]
+* link:https://access.redhat.com/documentation/en-us/assisted_installer_for_openshift_container_platform/2022/html-single/assisted_installer_for_openshift_container_platform/index[Assisted Installer for {product-title}]
+//* link:https://access.redhat.com/node/7038262[Using the Agent-based Installer to install a cluster on OCI]
+* link:https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Concepts/resourcemanager.htm#ways[Ways to access Resource Manager]
+* link:https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Tasks/create-stack.htm#top[Creating a stack] in the Oracle documentation.
diff --git a/installing/installing_oci/modules b/installing/installing_oci/modules
@@ -0,0 +1 @@
+../../modules/
diff --git a/installing/installing_oci/snippets b/installing/installing_oci/snippets
@@ -0,0 +1 @@
+../../snippets/
diff --git a/modules/complete-assisted-installer-oci.adoc b/modules/complete-assisted-installer-oci.adoc
@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: PROCEDURE
+[id="complete-assisted-installer-oci_{context}"]
+= Completing the remaining Assisted Installer 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 Assisted Installer before you can create an instance {oci}.
+
+.Prerequisites
+
+* You created a resource stack on {oci}, and the stack includes the custom manifest configuration files and {oci} Resource Manager configuration resources.
+
+.Procedure
+
+. From the link:https://console.redhat.com/[Red Hat Hybrid Cloud Console] web console, go to the **Host discovery** step. Under the **Role** column, assign a node role, `Control plane node` or `Worker`, for each targeted hostname.
++
+[IMPORTANT]
+====
+Before, you can continue to the next steps, wait for each node to reach the `Ready` status.
+====
+
+. Accept the default settings for the **Storage** and **Networking** steps. Click the **Next** button to go to the **Custom manifests** step. 
+
+. Select the value `manifests` in the **Folder** field and enter a value in the **File name** field, such as `oci-ccm.yml`. From the **Content** section, click **Browse** and select the CCM manifest from your drive located in `custom_ manifest/manifests/oci-ccm.yml`. 
+
+. Expand the next **Custom manifest** section and repeat the same steps for the following manifests:
+    - CSI driver manifest: `custom_ manifest/manifests/oci-csi.yml`
+    - CCM machine configuration: `custom_ manifest/openshift/machineconfig-ccm.yml`
+    - CSI driver machine configuration: `custom_ manifest/openshift/machineconfig-csi.yml`
+
+. Complete the **Review and create** step to create your {product-title} cluster on {oci}. Click the **Install cluster** button to complete the cluster installation. 
diff --git a/modules/creating-oci-resources-services.adoc b/modules/creating-oci-resources-services.adoc
@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-oci-resources-services_{context}"]
+= Creating OCI resources and services
+
+Create {oci-first} resources and services so that you can establish infrastructure with governance standards that meets your organization's requirements.
+
+By creating a compartment, you can better organize, restrict access, and set usage limits to {oci} resources. Additionally, by creating an object storage bucket, you can safely and securely store the ISO image. You can access the image at a later stage for the purposes of booting the instances, so that you can then create your cluster.
+
+.Prerequisites
+
+* You configured an {oci} account to host the cluster. See link:https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/csgsg/create-users-and-assign-roles.html#GUID-1041AC78-9E43-42CF-B5A5-73F8B8FEB39A[Create Users and Assign Roles] in the Oracle documentation.
+
+.Procedure
+
+. Log in to your link:https://cloud.oracle.com/a/[Oracle Cloud Infrastructure] account with administrator privileges.
+
+. Create a child compartment. See link:https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/process-automation/oci-process-automation/create-compartment.html[Create a compartment] in the Oracle documentation.
++
+[NOTE]
+====
+When creating the child compartment, specify the default parent compartment or any other parent compartment from the list.
+====
+
+. Record the name and the link:https://docs.oracle.com/en-us/iaas/Content/libraries/glossary/ocid.htm[{ocid-first}] of the compartment
+
+. Create a bucket resource for your child compartment. Ensure that you specify your child compartment in the **Create in compartment** field for the bucket resource. 
+
+. Go to **Object Storage & Archive Storage > Buckets** and create a bucket, where **Bucket name** refers to your cluster's name.
diff --git a/modules/downloading-manifest-files-resources-oci.adoc b/modules/downloading-manifest-files-resources-oci.adoc
@@ -0,0 +1,73 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: PROCEDURE
+[id="downloading-manifest-files-resources-oci_{context}"]
+= Downloading manifest files and deployment resources
+
+You must download the archive file that includes files for creating cluster resources and custom manifests. After you extract the contents of the archive file, you must upload the extracted files to an {oci-first} stack. The archive file contains a script that when run creates OCI resources, such as DNS records, an instance, and so on.
+
+A stack is an {oci} feature where you can automate the provisioning of all necessary {oci} infrastructure resources, such as the custom image, that are required for installing an {product-title} cluster on {oci}.
+
+The script uses the {oci-first} Compute Service to create a virtual machine (VM) instance on {oci}. This instance can then automatically attach to a virtual network interface controller (vNIC) in the virtual cloud network (VNC) subnet. On specifying the IP address of your {product-title} cluster in the custom manifest template files, the {oci} instance can communicate with your cluster over the VNC.
+
+.Prerequisites
+
+* You uploaded a generated Agent ISO image to {oci}. See the "Using the Assisted Installer to generate an OCI-compatible Agent ISO image" section.
+* You have permissions to access the `oracle-quickstart / oci-openshift` GitHub repository.
+* You logged in to your Oracle Cloud Infrastructure account with administrator privileges.
+
+.Procedure
+
+. From the link:https://github.com/oracle-quickstart/oci-openshift[`oracle-quickstart / oci-openshift`] GitHub web page, click the **<> Code** button and then click **Download ZIP**.  The following list details these resources:
++
+** link:https://github.com/oracle-quickstart/oci-openshift/tree/main/custom_manifests[CCM and CSI custom manifests].
+** link:https://github.com/oracle-quickstart/oci-openshift/blob/main/README.md[Download the {oci} Resource Manager configuration to provision resources for deploying Openshift on {oci}].
++
+[NOTE]
+====
+Consider using the example configurations in link:https://github.com/oracle-quickstart/oci-openshift/tree/main/custom_manifests/manifests[manifests] GitHub page as a guide for configuring a cloud infrastructure to meet your organization's needs.
+====
+
+. Create a stack by completing the link:https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Tasks/create-stack-compartment.htm[Creating a Stack from an Existing Compartment] procedure in the Oracle documentation. Ensure that you also complete the following subtasks:
++
+.. Upload the archive file, `.zip`, that you downloaded previously from the `oracle-quickstart / oci-openshift` repository. This file contains a script and after you upload the script to OCI, the script creates OCI resources within your child compartment.
+.. From the **Stack information** section, specify a name for your stack.
+.. From the **Configure variables** section, complete the following fields. Ensure you replace the examples with your actual values:
+... **cluster_name:**  `ocicluster`.
+... **compartment_ocid:** Specify the {ocid} from the parent compartment. For example, `ocid1.compartment.oc1..aaaaaaaa6r2iu3qndqgz5ogqkgnh2u2ajy5iou5ugkjr2ksmkrtdqrvxsvyq`.
+... **home_region:**  `us-sanjose-1`
+... **zone_dns:**  `openshift-demo.devcluster.openshift.com`.
+... **enable_private_dns:** Set the DNS zone to public or private. Specifying a value of `true`, creates a private DNS zone; specifying a value of `false` creates a public DNS zone. For a private DNS zone, you must configure your local `/etc/hosts` file to reach the cluster.
+... **openshift_image_source_url:** Specify the URL that you copied from a previous step of the quick-start procedure.
+
+. Click the **Apply** button to start an apply job. Check the **Logs** section to confirm that your stack was successfully created. 
+
+. Copy the `oci_ccm_config` cloud configuration from the **Outputs** section of the log. 
+
+. Extract the archive file that you downloaded in a previous step from the link:https://github.com/oracle-quickstart/oci-openshift[`oracle-quickstart / oci-openshift`] repository. A new directory displays on your file explorer. Open the directory in your preferred code editor.
+
+. Open the custom manifest template, `oci-ccm.yml`, and replace the cloud configuration section of the template file with the configuration that you previously copied from the **Logs** section on {oci}. Perform the same steps to update the configuration of the CSI driver in the `oci-csi.yml` file.
++
+The following example replaced the `region:` to `rateLimitBucketWrite` parameters of the `oci-csi.yml` file with the configuration from the `oci_ccm_config` cloud configuration on {oci}: 
++
+[source,yaml]
+----
+# …
+config.yaml: |
+   auth: 
+     region: <region_name>
+     useInstancePrincipals: true
+     compartment: <compartment_ocid>
+   vcn: <virtual_cloud_network_ocid>
+   loadBalancer:
+      subnet1: <subnet_ocid>
+      securityListManagementMode: Frontend
+   rateLimiter:
+     rateLimitQPSRead: 20.0
+     rateLimitBucketRead: 5
+     rateLimitQPSWrite: 20.0
+     rateLimitBucketWrite: 5
+# …
+----
diff --git a/modules/installing-oci-about-assisted-installer.adoc b/modules/installing-oci-about-assisted-installer.adoc
@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: CONCEPT
+[id="installing-oci-about-assisted-installer_{context}"]
+= The Assisted Installer and OCI overview
+
+You can run cluster workloads on {oci-first} infrastructure that supports dedicated, hybrid, public, and multiple cloud environments. Both Red Hat and Oracle test, validate, and support running {oci} in an {product-title} cluster on {oci}.
+
+The Assisted Installer supports the {oci} platform, and you can use the Assisted Installer to access an intuitive interactive workflow for the purposes of automating cluster installation tasks on {oci}.
+
+:FeatureName: Using the Assisted Installer to install an {product-title} cluster on OCI
+include::snippets/technology-preview.adoc[]
+
+{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.
+
+[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.
+====
+
+Follow the steps in this document to understand how to use the Assisted Installer to install a {product-title} cluster on {oci}. The document demonstrates the use of the {oci} Manager (CCM) and Oracle’s Container Storage Interface (CSI) objects to link your {product-title} cluster with the {oci} API.
+
+[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 in the Oracle documentation.
+====
+
+If you are unfamiliar with the {product-title} Assisted Installer, see "Using the Assisted Installer" in _Additional Resources_.
diff --git a/modules/installing-troubleshooting-assisted-installer-oci.adoc b/modules/installing-troubleshooting-assisted-installer-oci.adoc
@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: PROCEDURE
+[id="installing-troubleshooting-assisted-installer-oci_{context}"]
+= Troubleshooting installation of a cluster on OCI
+
+If you experience issues with using the Assisted Installer to install an {product-title} cluster on {oci-first}, read the following sections to troubleshoot common problems.
+
+[discrete]
+== The Ingress Load Balancer in OCI is not at a healthy status
+
+This issue is classed as a `Warning` because by using the Resource Manager to create a stack, you created a pool of compute nodes, 3 by default, that are automatically added as backend listeners for the Ingress Load Balancer. By default, the {product-title} deploys 2 router pods, which are based on the default values from the {product-title} manifest files. The `Warning` is expected because a mismatch exists with the number of router pods available, two, to run on the three compute nodes. 
+
+.Example of a `Warning` message that is under the Backend set information tab on {oci}: 
+image::ingress_load_balancer_warning_message.png[Example of an warning message that is under the Backend set information tab on OCI]
+
+You do not need to modify the Ingress Load Balancer configuration. Instead, you can point the Ingress Load Balancer to specific compute nodes that operate in your cluster on {product-title}. To do this, you will need to use placement mechanisms, such as annotations, on {product-title} to ensure router pods only run on the compute nodes that you originally configured on the Ingress Load Balancer as backend listeners. 
+
+[discrete]
+== OCI create stack operation fails with an Error: 400-InvalidParameter message
+
+On attempting to create a stack on {oci}, you identified that the **Logs** section of the job outputs an error message. For example:
+
+[source,terminal]
+----
+Error: 400-InvalidParameter, DNS Label oci-demo does not follow Oracle requirements
+Suggestion: Please update the parameter(s) in the Terraform config as per error message DNS Label oci-demo does not follow Oracle requirements
+Documentation: https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/core_vcn
+----
+
+Go to the https://console.redhat.com/openshift/assisted-installer/clusters/~new[**Install OpenShift with the Assisted Installer**] page on the Hybrid Cloud Console, and check the **Cluster name** field on the  **Cluster Details** step. Remove any special characters, such as a hyphen (`-`),  from the name, because these special characters are not compatible with the {oci} naming conventions.  For example, change `oci-demo` to `ocidemo`. 
diff --git a/modules/using-assisted-installer-oci-agent-iso.adoc b/modules/using-assisted-installer-oci-agent-iso.adoc
diff --git a/modules/verifying-cluster-install-ai-oci.adoc b/modules/verifying-cluster-install-ai-oci.adoc
