Skip to content

Commit 82e86a3

Browse files
stevsmitstevsmit
authored
Merge pull request #69901 from dfitzmau/OSDOCS-8210
OSDOCS-8210: Created an OCI doc book for the AI install route
2 parents 9047c34 + a2126bb commit 82e86a3

15 files changed

+348
-0
lines changed

‎_attributes/common-attributes.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,8 @@ endif::[]
254254
//Oracle
255255
:oci-first: Oracle(R) Cloud Infrastructure (OCI)
256256
:oci: OCI
257+
:ocid-first: Oracle(R) Cloud Identifier (OCID)
258+
:ocid: OCID
257259
:ocvs-first: Oracle(R) Cloud VMware Solution (OCVS)
258260
:ocvs: OCVS
259261
// Cluster Observability Operator

‎_topic_maps/_topic_map.yml

+6
Original file line numberDiff line numberDiff line change
@@ -475,6 +475,12 @@ Topics:
475475
File: uninstalling-openstack-user
476476
- Name: Installation configuration parameters for OpenStack
477477
File: installation-config-parameters-openstack
478+
- Name: Installing on OCI
479+
Dir: installing_oci
480+
Distros: openshift-origin,openshift-enterprise
481+
Topics:
482+
- Name: Using the Assisted Installer to install a cluster on OCI
483+
File: installing-oci-assisted-installer
478484
- Name: Installing on vSphere
479485
Dir: installing_vsphere
480486
Distros: openshift-origin,openshift-enterprise

‎images/ingress_load_balancer_warning_message.png

233 KB
Loading

‎installing/installing_oci/_attributes

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../_attributes/

‎installing/installing_oci/images

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../images

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

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="installing-oci-assisted-installer"]
3+
= Using the Assisted Installer to install a cluster on OCI
4+
include::_attributes/common-attributes.adoc[]
5+
:context: installing-oci-assisted-installer
6+
7+
toc::[]
8+
9+
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.
10+
11+
// The Assisted Installer and OCI overview
12+
include::modules/installing-oci-about-assisted-installer.adoc[leveloffset=+1]
13+
14+
[role="_additional-resources"]
15+
.Additional resources
16+
17+
* link:https://access.redhat.com/documentation/en-us/assisted_installer_for_openshift_container_platform/2024[Assisted Installer for {product-title}]
18+
* xref:../../installing/installing_platform_agnostic/installing-platform-agnostic.adoc#cluster-entitlements_installing-platform-agnostic[Internet access for {product-title}]
19+
* link:https://docs.oracle.com/en-us/iaas/Content/Block/Concepts/blockvolumeperformance.htm#vpus[Volume Performance Units]
20+
21+
22+
// Creating OCI resources
23+
include::modules/creating-oci-resources-services.adoc[leveloffset=+1]
24+
25+
[role="_additional-resources"]
26+
.Additional resources
27+
28+
See the following Oracle web-based documents:
29+
30+
* link:https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/managingcompartments.htm[Managing compartments]
31+
* link:https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/objectstorageoverview.htm[Overview of Object Storage]
32+
33+
// Using the Assisted Installer to generate an OCI-compatible Agent ISO image
34+
include::modules/using-assisted-installer-oci-agent-iso.adoc[leveloffset=+1]
35+
36+
// Downloading manifest files and deployment resources
37+
include::modules/downloading-manifest-files-resources-oci.adoc[leveloffset=+1]
38+
39+
// Completing the remaining Assisted Installer steps
40+
include::modules/complete-assisted-installer-oci.adoc[leveloffset=+1]
41+
42+
// Verifying a successful cluster installation on OCI
43+
include::modules/verifying-cluster-install-ai-oci.adoc[leveloffset=+1]
44+
45+
// Troubleshooting installation of a cluster on OCI
46+
include::modules/installing-troubleshooting-assisted-installer-oci.adoc[leveloffset=+1]
47+
48+
[role="_additional-resources"]
49+
.Additional resources
50+
51+
* 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]
52+
* 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}]
53+
//* link:https://access.redhat.com/node/7038262[Using the Agent-based Installer to install a cluster on OCI]
54+
* link:https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Concepts/resourcemanager.htm#ways[Ways to access Resource Manager]
55+
* link:https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Tasks/create-stack.htm#top[Creating a stack] in the Oracle documentation.

‎installing/installing_oci/modules

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../modules/

‎installing/installing_oci/snippets

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../snippets/

‎modules/complete-assisted-installer-oci.adoc

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="complete-assisted-installer-oci_{context}"]
7+
= Completing the remaining Assisted Installer steps
8+
9+
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}.
10+
11+
.Prerequisites
12+
13+
* You created a resource stack on {oci}, and the stack includes the custom manifest configuration files and {oci} Resource Manager configuration resources.
14+
15+
.Procedure
16+
17+
. 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.
18+
+
19+
[IMPORTANT]
20+
====
21+
Before, you can continue to the next steps, wait for each node to reach the `Ready` status.
22+
====
23+
24+
. Accept the default settings for the **Storage** and **Networking** steps. Click the **Next** button to go to the **Custom manifests** step.
25+
26+
. 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`.
27+
28+
. Expand the next **Custom manifest** section and repeat the same steps for the following manifests:
29+
- CSI driver manifest: `custom_ manifest/manifests/oci-csi.yml`
30+
- CCM machine configuration: `custom_ manifest/openshift/machineconfig-ccm.yml`
31+
- CSI driver machine configuration: `custom_ manifest/openshift/machineconfig-csi.yml`
32+
33+
. Complete the **Review and create** step to create your {product-title} cluster on {oci}. Click the **Install cluster** button to complete the cluster installation.

‎modules/creating-oci-resources-services.adoc

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="creating-oci-resources-services_{context}"]
7+
= Creating OCI resources and services
8+
9+
Create {oci-first} resources and services so that you can establish infrastructure with governance standards that meets your organization's requirements.
10+
11+
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.
12+
13+
.Prerequisites
14+
15+
* 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.
16+
17+
.Procedure
18+
19+
. Log in to your link:https://cloud.oracle.com/a/[Oracle Cloud Infrastructure] account with administrator privileges.
20+
21+
. 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.
22+
+
23+
[NOTE]
24+
====
25+
When creating the child compartment, specify the default parent compartment or any other parent compartment from the list.
26+
====
27+
28+
. Record the name and the link:https://docs.oracle.com/en-us/iaas/Content/libraries/glossary/ocid.htm[{ocid-first}] of the compartment
29+
30+
. 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.
31+
32+
. Go to **Object Storage & Archive Storage > Buckets** and create a bucket, where **Bucket name** refers to your cluster's name.

‎modules/downloading-manifest-files-resources-oci.adoc

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="downloading-manifest-files-resources-oci_{context}"]
7+
= Downloading manifest files and deployment resources
8+
9+
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.
10+
11+
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}.
12+
13+
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.
14+
15+
.Prerequisites
16+
17+
* You uploaded a generated Agent ISO image to {oci}. See the "Using the Assisted Installer to generate an OCI-compatible Agent ISO image" section.
18+
* You have permissions to access the `oracle-quickstart / oci-openshift` GitHub repository.
19+
* You logged in to your Oracle Cloud Infrastructure account with administrator privileges.
20+
21+
.Procedure
22+
23+
. 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:
24+
+
25+
** link:https://github.com/oracle-quickstart/oci-openshift/tree/main/custom_manifests[CCM and CSI custom manifests].
26+
** 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}].
27+
+
28+
[NOTE]
29+
====
30+
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.
31+
====
32+
33+
. 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:
34+
+
35+
.. 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.
36+
.. From the **Stack information** section, specify a name for your stack.
37+
.. From the **Configure variables** section, complete the following fields. Ensure you replace the examples with your actual values:
38+
... **cluster_name:** `ocicluster`.
39+
... **compartment_ocid:** Specify the {ocid} from the parent compartment. For example, `ocid1.compartment.oc1..aaaaaaaa6r2iu3qndqgz5ogqkgnh2u2ajy5iou5ugkjr2ksmkrtdqrvxsvyq`.
40+
... **home_region:** `us-sanjose-1`
41+
... **zone_dns:** `openshift-demo.devcluster.openshift.com`.
42+
... **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.
43+
... **openshift_image_source_url:** Specify the URL that you copied from a previous step of the quick-start procedure.
44+
45+
. Click the **Apply** button to start an apply job. Check the **Logs** section to confirm that your stack was successfully created.
46+
47+
. Copy the `oci_ccm_config` cloud configuration from the **Outputs** section of the log.
48+
49+
. 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.
50+
51+
. 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.
52+
+
53+
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}:
54+
+
55+
[source,yaml]
56+
----
57+
# …
58+
config.yaml: |
59+
auth:
60+
region: <region_name>
61+
useInstancePrincipals: true
62+
compartment: <compartment_ocid>
63+
vcn: <virtual_cloud_network_ocid>
64+
loadBalancer:
65+
subnet1: <subnet_ocid>
66+
securityListManagementMode: Frontend
67+
rateLimiter:
68+
rateLimitQPSRead: 20.0
69+
rateLimitBucketRead: 5
70+
rateLimitQPSWrite: 20.0
71+
rateLimitBucketWrite: 5
72+
# …
73+
----

‎modules/installing-oci-about-assisted-installer.adoc

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="installing-oci-about-assisted-installer_{context}"]
7+
= The Assisted Installer and OCI overview
8+
9+
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}.
10+
11+
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}.
12+
13+
:FeatureName: Using the Assisted Installer to install an {product-title} cluster on OCI
14+
include::snippets/technology-preview.adoc[]
15+
16+
{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.
17+
18+
[IMPORTANT]
19+
====
20+
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.
21+
====
22+
23+
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.
24+
25+
[IMPORTANT]
26+
====
27+
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:
28+
29+
* Test or proof of concept environment: 100 GB, and 20 to 30 VPUs.
30+
* Basic environment: 500 GB, and 60 VPUs.
31+
* Heavy production environment: More than 500 GB, and 100 or more VPUs.
32+
33+
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.
34+
====
35+
36+
If you are unfamiliar with the {product-title} Assisted Installer, see "Using the Assisted Installer" in _Additional Resources_.

‎modules/installing-troubleshooting-assisted-installer-oci.adoc

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * installing/installing_oci/installing-oci-assisted-installer.adoc [Using the Assisted Installer to install a cluster on OCI]
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="installing-troubleshooting-assisted-installer-oci_{context}"]
7+
= Troubleshooting installation of a cluster on OCI
8+
9+
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.
10+
11+
[discrete]
12+
== The Ingress Load Balancer in OCI is not at a healthy status
13+
14+
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.
15+
16+
.Example of a `Warning` message that is under the Backend set information tab on {oci}:
17+
image::ingress_load_balancer_warning_message.png[Example of an warning message that is under the Backend set information tab on OCI]
18+
19+
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.
20+
21+
[discrete]
22+
== OCI create stack operation fails with an Error: 400-InvalidParameter message
23+
24+
On attempting to create a stack on {oci}, you identified that the **Logs** section of the job outputs an error message. For example:
25+
26+
[source,terminal]
27+
----
28+
Error: 400-InvalidParameter, DNS Label oci-demo does not follow Oracle requirements
29+
Suggestion: Please update the parameter(s) in the Terraform config as per error message DNS Label oci-demo does not follow Oracle requirements
30+
Documentation: https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/core_vcn
31+
----
32+
33+
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`.

0 commit comments

Comments
 (0)