openshift-docs/modules/installation-user-infra-machines-pxe.adoc

// Module included in the following assemblies:
//
// * installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc
// * installing/installing_bare_metal/upi/installing-bare-metal.adoc
// * installing/installing_bare_metal/upi/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:
:only-pxe:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-ibm-power"]
:ibm-power:
:only-pxe:
endif::[]

:_mod-docs-content-type: PROCEDURE
[id="installation-user-infra-machines-pxe_{context}"]
ifndef::only-pxe[]
= Installing {op-system} by using PXE or iPXE booting
endif::only-pxe[]
ifdef::only-pxe[]
= Installing {op-system} by using PXE booting
endif::only-pxe[]

[role="_abstract"]
ifndef::only-pxe[]
You can use PXE or iPXE booting to install {op-system} on the machines.
endif::only-pxe[]
ifdef::only-pxe[]
You can use PXE booting to install {op-system} on the machines.
endif::only-pxe[]

.Prerequisites

* You have created the Ignition config files for your cluster.
* You have configured suitable network, DNS and load balancing infrastructure.
ifndef::only-pxe[]
* You have configured suitable PXE or iPXE infrastructure.
endif::only-pxe[]
ifdef::only-pxe[]
* You have configured suitable PXE infrastructure.
endif::only-pxe[]
* 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

. 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
----
+
* `<HTTP_server>`: 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.
+
.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...
----

. Although it is possible to obtain the {op-system} `kernel`, `initramfs` and `rootfs`
files 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} files are
from the output of `openshift-install` command:
+
[source,terminal]
----
$ openshift-install coreos print-stream-json | grep -Eo '"https.*(kernel-|initramfs.|rootfs.)\w+(\.img)?"'
----
+
.Example output
[source,terminal]
ifndef::openshift-origin[]
----
"<url>/art/storage/releases/rhcos-4.21-aarch64/<release>/aarch64/rhcos-<release>-live-kernel-aarch64"
"<url>/art/storage/releases/rhcos-4.21-aarch64/<release>/aarch64/rhcos-<release>-live-initramfs.aarch64.img"
"<url>/art/storage/releases/rhcos-4.21-aarch64/<release>/aarch64/rhcos-<release>-live-rootfs.aarch64.img"
"<url>/art/storage/releases/rhcos-4.21-ppc64le/49.84.202110081256-0/ppc64le/rhcos-<release>-live-kernel-ppc64le"
"<url>/art/storage/releases/rhcos-4.21-ppc64le/<release>/ppc64le/rhcos-<release>-live-initramfs.ppc64le.img"
"<url>/art/storage/releases/rhcos-4.21-ppc64le/<release>/ppc64le/rhcos-<release>-live-rootfs.ppc64le.img"
"<url>/art/storage/releases/rhcos-4.21-s390x/<release>/s390x/rhcos-<release>-live-kernel-s390x"
"<url>/art/storage/releases/rhcos-4.21-s390x/<release>/s390x/rhcos-<release>-live-initramfs.s390x.img"
"<url>/art/storage/releases/rhcos-4.21-s390x/<release>/s390x/rhcos-<release>-live-rootfs.s390x.img"
"<url>/art/storage/releases/rhcos-4.21/<release>/x86_64/rhcos-<release>-live-kernel-x86_64"
"<url>/art/storage/releases/rhcos-4.21/<release>/x86_64/rhcos-<release>-live-initramfs.x86_64.img"
"<url>/art/storage/releases/rhcos-4.21/<release>/x86_64/rhcos-<release>-live-rootfs.x86_64.img"
----
endif::openshift-origin[]
ifdef::openshift-origin[]
----
"<url>/prod/streams/stable/builds/<release>/x86_64/fedora-coreos-<release>-live-kernel-x86_64"
"<url>/prod/streams/stable/builds/<release>/x86_64/fedora-coreos-<release>-live-initramfs.x86_64.img"
"<url>/prod/streams/stable/builds/<release>/x86_64/fedora-coreos-<release>-live-rootfs.x86_64.img"
----
endif::openshift-origin[]
+
[IMPORTANT]
====
The {op-system} artifacts 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. Only use
the appropriate `kernel`, `initramfs`, and `rootfs` artifacts described below
for this procedure.
{op-system} QCOW2 images are not supported for this installation type.
====
+
The file names contain the {product-title} version number. They resemble the following examples:
+
ifndef::openshift-origin[]
** `kernel`: `rhcos-<version>-live-kernel-<architecture>`
** `initramfs`: `rhcos-<version>-live-initramfs.<architecture>.img`
** `rootfs`: `rhcos-<version>-live-rootfs.<architecture>.img`
endif::openshift-origin[]
ifdef::openshift-origin[]
** `kernel`: `fedora-coreos-<version>-live-kernel-<architecture>`
** `initramfs`: `fedora-coreos-<version>-live-initramfs.<architecture>.img`
** `rootfs`: `fedora-coreos-<version>-live-rootfs.<architecture>.img`
endif::openshift-origin[]

. Upload the `rootfs`, `kernel`, and `initramfs` files
to your HTTP server.
+
[IMPORTANT]
====
If you plan to add more compute machines to your cluster after you finish
installation, do not delete these files.
====

. Configure the network boot infrastructure so that the machines boot from their
local disks after {op-system} is installed on them.

ifndef::only-pxe[]
. Configure PXE or iPXE installation for the {op-system} images and begin the installation.
endif::only-pxe[]
ifdef::only-pxe[]
. Configure PXE installation for the {op-system} images and begin the installation.
endif::only-pxe[]
+
ifndef::only-pxe[]
. Modify one of the following example menu entries for your environment and verify that the image and Ignition files are properly accessible:
endif::only-pxe[]
ifdef::only-pxe[]
. Modify the following example menu entry for your environment and verify that the image and Ignition files are properly accessible:
endif::only-pxe[]
ifndef::only-pxe[]
** For PXE (`x86_64`):
endif::only-pxe[]
+
----
DEFAULT pxeboot
TIMEOUT 20
PROMPT 0
LABEL pxeboot
    KERNEL http://<HTTP_server>/rhcos-<version>-live-kernel-<architecture>
    APPEND initrd=http://<HTTP_server>/rhcos-<version>-live-initramfs.<architecture>.img coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/bootstrap.ign
----
+
where:
+
`kernel`:: Specify the location of the live `kernel` file that you uploaded to your HTTP server. The URL must be HTTP, TFTP, or FTP; HTTPS and NFS are not supported.
`initrd=main`:: If you use multiple NICs, specify a single interface in the `ip` option. For example, to use DHCP on a NIC that is named `eno1`, set `ip=eno1:dhcp`. Specify the locations of the {op-system} files that you uploaded to your HTTP server. The `initrd` parameter value is the location of the `initramfs` file, the `coreos.live.rootfs_url` parameter value is the location of the `rootfs` file, and the `coreos.inst.ignition_url` parameter value is the location of the bootstrap Ignition config file. You can also add more kernel arguments to the `APPEND` line to configure networking or other boot options.
+
[NOTE]
====
This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `APPEND` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?] and "Enabling the serial console for PXE and ISO installation" in the "Advanced {op-system} installation configuration" section.
====

ifndef::only-pxe[]
** For iPXE (`x86_64`
ifndef::openshift-origin[]
+ `aarch64`
endif::openshift-origin[]
):
+
----
kernel http://<HTTP_server>/rhcos-<version>-live-kernel-<architecture> initrd=main coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/bootstrap.ign
initrd --name main http://<HTTP_server>/rhcos-<version>-live-initramfs.<architecture>.img
boot
----
`kernel`:: Specify the locations of the {op-system} files that you uploaded to your HTTP server. The `kernel` parameter value is the location of the `kernel` file, the `initrd=main` argument is needed for booting on UEFI systems, the `coreos.live.rootfs_url` parameter value is the location of the `rootfs` file, and the `coreos.inst.ignition_url` parameter value is the location of the bootstrap Ignition config file. If you use multiple NICs, specify a single interface in the `ip` option.
For example, to use DHCP on a NIC that is named `eno1`, set `ip=eno1:dhcp`.
`initrd`:: Specify the location of the `initramfs` file that you uploaded to your HTTP server.
+
[NOTE]
====
This configuration does not enable serial console access on machines with a graphical console.  To configure a different console, add one or more `console=` arguments to the `kernel` line.  For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console.  For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?] and "Enabling the serial console for PXE and ISO installation" in the "Advanced {op-system} installation configuration" section.
====
+
ifndef::openshift-origin[]
[NOTE]
====
To network boot the CoreOS `kernel` on `aarch64` architecture, you need to use a version of iPXE build with the `IMAGE_GZIP` option enabled. See link:https://ipxe.org/buildcfg/image_gzip[`IMAGE_GZIP` option in iPXE].
====
endif::openshift-origin[]
endif::only-pxe[]
ifndef::only-pxe,openshift-origin[]
** For PXE (with UEFI and Grub as second stage) on `aarch64`:
+
----
menuentry 'Install CoreOS' {
    linux rhcos-<version>-live-kernel-<architecture>  coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/bootstrap.ign
    initrd rhcos-<version>-live-initramfs.<architecture>.img
}
----
+
where:
+
`coreos.live.rootfs_url`:: Specify the locations of the {op-system} files that you uploaded to your HTTP/TFTP server.
`kernel`:: The `kernel` parameter value is the location of the `kernel` file on your TFTP server. The `coreos.live.rootfs_url` parameter value is the location of the `rootfs` file, and the `coreos.inst.ignition_url` parameter value is the location of the bootstrap Ignition config file on your HTTP Server. If you use multiple NICs, specify a single interface in the `ip` option.
For example, to use DHCP on a NIC that is named `eno1`, set `ip=eno1:dhcp`.
`initrd rhcos`:: Specify the location of the `initramfs` file that you uploaded to your TFTP server.

endif::only-pxe,openshift-origin[]

. 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, the system reboots. During reboot, the system 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 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 the cluster.
====
+
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:
:!only-pxe:
endif::[]
ifeval::["{context}" == "installing-restricted-networks-ibm-power"]
:!ibm-power:
:!only-pxe:
endif::[]