Merge pull request #40954 from jldohmann/OSDOCS-3143

OSDOCS-3143: Add coreos-installer iso customize feature

Author: mburke5678

installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc

@@ -111,6 +111,14 @@ include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2]
 
 include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
 
+include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso-ca-certs.adoc[leveloffset=+5]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso-network-config.adoc[leveloffset=+5]
+
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 
 include::modules/rhcos-enabling-multipath.adoc[leveloffset=+2]

installing/installing_bare_metal/installing-bare-metal.adoc

@@ -124,6 +124,14 @@ include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2]
 
 include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
 
+include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso-ca-certs.adoc[leveloffset=+5]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso-network-config.adoc[leveloffset=+5]
+
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 
 include::modules/rhcos-enabling-multipath.adoc[leveloffset=+2]

installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc

@@ -131,6 +131,14 @@ include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2]
 
 include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2]
 
+include::modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso-ca-certs.adoc[leveloffset=+5]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-iso-network-config.adoc[leveloffset=+5]
+
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 
 include::modules/rhcos-enabling-multipath.adoc[leveloffset=+2]

modules/installation-special-config-storage.adoc

@@ -155,11 +155,11 @@ When the `Do you wish to trust these keys? [ynYN]` prompt displays, type `Y`.
 {op-system-base} 8 provides Clevis version 15, which uses the SHA-1 hash algorithm to generate thumbprints. Some other distributions provide Clevis version 17 or later, which use the SHA-256 hash algorithm for thumbprints. You must use a Clevis version that uses SHA-1 to create the thumbprint, to prevent Clevis binding issues when you install {op-system-first} on your {product-title} cluster nodes.
 ====
 
-.. If the nodes are configured with static IP addressing, use the `coreos-installer` `--append-karg` option when installing {op-system} nodes to set the IP address of the installed system. Append the `ip=` and other arguments needed for your network.
+.. If the nodes are configured with static IP addressing, run `coreos-installer iso customize --dest-karg-append` or use the `coreos-installer` `--append-karg` option when installing {op-system} nodes to set the IP address of the installed system. Append the `ip=` and other arguments needed for your network.
 +
 [IMPORTANT]
 ====
-Some methods for configuring static IPs do not affect the initramfs after the first boot and will not work with Tang encryption. These include the `coreos-installer` `--copy-network` option, as well as adding `ip=` arguments to the kernel command line of the live ISO or PXE image during installation. Incorrect static IP configuration causes the second boot of the node to fail.
+Some methods for configuring static IPs do not affect the initramfs after the first boot and will not work with Tang encryption. These include the `coreos-installer` `--copy-network` option, the `coreos-installer iso customize` `--network-keyfile` option, and the `coreos-installer pxe customize` `--network-keyfile` option, as well as adding `ip=` arguments to the kernel command line of the live ISO or PXE image during installation. Incorrect static IP configuration causes the second boot of the node to fail.
 ====
 
 . On your installation node, change to the directory that contains the installation program and generate the Kubernetes manifests for the cluster:

modules/installation-user-infra-machines-advanced-customizing-iso-or-pxe.adoc

@@ -0,0 +1,17 @@
+// Module included in the following assemblies
+//
+// * installing/installing_bare_metal/installing-bare-metal.adoc
+// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
+// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc
+
+[id="installation-user-infra-machines-advanced-customizing-iso-or-pxe_{context}"]
+= Customizing a live {op-system} ISO or PXE install
+You can use the live ISO image or PXE environment to install {op-system} by injecting an Ignition config file directly into the image. This creates a customized image that you can use to provision your system.
+
+For an ISO image, the mechanism to do this is the `coreos-installer iso customize` subcommand, which modifies the `.iso` file with your configuration. Similarly, the mechanism for a PXE environment is the `coreos-installer pxe customize` subcommand, which creates a new `initramfs` file that includes your customizations.
+
+The `customize` subcommand is a general purpose tool that can embed other types of customizations as well. The following tasks are examples of some of the more common customizations:
+
+* Inject custom CA certificates for when corporate security policy requires their use.
+* Configure network settings without the need for kernel arguments.
+* Embed arbitrary pre-install and post-install scripts or binaries.

modules/installation-user-infra-machines-advanced-customizing-live-iso-ca-certs.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies
+//
+// * installing/installing_bare_metal/installing-bare-metal.adoc
+// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
+// * installing_bare_metal/installing-bare-metal-network-customizations.adoc
+
+[id="installation-user-infra-machines-advanced-customizing-live-iso-ca-certs_{context}"]
+= Modifying a live install image to use a custom certificate authority
+
+You can provide certificate authority (CA) certificates to Ignition with the `--ignition-ca` flag of the `customize` subcommand. You can use the CA certificates during both the installation boot and when provisioning the installed system.
+
+.Procedure
+
+. Download the `coreos-installer` binary from the link:https://mirror.openshift.com/pub/openshift-v4/clients/coreos-installer/latest/[`coreos-installer` image mirror] page.
+
+. Retrieve the {op-system} ISO image from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and run the following command to customize the ISO image for use with a custom CA:
++
+[source,terminal]
+----
+$ coreos-installer iso customize rhcos-<version>-live.x86_64.iso --ignition-ca cert.pem
+----
++
+[NOTE]
+====
+Custom CA certificates affect how Ignition fetches remote resources but they do not affect the certificates installed onto the system.
+====
++
+Your CA certificate is applied and affects every subsequent boot of the ISO image.

modules/installation-user-infra-machines-advanced-customizing-live-iso-network-config.adoc

@@ -0,0 +1,86 @@
+// Module included in the following assemblies
+//
+// * installing/installing_bare_metal/installing-bare-metal.adoc
+// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
+// * installing_bare_metal/installing-bare-metal-network-customizations.adoc
+
+[id="installation-user-infra-machines-advanced-customizing-live-iso_network_keyfile_{context}"]
+= Modifying a live install image with customized network settings
+You can embed a NetworkManager keyfile into the live ISO image and pass it through to the installed system with the `--network-keyfile` flag of the `customize` subcommand.
+
+.Procedure
+
+. Download the `coreos-installer` binary from the link:https://mirror.openshift.com/pub/openshift-v4/clients/coreos-installer/latest/[`coreos-installer` image mirror] page.
+
+. Create a connection profile for a bonded interface. For example, create the `bond0.nmconnection` file in your local directory with the following content:
++
+[source,ini]
+----
+[connection]
+id=bond0
+type=bond
+interface-name=bond0
+multi-connect=1
+permissions=
+
+[ethernet]
+mac-address-blacklist=
+
+[bond]
+miimon=100
+mode=active-backup
+
+[ipv4]
+method=auto
+
+[ipv6]
+method=auto
+
+[proxy]
+----
++
+. Create a connection profile for a secondary interface to add to the bond. For example, create the `bond0-proxy-em1.nmconnection` file in your local directory with the following content:
++
+[source,ini]
+----
+[connection]
+id=em1
+type=ethernet
+interface-name=em1
+master=bond0
+multi-connect=1
+permissions=
+slave-type=bond
+
+[ethernet]
+mac-address-blacklist=
+----
++
+. Create a connection profile for a secondary interface to add to the bond. For example, create the `bond0-proxy-em2.nmconnection` file in your local directory with the following content:
++
+[source,ini]
+----
+[connection]
+id=em2
+type=ethernet
+interface-name=em2
+master=bond0
+multi-connect=1
+permissions=
+slave-type=bond
+
+[ethernet]
+mac-address-blacklist=
+----
++
+. Retrieve the {op-system} ISO image from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and run the following command to customize the ISO image with your configured networking:
++
+[source,terminal]
+----
+$ coreos-installer iso customize rhcos-<version>-live.x86_64.iso \
+--network-keyfile bond0.nmconnection \
+--network-keyfile bond0-proxy-em1.nmconnection \
+--network-keyfile bond0-proxy-em2.nmconnection
+----
++
+Network settings are applied to the live system and are carried over to the destination system.

modules/installation-user-infra-machines-advanced-customizing-live-iso.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies
+//
+// * installing/installing_bare_metal/installing-bare-metal.adoc
+// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
+// * installing_bare_metal/installing-bare-metal-network-customizations.adoc
+
+[id="installation-user-infra-machines-advanced-customizing-live-iso_{context}"]
+= Customizing a live {op-system} ISO image
+You can customize a live {op-system} ISO image directly with the `coreos-installer iso customize` subcommand. When you boot the ISO image, the customizations are applied automatically.
+
+You can use this feature to configure the ISO image to automatically install {op-system}.
+
+.Procedure
+
+. Download the `coreos-installer` binary from the link:https://mirror.openshift.com/pub/openshift-v4/clients/coreos-installer/latest/[`coreos-installer` image mirror] page.
+
+. Retrieve the {op-system} ISO image from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and the Ignition config file, then run the following command to inject the Ignition config directly into the ISO image:
++
+[source,terminal]
+----
+$ coreos-installer iso customize rhcos-<version>-live.x86_64.iso \
+    --dest-ignition bootstrap.ign \ <1>
+    --dest-device /dev/sda <2>
+----
+<1> The Ignition config file that is generated from `openshift-installer`.
+<2> When this option is specified, the ISO image automatically runs an install. Otherwise, the image remains configured for installing but will not do so automatically unless the `coreos.inst.install_dev` kernel argument is specified.
++
+Your customizations are applied and affect every subsequent boot of the ISO image.
+
+. To remove the ISO image customizations and return the image to its pristine state, run:
++
+[source,terminal]
+----
+$ coreos-installer iso reset rhcos-<version>-live.x86_64.iso
+----
++
+You can now re-customize the live ISO image or use it in its pristine state.

modules/installation-user-infra-machines-advanced.adoc

@@ -16,7 +16,7 @@ techniques that include:
 
 * Passing kernel arguments to the live installer
 * Running `coreos-installer` manually from the live system
-* Embedding Ignition configs in an ISO
+* Customizing a live ISO or PXE boot image
 
 The advanced configuration topics for manual {op-system-first}
 installations detailed in this section relate to disk partitioning, networking, and using Ignition configs in different ways.
@@ -272,77 +272,9 @@ command line with the `--ignition-url=` option. In both cases, only HTTP and HTT
 protocols are supported.
 +
 
-* **Live install Ignition config**: This type must be created manually and should be avoided if possible, as it is not supported by Red Hat. With this method, the Ignition config passes to the live install medium, runs immediately upon booting, and performs setup tasks before and/or after the {op-system} system installs to disk. This method should only be used for performing tasks that must be done once and not applied again later, such as with advanced partitioning that cannot be done using a machine config.
+* **Live install Ignition config**: This type can be created by using the `coreos-installer` `customize` subcommand and its various options. With this method, the Ignition config passes to the live install medium, runs immediately upon booting, and performs setup tasks before or after the {op-system} system installs to disk. This method should only be used for performing tasks that must be done once and not applied again later, such as with advanced partitioning that cannot be done using a machine config.
 +
 For PXE or ISO boots, you can create the Ignition config
 and `APPEND` the `ignition.config.url=` option to identify the location of
 the Ignition config. You also need to append `ignition.firstboot ignition.platform.id=metal`
 or the `ignition.config.url` option will be ignored.
-
-[id="installation-user-infra-machines-advanced_embed_ignition_{context}"]
-=== Embedding a live install Ignition config in the {op-system} ISO
-
-You can embed a live install Ignition config directly in an {op-system} ISO image. When
-the ISO image is booted, the embedded config will be applied automatically.
-
-[IMPORTANT]
-====
-This type of configuration must be created manually and should be avoided if possible, as it is not supported by Red Hat.
-====
-
-.Procedure
-
-. Download the `coreos-installer` binary from the following image mirror page: https://mirror.openshift.com/pub/openshift-v4/clients/coreos-installer/latest/.
-
-. Retrieve the {op-system} ISO image and the Ignition config file, and copy them into an accessible directory, such as `/mnt`:
-+
-[source,terminal]
-----
-# cp rhcos-<version>-live.<architecture>.iso live.ign /mnt/
-# chmod 644 /mnt/rhcos-<version>-live.<architecture>.iso
-----
-
-. Run the following command to embed the Ignition config into the ISO:
-+
-[source,terminal]
-----
-# ./coreos-installer iso ignition embed -i /mnt/live.ign \
-     /mnt/rhcos-<version>-live.<architecture>.iso
-----
-+
-You can now use that ISO to install {op-system} using the specified live install
-Ignition config.
-+
-[IMPORTANT]
-====
-Using `coreos-installer iso ignition embed` to embed a file generated by `openshift-installer`, such as `bootstrap.ign`, `master.ign` and `worker.ign`, is unsupported and not recommended.
-====
-+
-. To show the contents of the embedded Ignition config and direct it into a file, run:
-+
-[source,terminal]
-----
-# ./coreos-installer iso ignition show /mnt/rhcos-<version>-live.<architecture>.iso > mylive.ign
-----
-+
-[source,terminal]
-----
-# diff -s live.ign mylive.ign
-----
-+
-.Example output
-[source,terminal]
-----
-Files live.ign and mylive.ign are identical
-----
-
-. To remove the Ignition config and return the ISO to its pristine state so
-you can reuse it, run:
-+
-[source,terminal]
-----
-# ./coreos-installer iso ignition remove /mnt/rhcos-<version>-live.<architecture>.iso
-----
-+
-You can now embed another Ignition config into the ISO or use the ISO in its
-pristine state.