// Module included in the following assemblies:
//
// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
// * installing/installing_bare_metal/installing-bare-metal.adoc
// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
// * installing/installing_ibm_power/installing-ibm-power.adoc
// * installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc
// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc

ifeval::["{context}" == "installing-ibm-power"]
:ibm-power:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-ibm-power"]
:ibm-power:
endif::[]

:_content-type: PROCEDURE
[id="installation-user-infra-machines-iso_{context}"]
= Installing {op-system} by using an ISO image

You can use an ISO image to install {op-system} on the machines.

.Prerequisites

* You have created the Ignition config files for your cluster.
* You have configured suitable network, DNS and load balancing infrastructure.
* You have an HTTP server that can be accessed from your computer, and from the machines that you create.
* You have reviewed the _Advanced {op-system} installation configuration_ section for different ways to configure features, such as networking and disk partitioning.

.Procedure

. Obtain the SHA512 digest for each of your Ignition config files. For example, you can use the following on a system running Linux to get the SHA512 digest for your `bootstrap.ign` Ignition config file:
+
[source,terminal]
----
$ sha512sum <installation_directory>/bootstrap.ign
----
+
The digests are provided to the `coreos-installer` in a later step to validate the authenticity of the Ignition config files on the cluster nodes.

. Upload the bootstrap, control plane, and compute node Ignition config files that the installation program created to your HTTP server. Note the URLs of these files.
+
[IMPORTANT]
====
You can add or change configuration settings in your Ignition configs before saving them to your HTTP server. If you plan to add more compute machines to your cluster after you finish installation, do not delete these files.
====

. From the installation host, validate that the Ignition config files are available on the URLs. The following example gets the Ignition config file for the bootstrap node:
+
[source,terminal]
----
$ curl -k http://<HTTP_server>/bootstrap.ign <1>
----
+
.Example output
[source,terminal]
----
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0{"ignition":{"version":"3.2.0"},"passwd":{"users":[{"name":"core","sshAuthorizedKeys":["ssh-rsa...
----
+
Replace `bootstrap.ign` with `master.ign` or `worker.ign` in the command to validate that the Ignition config files for the control plane and compute nodes are also available.
+
. Although it is possible to obtain the {op-system} images that are required for your preferred method of installing operating system instances from the
ifdef::openshift-enterprise[]
ifndef::ibm-power[]
link:https://mirror.openshift.com/pub/openshift-v4/x86_64/dependencies/rhcos/[{op-system} image mirror]
endif::ibm-power[]
endif::openshift-enterprise[]
ifdef::openshift-origin[]
link:https://getfedora.org/en/coreos/download?tab=metal_virtualized&stream=stable[{op-system}]
endif::openshift-origin[]
ifdef::ibm-power[]
link:https://mirror.openshift.com/pub/openshift-v4/ppc64le/dependencies/rhcos/[{op-system} image mirror]
endif::ibm-power[]
page, the recommended way to obtain the correct version of your {op-system} images are from the output of `openshift-install` command:
+
[source,terminal]
----
$ openshift-install coreos print-stream-json | grep '\.iso[^.]'
----
+
.Example output
[source,terminal]
ifndef::openshift-origin[]
----
"location": "<url>/art/storage/releases/rhcos-4.14-aarch64/<release>/aarch64/rhcos-<release>-live.aarch64.iso",
"location": "<url>/art/storage/releases/rhcos-4.14-ppc64le/<release>/ppc64le/rhcos-<release>-live.ppc64le.iso",
"location": "<url>/art/storage/releases/rhcos-4.14-s390x/<release>/s390x/rhcos-<release>-live.s390x.iso",
"location": "<url>/art/storage/releases/rhcos-4.14/<release>/x86_64/rhcos-<release>-live.x86_64.iso",
----
endif::openshift-origin[]
ifdef::openshift-origin[]
----
"location": "<url>/prod/streams/stable/builds/<release>/x86_64/fedora-coreos-<release>-live.x86_64.iso",
----
endif::openshift-origin[]
+
[IMPORTANT]
====
The {op-system} images might not change with every release of {product-title}. You must download images with the highest version that is less than or equal to the {product-title} version that you install. Use the image versions that match your {product-title} version if they are available. Use only ISO images for this procedure. {op-system} qcow2 images are not supported for this installation type.
====
+
ISO file names resemble the following example:
+
ifndef::openshift-origin[]
`rhcos-<version>-live.<architecture>.iso`
endif::openshift-origin[]
ifdef::openshift-origin[]
`fedora-coreos-<version>-live.<architecture>.iso`
endif::openshift-origin[]

. Use the ISO to start the {op-system} installation. Use one of the following installation options:
** Burn the ISO image to a disk and boot it directly.
** Use ISO redirection by using a lights-out management (LOM) interface.

. Boot the {op-system} ISO image without specifying any options or interrupting the live boot sequence. Wait for the installer to boot into a shell prompt in the {op-system} live environment.
+
[NOTE]
====
It is possible to interrupt the {op-system} installation boot process to add kernel arguments. However, for this ISO procedure you should use the `coreos-installer` command as outlined in the following steps, instead of adding kernel arguments.
====

. Run the `coreos-installer` command and specify the options that meet your installation requirements. At a minimum, you must specify the URL that points to the Ignition config file for the node type, and the device that you are installing to:
+
[source,terminal]
----
$ sudo coreos-installer install --ignition-url=http://<HTTP_server>/<node_type>.ign <device> --ignition-hash=sha512-<digest> <1><2>
----
<1> You must run the `coreos-installer` command by using `sudo`, because the `core` user does not have the required root privileges to perform the installation.
<2> The `--ignition-hash` option is required when the Ignition config file is obtained through an HTTP URL to validate the authenticity of the Ignition config file on the cluster node. `<digest>` is the Ignition config file SHA512 digest obtained in a preceding step.
+
[NOTE]
====
If you want to provide your Ignition config files through an HTTPS server that uses TLS, you can add the internal certificate authority (CA) to the system trust store before running `coreos-installer`.
====
+
The following example initializes a bootstrap node installation to the `/dev/sda` device. The Ignition config file for the bootstrap node is obtained from an HTTP web server with the IP address 192.168.1.2:
+
[source,terminal]
----
$ sudo coreos-installer install --ignition-url=http://192.168.1.2:80/installation_directory/bootstrap.ign /dev/sda --ignition-hash=sha512-a5a2d43879223273c9b60af66b44202a1d1248fc01cf156c46d4a79f552b6bad47bc8cc78ddf0116e80c59d2ea9e32ba53bc807afbca581aa059311def2c3e3b
----

. Monitor the progress of the {op-system} installation on the console of the machine.
+
[IMPORTANT]
====
Be sure that the installation is successful on each node before commencing with the {product-title} installation. Observing the installation process can also help to determine the cause of {op-system} installation issues that might arise.
====

. After {op-system} installs, you must reboot the system. During the system reboot, it applies the Ignition config file that you specified.

. Check the console output to verify that Ignition ran.
+
.Example command
[source,terminal]
----
Ignition: ran on 2022/03/14 14:48:33 UTC (this boot)
Ignition: user-provided config was applied
----

. Continue to create the other machines for your cluster.
+
[IMPORTANT]
====
You must create the bootstrap and control plane machines at this time. If the control plane machines are not made schedulable, also create at least two compute machines before you install {product-title}.
====
+
If the required network, DNS, and load balancer infrastructure are in place, the {product-title} bootstrap process begins automatically after the {op-system} nodes have rebooted.
+
[NOTE]
====
{op-system} nodes do not include a default password for the `core` user. You can access the nodes by running `ssh core@<node>.<cluster_name>.<base_domain>` as a user with access to the SSH private key that is paired to the public key that you specified in your `install_config.yaml` file. {product-title} 4 cluster nodes running {op-system} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes by using SSH is not recommended. However, when investigating installation issues, if the {product-title} API is not available, or the kubelet is not properly functioning on a target node, SSH access might be required for debugging or disaster recovery.
====

ifeval::["{context}" == "installing-ibm-power"]
:!ibm-power:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-ibm-power"]
:!ibm-power:
endif::[]
