Merge pull request #42037 from jldohmann/OSDOCS-3144

Add coreos-installer pxe customize feature

Author: mburke5678

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

@@ -120,11 +120,25 @@ 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]
+:boot-media: ISO image
+:boot: iso
+include::modules/installation-user-infra-machines-advanced-customizing-live.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-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-advanced-customizing-live-network-config.adoc[leveloffset=+5]
+:boot-media!:
+:boot!:
+
+:boot-media: PXE environment
+:boot: pxe
+include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
+:boot-media!:
+:boot!:
 
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 

installing/installing_bare_metal/installing-bare-metal.adoc

@@ -135,11 +135,25 @@ 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]
+:boot-media: ISO image
+:boot: iso
+include::modules/installation-user-infra-machines-advanced-customizing-live.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-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-advanced-customizing-live-network-config.adoc[leveloffset=+5]
+:boot-media!:
+:boot!:
+
+:boot-media: PXE environment
+:boot: pxe
+include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
+:boot-media!:
+:boot!:
 
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 

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

@@ -141,11 +141,25 @@ 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]
+:boot-media: ISO image
+:boot: iso
+include::modules/installation-user-infra-machines-advanced-customizing-live.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-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-advanced-customizing-live-network-config.adoc[leveloffset=+5]
+:boot-media!:
+:boot!:
+
+:boot-media: PXE environment
+:boot: pxe
+include::modules/installation-user-infra-machines-advanced-customizing-live.adoc[leveloffset=+4]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-ca-certs.adoc[leveloffset=+5]
+
+include::modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc[leveloffset=+5]
+:boot-media!:
+:boot!:
 
 include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3]
 

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

@@ -4,25 +4,37 @@
 // * 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
+[id="installation-user-infra-machines-advanced-customizing-live-{boot}-ca-certs_{context}"]
+= Modifying a live install {boot-media} 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.
 
+ifeval::["{boot-media}" == "ISO image"]
 . 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
 ----
+endif::[]
+ifeval::["{boot-media}" == "PXE environment"]
+. Retrieve the {op-system} `kernel`, `initramfs` and `rootfs` files from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and run the following command to create a new customized `initramfs` file for use with a custom CA:
++
+[source,terminal]
+----
+$ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
+    --ignition-ca cert.pem \
+    -o rhcos-<version>-custom-initramfs.x86_64.img
+----
+endif::[]
 +
 [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.
+Your CA certificate is applied and affects every subsequent boot of the {boot-media}.

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

@@ -4,9 +4,9 @@
 // * 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.
+[id="installation-user-infra-machines-advanced-customizing-live-{boot}_network_keyfile_{context}"]
+= Modifying a live install {boot-media} with customized network settings
+You can embed a NetworkManager keyfile into the live {boot-media} and pass it through to the installed system with the `--network-keyfile` flag of the `customize` subcommand.
 
 .Procedure
 
@@ -73,14 +73,29 @@ slave-type=bond
 mac-address-blacklist=
 ----
 +
+ifeval::["{boot-media}" == "ISO image"]
 . 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-keyfile bond0.nmconnection \
+    --network-keyfile bond0-proxy-em1.nmconnection \
+    --network-keyfile bond0-proxy-em2.nmconnection
 ----
+endif::[]
+
+ifeval::["{boot-media}" == "PXE environment"]
+. Retrieve the {op-system} `kernel`, `initramfs` and `rootfs` files from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and run the following command to create a new customized `initramfs` file that contains your configured networking:
++
+[source,terminal]
+----
+$ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
+    --network-keyfile bond0.nmconnection \
+    --network-keyfile bond0-proxy-em1.nmconnection \
+    --network-keyfile bond0-proxy-em2.nmconnection \
+    -o rhcos-<version>-custom-initramfs.x86_64.img
+----
+endif::[]
 +
 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-network-config.adoc renamed to modules/installation-user-infra-machines-advanced-customizing-live-network-config.adoc

@@ -0,0 +1,60 @@
+// 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-{boot}_{context}"]
+= Customizing a live {op-system} {boot-media}
+You can customize a live {op-system} {boot-media} directly with the
+ifeval::["{boot-media}" == "ISO image"]
+`coreos-installer iso customize`
+endif::[]
+ifeval::["{boot-media}" == "PXE environment"]
+`coreos-installer pxe customize`
+endif::[]
+subcommand. When you boot the {boot-media}, the customizations are applied automatically.
+
+You can use this feature to configure the {boot-media} 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.
+
+ifeval::["{boot-media}" == "ISO image"]
+. 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, and 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>
+----
+endif::[]
+
+ifeval::["{boot-media}" == "PXE environment"]
+. Retrieve the {op-system} `kernel`, `initramfs` and `rootfs` files from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page and the Ignition config file, and then run the following command to create a new `initramfs` file that contains the customizations from your Ignition config:
++
+[source,terminal]
+----
+$ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
+    --dest-ignition bootstrap.ign \ <1>
+    --dest-device /dev/sda \ <2>
+    -o rhcos-<version>-custom-initramfs.x86_64.img
+----
+endif::[]
+<1> The Ignition config file that is generated from `openshift-installer`.
+<2> When you specify this option, the {boot-media} automatically runs an install. Otherwise, the image remains configured for installing, but does not do so automatically unless you specify the `coreos.inst.install_dev` kernel argument.
++
+Your customizations are applied and affect every subsequent boot of the {boot-media}.
+
+ifeval::["{boot-media}" == "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.
+endif::[]

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

@@ -333,7 +333,7 @@ a|Remove the embedded Ignition config from an ISO image.
 |*_Option_* |*_Description_*
 
 a|`--dest-ignition <path>`
-a|Merge the specified Ignition config into a new configuration fragment for the destination system.
+a|Merge the specified Ignition config file into a new configuration fragment for the destination system.
 
 a|`--dest-device <path>`
 a|Install and overwrite the specified destination device.
@@ -360,7 +360,7 @@ a|`--installer-config <path>`
 a|Apply the specified installer configuration file.
 
 a|`--live-ignition <path>`
-a|Merge the specified Ignition config into a new configuration fragment for the live environment.
+a|Merge the specified Ignition config file into a new configuration fragment for the live environment.
 
 a|`--live-karg-append <arg>`
 a|Add a kernel argument to each boot of the live environment.
@@ -380,29 +380,58 @@ a|Write the ISO to a new output file.
 a|`-h`, `--help`
 a|Print help information.
 
-2+|*coreos-installer PXE Ignition subcommands*
+2+|*coreos-installer PXE subcommands*
 
 |*_Subcommand_* |*_Description_*
 
 2+|Note that not all of these options are accepted by all subcommands.
 
+a|`coreos-installer pxe customize <options> <path>`
+a|Customize a {op-system} live PXE boot config.
+
 a|`coreos-installer pxe ignition wrap <options>`
 a|Wrap an Ignition config in an image.
 
 a|`coreos-installer pxe ignition unwrap <options> <image_name>`
 a|Show the wrapped Ignition config in an image.
 
-2+|*coreos-installer PXE Ignition subcommand options*
+2+|*coreos-installer PXE customize subcommand options*
 
 |*_Option_* |*_Description_*
 
 2+|Note that not all of these options are accepted by all subcommands.
 
-a|`-i`, `--ignition-file <path>`
-a|The Ignition config to be used. Default is `stdin`.
+a|`--dest-ignition <path>`
+a|Merge the specified Ignition config file into a new configuration fragment for the destination system.
+
+a|`--dest-device <path>`
+a|Install and overwrite the specified destination device.
+
+a|`--network-keyfile <path>`
+a|Configure networking by using the specified NetworkManager keyfile for live and destination systems.
+
+a|`--ignition-ca <path>`
+a|Specify an additional TLS certificate authority to be trusted by Ignition.
+
+a|`--pre-install <path>`
+a|Run the specified script before installation.
+
+a|`post-install <path>`
+a|Run the specified script after installation.
+
+a|`--installer-config <path>`
+a|Apply the specified installer configuration file.
+
+a|`--live-ignition <path>`
+a|Merge the specified Ignition config file into a new configuration fragment for the live environment.
 
 a|`-o,` `--output <path>`
-a|Write the ISO to a new output file.
+a|Write the initramfs to a new output file.
+
+[NOTE]
+====
+This option is required for PXE environments.
+====
 
 a|`-h`, `--help`
 a|Print help information.