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

// Module included in the following assemblies:
//
// * installing/installing_oci/installing-oci-agent-based-installer.adoc
// * installing/installing_oci/installing-pca-agent-based-installer.adoc

ifeval::["{context}" == "installing-pca-agent-based-installer"]
:pca:
endif::[]


ifeval::["{context}" == "installing-c3-agent-based-installer"]
:c3:
endif::[]

:_mod-docs-content-type: PROCEDURE

ifdef::c3[]
[id="creating-config-files-cluster-install-c3_{context}"]
= Creating configuration files for installing a cluster on {oci-edge-no-rt}

You must 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 has 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.
endif::c3[]

ifdef::pca[]
[id="creating-config-files-cluster-install-pca_{context}"]
= Creating configuration files for installing a cluster on {oci-pca-short}

You must 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 has 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.
endif::pca[]

ifndef::pca,c3[]
[id="creating-config-files-cluster-install-oci_{context}"]
= Creating configuration files for installing a cluster on {oci-distributed-no-rt}

You must 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 has 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.

endif::pca,c3[]

[NOTE]
====
You can also use the Agent-based Installer to generate or accept Zero Touch Provisioning (ZTP) custom resources.
====

.Prerequisites
* You reviewed details about the {product-title} installation and update processes.
* You read the documentation on selecting a cluster installation method and preparing the method for users.
* You have read the "Preparing to install with the Agent-based Installer" documentation.
* You downloaded the Agent-Based Installer and the command-line interface (CLI) from the link:https://console.redhat.com/openshift/install/metal/agent-based[{hybrid-console}].
* If you are installing in a disconnected environment, you have prepared a mirror registry in your environment and mirrored release images to the registry.
+
[IMPORTANT]
====
Check that your `openshift-install` binary version relates to your local image container registry and not a shared registry, such as {quay}, by running the following command:

[source,terminal]
----
$ ./openshift-install version
----

.Example output for a shared registry binary
[source,terminal,subs="quotes"]
----
./openshift-install 4.21.0
built from commit ae7977b7d1ca908674a0d45c5c243c766fa4b2ca
release image registry.ci.openshift.org/origin/release:4.21ocp-release@sha256:0da6316466d60a3a4535d5fed3589feb0391989982fba59d47d4c729912d6363
release architecture amd64
----
====
* You have logged in to the {product-title} with administrator privileges.

.Procedure

. Create an installation directory to store configuration files in by running the following command:
+
[source,terminal]
----
$ mkdir ~/<directory_name>
----

. Configure the `install-config.yaml` configuration file to meet the needs of your organization and save the file in the directory you created.
+
.`install-config.yaml` file that sets 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 virtual cloud network (VCN) that the CIDR allocates to resources and components that operate on your network.
<3> Depending on your infrastructure, you can select either `arm64` 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 {hybrid-console}.

. Create a directory on your local system named `openshift`. This must be a subdirectory of the installation directory.
+
[IMPORTANT]
====
Do not move the `install-config.yaml` or `agent-config.yaml` configuration files to the `openshift` directory.
====

ifndef::c3,pca[]
. If you used a stack to provision OCI infrastructure resources: Copy and paste the `dynamic_custom_manifest` output of the OCI stack into a file titled `manifest.yaml` and save the file in the `openshift` directory.

. If you did not use a stack to provision OCI infrastructure resources: Download and prepare custom manifests to create an Agent ISO image:


.. Go to link:https://docs.oracle.com/iaas/Content/openshift-on-oci/install-prereq.htm#install-configuration-files[Configuration Files] (Oracle documentation) and follow the link to the custom manifests directory on GitHub.

.. Copy the contents of the `condensed-manifest.yml` file and save it locally to a file in the `openshift` directory.

.. In the `condensed-manifest.yml` file, update the sections marked with `TODO` to specify the compartment {ocid-first}, VCN {ocid}, subnet {ocid} from the load balancer, and the security lists {ocid}.
endif::c3,pca[]

ifdef::c3[]
. Configure the Oracle custom manifest files.

.. Go to "Prepare the OpenShift Master Images" in link:https://www.oracle.com/a/otn/docs/compute_cloud_at_customer_agent_based_installation.pdf?source=:em:nl:mt::::PCATP[OpenShift Cluster Setup with
Agent Based Installer on Compute
Cloud@Customer] (Oracle documentation).

.. Copy and paste the `oci-ccm.yml`, `oci-csi.yml`, and `machineconfig-ccm.yml` files into your `openshift` directory.

.. Edit the `oci-ccm.yml` and `oci-csi.yml` files to specify the compartment {ocid-first}, VCN {ocid}, subnet {ocid} from the load balancer, the security lists {ocid}, and the `c3-cert.pem` section.
endif::c3[]

ifdef::pca[]
. Configure the Oracle custom manifest files.

.. Go to "Prepare the OpenShift Master Images" in link:https://www.oracle.com/a/otn/docs/private_cloud_appliance_agent_based_installation.pdf?source=:em:nl:mt::::PCATP[OpenShift Cluster Setup with
Agent Based Installer on Private Cloud Appliance] (Oracle documentation).

.. Copy and paste the `oci-ccm.yml`, `oci-csi.yml`, and `machineconfig-ccm.yml` files into your `openshift` directory.

.. Edit the `oci-ccm.yml` and `oci-csi.yml` files to specify the compartment {ocid-first}, VCN {ocid}, subnet {ocid} from the load balancer, the security lists {ocid}, and the `c3-cert.pem` section.
endif::pca[]

. Configure the `agent-config.yaml` configuration file to meet your organization's requirements.
+
.Sample `agent-config.yaml` file for an IPv4 network.
[source,yaml]
----
apiVersion: v1beta1
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 namespace of your cluster on {product-title}.
<3> If you use 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 the `rendezvousIP` parameter.
<4> The URL of the server where you want to upload the rootfs image. This parameter is required only for disconnected environments.

. Generate a minimal ISO image, which excludes the rootfs image, by entering the following command in your installation directory:
+
[source,terminal]
----
$ ./openshift-install agent create image --log-level debug
----
+
The 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 later step, is required for booting, recovering, and repairing your operating system.
====

. Disconnected environments only: Upload the rootfs image to a web server.

..  Go to the `./<installation_directory>/boot-artifacts` directory that was generated when you created the minimal ISO image.

.. Use your preferred web server, such as any Hypertext Transfer Protocol daemon (`httpd`), to upload the rootfs image to the location specified in the `bootArtifactsBaseURL` parameter of the `agent-config.yaml` file.
+
For example, if the `bootArtifactsBaseURL` parameter states `\http://192.168.122.20`, you would upload the generated rootfs image to this location so that the Agent-based installer can access the image from `\http://192.168.122.20/agent.x86_64-rootfs.img`. After the Agent-based 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.
====
+
[IMPORTANT]
====
Consider that the full ISO image, which is in excess of `1` GB, includes the rootfs image. The image is larger than the minimal ISO Image, which is typically less than `150` MB.
====

ifeval::["{context}" == "installing-c3-agent-based-installer"]
:!c3:
endif::[]

ifeval::["{context}" == "installing-pca-agent-based-installer"]
:!pca:
endif::[]