openshift-docs/modules/rhcos-enabling-multipath.adoc

// Module included in the following assemblies:
//
// * installing/installing_bare_metal/upi/installing-bare-metal.adoc
// * installing/installing_bare_metal/upi/installing-bare-metal-network-customizations.adoc
// * installing/installing_bare_metal/upi/installing-restricted-networks-bare-metal.adoc

ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
:restricted:
endif::[]

:_mod-docs-content-type: PROCEDURE
[id="rhcos-enabling-multipath_{context}"]
= Enabling multipathing with kernel arguments on {op-system}

[role="_abstract"]
To achieve higher host availability and stronger resilience against hardware failure, enable multipathing on the primary disk. This configuration uses kernel arguments on {op-system} to ensure continuous storage access if path failure occurs.

You can enable multipathing at installation time for nodes that were provisioned in {product-title} 4.8 or later. While postinstallation support is available by activating multipathing through the machine config, Red{nbsp}Hat recommends enabling multipathing during installation.

In setups where any I/O to non-optimized paths results in I/O system errors, you must enable multipathing at installation time.

[IMPORTANT]
====
On {ibm-z-name} and {ibm-linuxone-name}, you can enable multipathing only if you configured your cluster for it during installation. For more information, see "Installing {op-system} and starting the {product-title} bootstrap process" in _Installing a cluster with z/VM on {ibm-z-name} and {ibm-linuxone-name}_.
====

The following procedure enables multipath at installation time and appends kernel arguments to the `coreos-installer install` command so that the installed system itself will use multipath beginning from the first boot.

[NOTE]
====
{product-title} does not support enabling multipathing as a day-2 activity on nodes that have been upgraded from 4.6 or earlier.
====

.Prerequisites

* You have created the Ignition config files for your cluster.

* You have reviewed _Installing {op-system} and starting the {product-title} bootstrap process_.

.Procedure

. To enable multipath and start the `multipathd` daemon, run the following command on the installation host:
+
[source,terminal]
----
$ mpathconf --enable && systemctl start multipathd.service
----
+
.. Optional: If booting the PXE or ISO, you can instead enable multipath by adding `rd.multipath=default` from the kernel command line.

. Append the kernel arguments by invoking the `coreos-installer` program:
+
* If there is only one multipath device connected to the machine, the device should be available at path `/dev/mapper/mpatha`. For example:
+
ifndef::restricted[]
[source,terminal]
----
$ coreos-installer install /dev/mapper/mpatha \
--ignition-url=http://host/worker.ign \
--append-karg rd.multipath=default \
--append-karg root=/dev/disk/by-label/dm-mpath-root \
--append-karg rw
----
endif::[]
ifdef::restricted[]
[source,terminal]
----
$ coreos-installer install /dev/mapper/mpatha \
--ignition-url=http://host/worker.ign \
--append-karg rd.multipath=default \
--append-karg root=/dev/disk/by-label/dm-mpath-root \
--append-karg rw \
--offline
----
endif::[]
+
--
* `/dev/mapper/mpatha`: Indicates the path of the single multipathed device.
--
+
* If there are multiple multipath devices connected to the machine, instead of using `/dev/mapper/mpatha`, Red{nbsp}Hat recommends using the World Wide Name (WWN) symlink. The symlink is available in `/dev/disk/by-id`. For example:
+
ifndef::restricted[]
[source,terminal]
----
$ coreos-installer install /dev/disk/by-id/wwn-<wwn_ID> \
--ignition-url=http://host/worker.ign \
--append-karg rd.multipath=default \
--append-karg root=/dev/disk/by-label/dm-mpath-root \
--append-karg rw
----
endif::[]
ifdef::restricted[]
[source,terminal]
----
$ coreos-installer install /dev/disk/by-id/wwn-<wwn_ID> \
--ignition-url=http://host/worker.ign \
--append-karg rd.multipath=default \
--append-karg root=/dev/disk/by-label/dm-mpath-root \
--append-karg rw \
--offline
----
endif::[]
+
where:
+
* `<wwn_ID>`:: Indicates the WWN ID of the target multipathed device. For example, `0xx194e957fcedb4841`.
+
This symlink can also be used as the `coreos.inst.install_dev` kernel argument when using special `coreos.inst.*` arguments to direct the live installer. For more information, see "Installing {op-system} and starting the {product-title} bootstrap process".

. Reboot into the installed system.

. Check that the kernel arguments worked by going to one of the worker nodes and listing the kernel command-line arguments (in `/proc/cmdline` on the host):
+
[source,terminal]
----
$ oc debug node/ip-10-0-141-105.ec2.internal
----
+
.Example output
[source,terminal]
----
Starting pod/ip-10-0-141-105ec2internal-debug ...
To use host binaries, run `chroot /host`

sh-4.2# cat /host/proc/cmdline
...
rd.multipath=default root=/dev/disk/by-label/dm-mpath-root
...

sh-4.2# exit
----
+
You should see the added kernel arguments.

ifeval::["{context}" == "installing-restricted-networks-bare-metal"]
:!restricted:
endif::[]