OSDOCS-6888-new: Created the agent-based installer book for OCI

Author: dfitzmau

_attributes/common-attributes.adoc

@@ -254,6 +254,10 @@ endif::[]
 //Oracle
 :oci-first: Oracle(R) Cloud Infrastructure (OCI)
 :oci: OCI
+:oci-ccm-full: Oracle Cloud Controller Manager (CCM)
+:oci-ccm: Oracle CCM
+:oci-csi-full: Oracle Container Storage Interface (CSI)
+:oci-csi: Oracle CSI
 :ocid-first: Oracle(R) Cloud Identifier (OCID)
 :ocid: OCID
 :ocvs-first: Oracle(R) Cloud VMware Solution (OCVS)

_topic_maps/_topic_map.yml

@@ -481,6 +481,8 @@ Topics:
   Topics:
   - Name: Using the Assisted Installer to install a cluster on OCI
     File: installing-oci-assisted-installer
+  - Name: Using the Agent-based Installer to install a cluster on OCI
+    File: installing-oci-agent-based-installer
 - Name: Installing on vSphere
   Dir: installing_vsphere
   Distros: openshift-origin,openshift-enterprise

installing/installing_oci/installing-oci-agent-based-installer.adoc

@@ -0,0 +1,56 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="installing-oci-agent-based-installer"]
+= Installing a cluster OCI by using the Agent-based Installer 
+include::_attributes/common-attributes.adoc[]
+:context: installing-oci-agent-based-installer
+
+toc::[]
+
+In {product-title} {product-version}, you can use the Agent-based Installer to install a cluster on {oci-first}, so that you can run cluster workloads on infrastructure that supports dedicated, hybrid, public, and multiple cloud environments.
+
+// The Agent-based Installer and OCI overview
+include::modules/installing-oci-about-agent-based-installer.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../architecture/architecture-installation.html#installation-process_architecture-installation[Installation process]
+* xref:../../installing/installing_platform_agnostic/installing-platform-agnostic.html#cluster-entitlements_installing-platform-agnostic[Internet access for {product-title}]
+* xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.html#understanding-agent-install_preparing-to-install-with-agent-based-installer[Understanding the Agent-based Installer]
+* See link:https://docs.oracle.com/en-us/iaas/Content/Compute/Concepts/computeoverview.htm[Overview of the Compute Service] in the Oracle documentation.
+* See link:https://docs.oracle.com/en-us/iaas/Content/Block/Concepts/blockvolumeperformance.htm#vpus[Volume Performance Units] in the Oracle documentation.
+
+// Creating OCI infrastructure resources and services
+include::modules/creating-oci-infra-resources-services.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+See the following Oracle documentation resources: 
+
+* link:https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/managingcompartments.htm#ariaid-title5[Creating compartments] 
+* link:https://docs.oracle.com/en-us/iaas/Content/Network/Tasks/create_vcn.htm[Creating a VCN]
+* link:https://docs.oracle.com/en-us/iaas/Content/Network/Concepts/create-nsg.htm[Creating an NSG]
+* link:https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengdynamicgrouppolicyforselfmanagednodes.htm[Creating a dynamic group and a policy for self-managed nodes]
+* link:https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/managingpolicies.htm[Managing policies]
+* link:https://docs.oracle.com/en-us/iaas/Content/Balance/Tasks/managingloadbalancer_topic-Creating_Load_Balancers.htm[Creating a load balancer]
+* link:https://docs.oracle.com/en-us/iaas/Content/DNS/Tasks/record-add.htm[Adding a record to a DNS zone]
+
+// Creating configuration files for installing a cluster on OCI
+include::modules/creating-config-files-cluster-install-oci.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.html#installing-ocp-agent-ztp_installing-with-agent-based-installer[Optional: Using ZTP manifests]
+
+// Running your cluster on OCI
+include::modules/running-cluster-oci-agent-based.adoc[leveloffset=+1]
+
+// Verifying a succesful cluster installation on OCI
+include::modules/verifying-cluster-install-oci-agent-based.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.html#installing-ocp-agent-gather-log_installing-with-agent-based-installer[Gathering log data from a failed Agent-based installation]

modules/creating-config-files-cluster-install-oci.adoc

@@ -0,0 +1,138 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-agent-based-installer.adoc [Using the Agent-based Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-config-files-cluster-install-oci_{context}"]
+= Creating configuration files for installing a cluster on OCI
+
+You need to create the `install-config.yaml` and the `agent-config.yaml` configuration files so that you can use the Agent-based Installer to generate a bootable ISO image. The Agent-based installation comprises a bootable ISO that contains the Assisted discovery agent and the Assisted Service. Both of these components are required to perform the cluster installation, but the latter component runs on only one of the hosts.
+
+In a subsequent procedure, you can upload your generated Agent ISO image to Oracle’s default Object Storage bucket, which is the initial step for integrating your {product-title} cluster on {oci-first}.
+
+You can also use the Agent-based Installer to generate or accept Zero Touch Provisioning (ZTP) custom resources.
+
+.Prerequisites
+* You reviewed details about the xref:../../architecture/architecture-installation.html#installation-overview_architecture-installation[{product-title} installation and update processes].
+* You read the documentation on xref:../../installing/installing-preparing.html#installing-preparing-selecting-cluster-type[Selecting a cluster installation method and preparing it for users].
+* You have read the xref:../../installing/installing_with_agent_based_installer/preparing-to-install-with-agent-based-installer.html#about-the-agent-based-installer[Preparing to install with the Agent-based Installer] documentation.
+* You downloaded the xref:../../installing/installing_with_agent_based_installer/installing-with-agent-based-installer.html#installing-ocp-agent-retrieve_installing-with-agent-based-installer[Agent-Based Installer] and the command-line interface (CLI) from Red Hat’s Hybrid Cloud Console.
+* For a disconnected environment, you created a container image registry, such as Red Hat Quay. See xref:../../installing/disconnected_install/installing-mirroring-creating-registry.html#mirror-registry-introduction_installing-mirroring-creating-registry[Mirror registry for Red Hat OpenShift introduction].
+* You have logged into the {product-title} with administrator privileges. 
+
+.Procedure
+
+. Configure the `install-config.yaml` configuration file to meet the needs of your organization. 
++
+.Example `install-config.yaml` configuration file that demonstrates setting an external platform
++
+[source,yaml]
+----
+# install-config.yaml
+apiVersion: v1
+baseDomain: <base_domain> <1>
+networking:
+  clusterNetwork:
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  network type: OVNKubernetes
+  machineNetwork:
+  - cidr: <ip_address_from_cidr> <2>
+  serviceNetwork: 
+  - 172.30.0.0/16
+compute:
+  - architecture: amd64 <3>
+  hyperthreading: Enabled
+  name: worker
+  replicas: 0
+controlPlane:
+  architecture: amd64 <3>
+  hyperthreading: Enabled
+  name: master
+  replicas: 3
+platform:
+   external:
+    platformName: oci <4>
+    cloudControllerManager: External
+sshKey: <public_ssh_key> <5>
+pullSecret: '<pull_secret>' <6>
+# ...
+----
+<1> The base domain of your cloud provider. 
+<2> The IP address from the VCN that the CIDR allocates to resources and components that operate on your network.
+<3> Depending on your infrastructure, you can select either `x86_64`, or `amd64`.
+<4> Set `OCI` as the external platform, so that {product-title} can integrate with {oci}. 
+<5> Specify your SSH public key.
+<6> The pull secret that you need for authenticate purposes when downloading container images for {product-title} components and services, such as Quay.io. See link:https://console.redhat.com/openshift/install/pull-secret[Install {product-title} 4] from the Red Hat Hybrid Cloud Console. 
+
+. Create a directory on your local system named `openshift`. 
++
+[IMPORTANT]
+====
+Do not move the `install-config.yaml` and `agent-config.yaml` configuration files to the `openshift` directory.
+====
+
+. From the link:https://github.com/oracle-quickstart/oci-openshift[`oracle-quickstart / oci-openshift`] GitHub web page, select the **<> Code** button and click **Download ZIP**. Save the archive file to your `openshift` directory,  so that all the {oci-ccm-full} and {oci-csi-full} manifests exist in the same directory. The downloaded archive file includes files for creating cluster resources and custom manifests. 
+
+. Go to the link:https://github.com/oracle-quickstart/oci-openshift/tree/main/custom_manifests[custom_manifests] web page on GitHub to access the custom manifest files.
++
+The {oci-ccm} manifest are required for deploying the {oci-ccm} during cluster installation so that {product-title} can connect to the external {oci} platform. The {oci-csi} custom manifests are required for deploying the {oci-csi} driver during cluster installation so that {product-title} can claim required objects from {oci}.
++
+[IMPORTANT]
+====
+You must modify the secret `oci-cloud-controller-manager` defined in the link:https://github.com/oracle-quickstart/oci-openshift/blob/main/custom_manifests/manifests/oci-ccm.yml[`oci-ccm.yml`] configuration file to match your organization's region, compartment {ocid}, VCN {ocid}, and the subnet {ocid} from the load balancer.
+====
+
+. Use the Agent-based Installer to generate a minimal ISO image, which excludes the `rootfs` image, by entering the following command in your {product-title} CLI. You can use this image later in the process to boot all your cluster’s nodes. 
++
+[source,terminal]
+----
+$ ./openshift-install agent create image --log-level debug
+----
++
+The previous command also completes the following actions:
++
+* Creates a subdirectory, `./<installation_directory>/auth directory:`, and places `kubeadmin-password` and `kubeconfig` files in the subdirectory.  
+* Creates a `rendezvousIP` file based on the IP address that you specified in the `agent-config.yaml` configuration file. 
+* Optional: Any modifications you made to `agent-config.yaml` and `install-config.yaml` configuration files get imported to the Zero Touch Provisioning (ZTP) custom resources. 
++
+[IMPORTANT]
+====
+The Agent-based Installer uses {op-system-first}. The `rootfs` image, which is mentioned in a subsequent listed item,  is required for booting, recovering, and repairing your operating system. 
+====
+
+. Configure the `agent-config.yaml` configuration file to meet your organization’s requirements. 
++
+.Example `agent-config.yaml` configuration file that sets values for an IPv4 formatted network.
+[source,yaml]
+----
+apiVersion: v1alpha1
+metadata:
+  name: <cluster_name> <1>
+  namespace: <cluster_namespace> <2>
+rendezvousIP:<ip_address_from_CIDR> <3>
+bootArtifactsBaseURL:<server_URL> <4>
+# …
+----
+<1> The cluster name that you specified in your DNS record. 
+<2> The name of your cluster on {product-title}. 
+<3> If you are using IPv4 as the network IP address format, ensure that you set the `rendezvousIP` parameter to an IPv4 address that the VCN’s Classless Inter-Domain Routing (CIDR) method allocates on your network. Also ensure that at least one instance from the pool of instances that you booted with the ISO matches the IP address value you set for `rendezvousIP`.  
+<4> The URL of the server where you want to upload the `rootfs` image.
+
+. Apply one of the following two updates to your `agent-config.yaml` configuration file:
++
+* For a disconnected network:  After you run the command to generate a minimal ISO Image, the Agent-based installer saves the `rootfs` image into the `./<installation_directory>/boot-artifacts` directory on your local system. Upload `rootfs` to the location stated in the `bootArtifactsBaseURL` parameter in the `agent-config.yaml` configuration file. 
++
+For example, if the URL states \http://192.168.122.20, you would upload the generated `rootfs` image to this location, so that the installer can access the image from \http://192.168.122.20/agent.x86_64-rootfs.img. After the installer boots the minimal ISO for the external platform, the Agent-based Installer downloads the `rootfs` image from the \http://192.168.122.20/agent.x86_64-rootfs.img location into the system memory. 
++
+[NOTE]
+====
+The Agent-based Installer also adds the value of the `bootArtifactsBaseURL` to the minimal ISO Image’s configuration, so that when the Operator boots a cluster’s node, the Agent-based Installer  downloads the `rootfs` image into system memory.
+====
++
+* For a connected network: You do not need to specify the `bootArtifactsBaseURL` parameter in the `agent-config.yaml` configuration file, because the Agent-based Installer, by default, reads the a `rootfs` URL location from \https://rhcos.mirror.openshift.com. After the Agent-based Installer  boots the minimal ISO for the external platform, the Agent-based Installer then downloads the `rootfs` file into your system’s memory from the default {op-system} URL.
++
+[IMPORTANT]
+====
+Consider that the full ISO image, which is in excess of `1` GB, includes the `rootfs` image and the image is considerably larger than the minimal ISO Image, which is typical less than `150` MB.
+====

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

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_oci/installing-oci-agent-based-installer.adoc [Using the Agent-based Installer to install a cluster on OCI]
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-oci-infra-resources-services_{context}"]
+= Creating OCI infrastructure resources and services
+
+// Removed "or bare-metal shape" as BM route is dev preview. Feature support progression is dependent on OSDOCS-8631 progress.
+Before you install {product-title} on {oci-first}, you must create an {oci} environment on your virtual machine (VM) shape. By creating this environment, you can install {product-title} and deploy a cluster on infrastructure that supports a wide range of cloud options and strong security policies.
+
+.Prerequisites
+* You have prior knowledge of {oci} components. See link:https://docs.oracle.com/en-us/iaas/Content/GSG/Concepts/concepts.htm[Learn About Oracle Cloud Basics] in the Oracle documentation.  
+* Your organization signed up for an Oracle account and Identity Domain. This step is required so that you can access an administrator account, which is the initial cloud-identity and access management (IAM) user for your organization. See link:https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/overview.htm#ariaid-title4[The administrators group and policy] section in the Oracle documentation.
+* You have logged into your organization’s {oci} account with administrator privileges.
+
+.Procedure
+
+. Create a compartment and ensure you defined your {ocid-first} in the compartment. A compartment is a component where you can organize and isolate your cloud resources. After you create a compartment, Oracle automatically assigns an {ocid} to your organization’s account. An administrator can access all compartments tagged to your organization’s {oci} account.
+
+. Create a virtual cloud network (VCN). A compute instance, load balancer, and other resources need this network infrastructure to connect to each other over an internet connection. To establish an on-premise network you must manually create subnets, gateways, routing rules, and security policies. Ensure that you complete the following steps:
+.. In **Primary VNIC IP addresses > Primary network**, select a VCN, such as *oci-cluster-vcn*. 
+.. From the **Subnet** section, select your subnet, such as *ici-cluster-private-subnet*. 
+.. For public IPV4 subnets, ensure that you select the **Do not assign a public IPv4 address** checkbox.
+
+. Create a network security group (NSG) in your VCN. You can use the NSG to establish advanced security rules for your network. You must locate the NSG in your compartment, so that certain groups can access network resources. Ensure that you complete the following steps:
+.. Click **Show advanced options**. 
+.. Select the **Use network security groups** to control traffic checkbox.
+.. Set your NSG, such as *oci-cluster-controlplane-nsg*.
+
+. Create a dynamic group that hosts compute instances. After you create the dynamic group, you can then create a policy statement that defines rules for your cluster environment. This statement sets the precedent  for each compute instance to join your {product-title} cluster as a self-managed node. 
+
+. Create a policy statement. You must create a policy so that your administrator can grant access to your groups, users, or resources that operate in your network.
+
+. Create a load balancer, so that you can provide automated traffic distribution on your VCN.
+
+. Create three Domain Name System (DNS) records and then add the records to a DNS, so that Oracle’s edge-network can maintain your domain’s DNS queries.
++
+[IMPORTANT]
+====
+To ensure compatibility with {product-title}, set `A` as the record type for each DNS record and name records as follows:
+
+* `api.<cluster_name>.<base_domain>`, which targets the `apiVIP` parameter of the API load balancer.
+* `api-int.<cluster_name>.<base_domain>`, which targets the `apiVIP` parameter of the API load balancer.
+* `*.apps.<cluster_name>.<base_domain>`, which targets the `ingressVIP` parameter of the Ingress load balancer.
+
+The `api.+*+` and `api-int.+*+` DNS records relate to control plane machines, so you must ensure that all nodes in your installed {product-title} cluster can access these DNS records.
+====