Merge pull request #66519 from jldohmann/bgilbert-pr

explicitly document including kargs

Author: jldohmann

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

@@ -4,11 +4,17 @@
 // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
 // * installing_bare_metal/installing-bare-metal-network-customizations.adoc
 
+:_content-type: PROCEDURE
 [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.
 
+[NOTE]
+====
+Custom CA certificates affect how Ignition fetches remote resources but they do not affect the certificates installed onto the 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.
@@ -21,6 +27,7 @@ ifeval::["{boot-media}" == "ISO image"]
 $ 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:
 +
@@ -30,17 +37,14 @@ $ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
     --ignition-ca cert.pem \
     -o rhcos-<version>-custom-initramfs.x86_64.img
 ----
+
+. Use the customized `initramfs` file in your PXE configuration. Add the `ignition.firstboot` and `ignition.platform.id=metal` kernel arguments if they are not already present.
 endif::[]
-+
+
 [IMPORTANT]
 ====
 The `coreos.inst.ignition_url` kernel parameter does not work with the `--ignition-ca` flag.
 You must use the `--dest-ignition` flag to create a customized image for each cluster.
 ====
-+
-[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 {boot-media}.
+
+Applying your custom CA certificate affects every subsequent boot of {op-system}.

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

@@ -4,6 +4,7 @@
 // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
 // * installing_bare_metal/installing-bare-metal-network-customizations.adoc
 
+:_content-type: PROCEDURE
 [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.
@@ -101,6 +102,8 @@ $ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
     --network-keyfile bond0-proxy-em2.nmconnection \
     -o rhcos-<version>-custom-initramfs.x86_64.img
 ----
+
+. Use the customized `initramfs` file in your PXE configuration. Add the `ignition.firstboot` and `ignition.platform.id=metal` kernel arguments if they are not already present.
 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-serial-console.adoc

@@ -59,13 +59,14 @@ $ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
   --dest-console tty0 \//<2>
   --dest-console ttyS0,<options> \//<3>
   --dest-device /dev/disk/by-id/scsi-<serial_number> \//<4>
-  -o rhcos-<version>-custom-initramfs.x86_64.img
+  -o rhcos-<version>-custom-initramfs.x86_64.img <5>
 ----
 +
 <1> The location of the Ignition config to install.
 <2> The desired secondary console. In this case, the graphical console. Omitting this option will disable the graphical console.
 <3> The desired primary console. In this case, the serial console. The `options` field defines the baud rate and other settings. A common value for this field is `115200n8`. If no options are provided, the default kernel value of `9600n8` is used. For more information on the format of this option, see the link:https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html[Linux kernel serial console] documentation.
 <4> The specified disk to install to. If you omit this option, the {boot-media} automatically runs the installer which will fail unless you also specify the `coreos.inst.install_dev` kernel argument.
+<5> Use the customized `initramfs` file in your PXE configuration. Add the `ignition.firstboot` and `ignition.platform.id=metal` kernel arguments if they are not already present.
 +
 Your customizations are applied and affect every subsequent boot of the {boot-media}.
 endif::[]

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

@@ -4,6 +4,7 @@
 // * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc
 // * installing_bare_metal/installing-bare-metal-network-customizations.adoc
 
+:_content-type: PROCEDURE
 [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
@@ -30,6 +31,17 @@ $ coreos-installer iso customize rhcos-<version>-live.x86_64.iso \
     --dest-ignition bootstrap.ign \ <1>
     --dest-device /dev/disk/by-id/scsi-<serial_number> <2>
 ----
+<1> The Ignition config file that is generated from the `openshift-installer` installation program.
+<2> When you specify this option, the {boot-media} automatically runs an installation. Otherwise, the image remains configured for installation, but does not install automatically unless you specify the `coreos.inst.install_dev` kernel argument.
+
+. Optional: To remove the {boot-media} 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 {boot-media} or use it in its pristine state.
 endif::[]
 
 ifeval::["{boot-media}" == "PXE environment"]
@@ -40,21 +52,11 @@ ifeval::["{boot-media}" == "PXE environment"]
 $ coreos-installer pxe customize rhcos-<version>-live-initramfs.x86_64.img \
     --dest-ignition bootstrap.ign \ <1>
     --dest-device /dev/disk/by-id/scsi-<serial_number> \ <2>
-    -o rhcos-<version>-custom-initramfs.x86_64.img
+    -o rhcos-<version>-custom-initramfs.x86_64.img <3>
 ----
-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.
+<3> Use the customized `initramfs` file in your PXE configuration. Add the `ignition.firstboot` and `ignition.platform.id=metal` kernel arguments if they are not already present.
 endif::[]
+
+Applying your customizations affects every subsequent boot of {op-system}.