mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 21:46:22 +01:00
OSDOCS-3143: add coreos-installer iso customize feature
This commit is contained in:
Jesse Dohmann
@@ -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]
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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,72 +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.
|
||||
|
||||
.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 bootstrap.ign mybootstrap.ign
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
Files bootstrap.ign and mybootstrap.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.
|
||||
|
||||
@@ -232,7 +232,7 @@ endif::ibm-z-kvm[]
|
||||
|===
|
||||
ifndef::ibm-z,ibm-z-kvm,ibm-power[]
|
||||
[id="installation-user-infra-machines-coreos-installer-options_{context}"]
|
||||
== `coreos-installer` options for ISO installations
|
||||
== `coreos-installer` options for ISO and PXE installations
|
||||
|
||||
You can install {op-system} by running `coreos-installer install <options> <device>` at the command prompt, after booting into the {op-system} live environment from an ISO image.
|
||||
|
||||
@@ -308,36 +308,72 @@ a|Do not clear partition table on error.
|
||||
a|`-h`, `--help`
|
||||
a|Print help information.
|
||||
|
||||
2+|*coreos-install install subcommand argument*
|
||||
2+|*coreos-installer install subcommand argument*
|
||||
|
||||
|*_Argument_* |*_Description_*
|
||||
|
||||
a|`<device>`
|
||||
a|The destination device.
|
||||
|
||||
2+|*coreos-installer ISO Ignition subcommands*
|
||||
2+|*coreos-installer ISO subcommands*
|
||||
|
||||
|*_Subcommand_* |*_Description_*
|
||||
|
||||
a|`$ coreos-installer iso ignition embed <options> --ignition-file <file_path> <ISO_image>`
|
||||
a|Embed an Ignition config in an ISO image.
|
||||
a|`$ coreos-installer iso customize <options> <ISO_image>`
|
||||
a|Customize a {op-system} live ISO image.
|
||||
|
||||
a|`coreos-installer iso ignition show <options> <ISO_image>`
|
||||
|Show the embedded Ignition config from an ISO image.
|
||||
a|`coreos-installer iso reset <options> <ISO_image>`
|
||||
|Restore a {op-system} live ISO image to default settings.
|
||||
|
||||
a|`coreos-installer iso ignition remove <options> <ISO_image>`
|
||||
a|Remove the embedded Ignition config from an ISO image.
|
||||
|
||||
2+|*coreos-installer ISO Ignition subcommand options*
|
||||
2+|*coreos-installer ISO customize subcommand options*
|
||||
|
||||
|*_Option_* |*_Description_*
|
||||
|
||||
a|`--dest-ignition <path>`
|
||||
a|Merge the specified Ignition config into a new configuration fragment for the destination system.
|
||||
|
||||
a|`--dest-device <path>`
|
||||
a|Install and overwrite the specified destination device.
|
||||
|
||||
a|`--dest-karg-append <arg>`
|
||||
a|Add a kernel argument to each boot of the destination system.
|
||||
|
||||
a|`--dest-karg-delete <arg>`
|
||||
a|Delete a kernel argument from each boot of the destination system.
|
||||
|
||||
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 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.
|
||||
|
||||
a|`--live-karg-delete <arg>`
|
||||
a|Delete a kernel argument from each boot of the live environment.
|
||||
|
||||
a|`--live-karg-replace <k=o=n>`
|
||||
a|Replace a kernel argument in each boot of the live environment, in the form `key=old=new`.
|
||||
|
||||
a|`-f`, `--force`
|
||||
a|Overwrite an existing Ignition config.
|
||||
|
||||
a|`-i`, `--ignition-file <path>`
|
||||
a|The Ignition config to be used. Default is `stdin`.
|
||||
|
||||
a|`-o`, `--output <path>`
|
||||
a|Write the ISO to a new output file.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user