1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00

TELCODOCS-906: D/S Docs & RN: MGMT-7888 Support installation disk encryption - enhancement OCP updates

This commit is contained in:
Katie Tothill
2022-11-18 15:14:57 -05:00
committed by openshift-cherrypick-robot
parent 590232fa97
commit d2e8a424a3
2 changed files with 104 additions and 50 deletions

View File

@@ -11,37 +11,51 @@ During an {product-title} installation, you can enable boot disk encryption and
[id="installation-special-config-encrypt-disk_{context}"]
== About disk encryption
You can enable encryption for the boot disks on the control plane and compute nodes at installation time. {product-title} supports the Trusted Platform Module (TPM) v2 and Tang encryption modes.
You can enable encryption for the boot disks on the control plane and compute nodes at installation time.
{product-title} supports the Trusted Platform Module (TPM) v2 and Tang encryption modes.
* TPM v2: This is the preferred mode. TPM v2 stores passphrases in a secure cryptoprocessor contained within a server. You can use this mode to prevent the boot disk data on a cluster node from being decrypted if the disk is removed from the server.
* Tang: Tang and Clevis are server and client components that enable network-bound disk encryption (NBDE). You can bind the boot disk data on your cluster nodes to one or more Tang servers. This prevents the data from being decrypted unless the nodes are on a secure network where the Tang servers can be accessed. Clevis is an automated decryption framework that is used to implement the decryption on the client side.
TPM v2:: This is the preferred mode.
TPM v2 stores passphrases in a secure cryptoprocessor on the server.
You can use this mode to prevent decryption of the boot disk data on a cluster node if the disk is removed from the server.
Tang:: Tang and Clevis are server and client components that enable network-bound disk encryption (NBDE).
You can bind the boot disk data on your cluster nodes to one or more Tang servers.
This prevents decryption of the data unless the nodes are on a secure network where the Tang servers are accessible.
Clevis is an automated decryption framework used to implement decryption on the client side.
[IMPORTANT]
====
The use of the Tang encryption mode to encrypt your disks is only supported for bare metal and vSphere installations on user-provisioned infrastructure.
====
[NOTE]
====
On previous versions of {op-system-first}, disk encryption was configured by specifying `/etc/clevis.json` in the Ignition config. That file is not supported in clusters created with {product-title} 4.7 or above, and disk encryption should be configured by using the following procedure.
====
In earlier versions of {op-system-first}, disk encryption was configured by specifying `/etc/clevis.json` in the Ignition config.
That file is not supported in clusters created with {product-title} 4.7 or later.
Configure disk encryption by using the following procedure.
When the TPM v2 or Tang encryption modes are enabled, the {op-system} boot disks are encrypted using the LUKS2 format.
This feature:
* Is available for installer-provisioned infrastructure and user-provisioned infrastructure deployments
* Is available for installer-provisioned infrastructure, user-provisioned infrastructure, and Assisted Installer deployments
* For Assisted installer deployments:
- Each cluster can only have a single encryption method, Tang or TPM
- Encryption can be enabled on some or all nodes
- There is no Tang threshold; all servers must be valid and operational
- Encryption applies to the installation disks only, not to the workload disks
* Is supported on {op-system-first} systems only
* Sets up disk encryption during the manifest installation phase so all data written to disk, from first boot forward, is encrypted
* Sets up disk encryption during the manifest installation phase, encrypting all data written to disk, from first boot forward
* Requires no user intervention for providing passphrases
* Uses AES-256-XTS encryption, or AES-256-CBC if FIPS mode is enabled
[id="installation-special-config-encryption-threshold_{context}"]
=== Configuring an encryption threshold
In {product-title}, you can specify a requirement for more than one Tang server. You can also configure the TPM v2 and Tang encryption modes simultaneously, so that the boot disk data can be decrypted only if the TPM secure cryptoprocessor is present and the Tang servers can be accessed over a secure network.
In {product-title}, you can specify a requirement for more than one Tang server.
You can also configure the TPM v2 and Tang encryption modes simultaneously.
This enables boot disk data decryption only if the TPM secure cryptoprocessor is present and the Tang servers are accessible over a secure network.
You can use the `threshold` attribute in your Butane configuration to define the minimum number of TPM v2 and Tang encryption conditions that must be met for decryption to occur. The threshold is met when the stated value is reached through any combination of the declared conditions. For example, the `threshold` value of `2` in the following configuration can be reached by accessing the two Tang servers, or by accessing the TPM secure cryptoprocessor and one of the Tang servers:
You can use the `threshold` attribute in your Butane configuration to define the minimum number of TPM v2 and Tang encryption conditions required for decryption to occur.
The threshold is met when the stated value is reached through any combination of the declared conditions.
For example, the `threshold` value of `2` in the following configuration can be reached by accessing the two Tang servers, or by accessing the TPM secure cryptoprocessor and one of the Tang servers:
.Example Butane configuration for disk encryption
@@ -66,31 +80,38 @@ boot_device:
openshift:
fips: true
----
<1> Set this field to the instruction set architecture of the cluster nodes. Some examples include, `x86_64`, `aarch64`, or `ppc64le`.
<1> Set this field to the instruction set architecture of the cluster nodes.
Some examples include, `x86_64`, `aarch64`, or `ppc64le`.
<2> Include this field if you want to use a Trusted Platform Module (TPM) to encrypt the root file system.
<3> Include this section if you want to use one or more Tang servers.
<4> Specify the minimum number of TPM v2 and Tang encryption conditions that must be met for decryption to occur.
<4> Specify the minimum number of TPM v2 and Tang encryption conditions required for decryption to occur.
[IMPORTANT]
====
The default `threshold` value is `1`. If you include multiple encryption conditions in your configuration but do not specify a threshold, decryption can occur if any of the conditions are met.
The default `threshold` value is `1`.
If you include multiple encryption conditions in your configuration but do not specify a threshold, decryption can occur if any of the conditions are met.
====
[NOTE]
====
If you require both TPM v2 and Tang for decryption, the value of the `threshold` attribute must equal the total number of stated Tang servers plus one. If the `threshold` value is lower, it is possible for the threshold to be reached by using one of the encryption modes only. For example, if `tpm2` is set to `true` and you specify two Tang servers, a threshold of `2` can be met by accessing the two Tang servers even if the TPM secure cryptoprocessor is not available.
If you require TPM v2 _and_ Tang for decryption, the value of the `threshold` attribute must equal the total number of stated Tang servers plus one.
If the `threshold` value is lower, it is possible to reach the threshold value by using a single encryption mode.
For example, if you set `tpm2` to `true` and specify two Tang servers, a threshold of `2` can be met by accessing the two Tang servers, even if the TPM secure cryptoprocessor is not available.
====
[id="installation-special-config-mirrored-disk_{context}"]
== About disk mirroring
During {product-title} installation on control plane and worker nodes, you can enable mirroring of the boot and other disks to two or more redundant storage devices. A node continues to function after storage device failure as long as one device remains available.
During {product-title} installation on control plane and worker nodes, you can enable mirroring of the boot and other disks to two or more redundant storage devices.
A node continues to function after storage device failure provided one device remains available.
Mirroring does not support replacement of a failed disk. To restore the mirror to a pristine, non-degraded state, reprovision the node.
Mirroring does not support replacement of a failed disk.
Reprovision the node to restore the mirror to a pristine, non-degraded state.
[NOTE]
====
Mirroring is available only for user-provisioned infrastructure deployments on {op-system} systems. Mirroring support is available on x86_64 nodes booted with BIOS or UEFI and on ppc64le nodes.
Mirroring is available only for user-provisioned infrastructure deployments on {op-system} systems.
Support for mirroring is available on `x86_64` nodes booted with BIOS or UEFI and on `ppc64le` nodes.
====
[id="installation-special-config-storage-procedure_{context}"]
@@ -105,18 +126,22 @@ You can enable and configure encryption and mirroring during an {product-title}
+
[NOTE]
====
Butane is a command-line utility that {product-title} uses to provide convenient, short-hand syntax for writing machine configs, as well as for performing additional validation of machine configs. For more information, see the _Creating machine configs with Butane_ section.
Butane is a command-line utility that {product-title} uses to offer convenient, short-hand syntax for writing and validating machine configs.
For more information, see "Creating machine configs with Butane".
====
+
* You have access to a {op-system-base-full} 8 machine that can be used to generate a thumbprint of the Tang exchange key.
.Procedure
. If you want to use TPM v2 to encrypt your cluster, check to see if TPM v2 encryption needs to be enabled in the BIOS on each node. This is required on most Dell systems. Check the manual for your computer.
. If you want to use TPM v2 to encrypt your cluster, check to see if TPM v2 encryption needs to be enabled in the host firmware for each node.
This is required on most Dell systems.
Check the manual for your specific system.
. If you want to use Tang to encrypt your cluster, follow these preparatory steps:
.. Set up a Tang server or access an existing one. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening#network-bound-disk-encryption_configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption[Network-bound disk encryption] for instructions.
.. Set up a Tang server or access an existing one.
See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening#network-bound-disk-encryption_configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption[Network-bound disk encryption] for instructions.
.. Install the `clevis` package on a {op-system-base} 8 machine, if it is not already installed:
+
@@ -125,7 +150,8 @@ Butane is a command-line utility that {product-title} uses to provide convenient
$ sudo yum install clevis
----
.. On the {op-system-base} 8 machine, run the following command to generate a thumbprint of the exchange key. Replace `\http://tang.example.com:7500` with the URL of your Tang server:
.. On the {op-system-base} 8 machine, run the following command to generate a thumbprint of the exchange key.
Replace `\http://tang.example.com:7500` with the URL of your Tang server:
+
[source,terminal]
----
@@ -135,7 +161,9 @@ $ clevis-encrypt-tang '{"url":"http://tang.example.com:7500"}' < /dev/null > /de
+
[NOTE]
====
The `clevis-encrypt-tang` command is used in this step only to generate a thumbprint of the exchange key. No data is being passed to the command for encryption at this point, so `/dev/null` is provided as an input instead of plain text. The encrypted output is also sent to `/dev/null`, because it is not required for this procedure.
The `clevis-encrypt-tang` command generates a thumbprint of the exchange key.
No data passes to the encryption command during this step; `/dev/null` exists here as an input instead of plain text.
The encrypted output is also sent to `/dev/null`, because it is not required for this procedure.
====
+
.Example output
@@ -151,14 +179,19 @@ When the `Do you wish to trust these keys? [ynYN]` prompt displays, type `Y`.
+
[NOTE]
====
{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.
{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, 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.
.. 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, 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.
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:
@@ -169,7 +202,8 @@ $ ./openshift-install create manifests --dir <installation_directory> <1>
----
<1> Replace `<installation_directory>` with the path to the directory that you want to store the installation files in.
. Create a Butane config that configures disk encryption, mirroring, or both. For example, to configure storage for compute nodes, create a `$HOME/clusterconfig/worker-storage.bu` file.
. Create a Butane config that configures disk encryption, mirroring, or both.
For example, to configure storage for compute nodes, create a `$HOME/clusterconfig/worker-storage.bu` file.
+
[source,yaml]
.Butane config example for a boot device
@@ -197,23 +231,31 @@ openshift:
----
+
<1> For control plane configurations, replace `worker` with `master` in both of these locations.
<2> Set this field to the instruction set architecture of the cluster nodes. Some examples include, `x86_64`, `aarch64`, or `ppc64le`.
<3> Include this section if you want to encrypt the root file system. For more details, see the _About disk encryption_ section.
<2> Set this field to the instruction set architecture of the cluster nodes.
Some examples include, `x86_64`, `aarch64`, or `ppc64le`.
<3> Include this section if you want to encrypt the root file system.
For more details, see "About disk encryption".
<4> Include this field if you want to use a Trusted Platform Module (TPM) to encrypt the root file system.
<5> Include this section if you want to use one or more Tang servers.
<6> Specify the URL of a Tang server. In this example, `tangd.socket` is listening on port `7500` on the Tang server.
<6> Specify the URL of a Tang server.
In this example, `tangd.socket` is listening on port `7500` on the Tang server.
<7> Specify the exchange key thumbprint, which was generated in a preceding step.
<8> Specify the minimum number of TPM v2 and Tang encryption conditions that must be met for decryption to occur. The default value is `1`. For more information on this topic, see the _Configuring an encryption threshold_ section.
<9> Include this section if you want to mirror the boot disk. For more details, see _About disk mirroring_.
<8> Specify the minimum number of TPM v2 and Tang encryption conditions that must be met for decryption to occur.
The default value is `1`.
For more information about this topic, see "Configuring an encryption threshold".
<9> Include this section if you want to mirror the boot disk.
For more details, see "About disk mirroring".
<10> List all disk devices that should be included in the boot disk mirror, including the disk that {op-system} will be installed onto.
<11> Include this directive to enable FIPS mode on your cluster.
+
[IMPORTANT]
====
If you are configuring nodes to use both disk encryption and mirroring, both features must be configured in the same Butane config. In addition, if you are configuring disk encryption on a node with FIPS mode enabled, you must include the `fips` directive in the same Butane config, even if FIPS mode is also enabled in a separate manifest.
If you are configuring nodes to use both disk encryption and mirroring, both features must be configured in the same Butane config.
If you are configuring disk encryption on a node with FIPS mode enabled, you must include the `fips` directive in the same Butane config, even if FIPS mode is also enabled in a separate manifest.
====
. Create a control plane or compute node manifest from the corresponding Butane config and save it to the `<installation_directory>/openshift` directory. For example, to create a manifest for the compute nodes, run the following command:
. Create a control plane or compute node manifest from the corresponding Butane config and save it to the `<installation_directory>/openshift` directory.
For example, to create a manifest for the compute nodes, run the following command:
+
[source,terminal]
----
@@ -241,14 +283,16 @@ If you configure additional data partitions, they will not be encrypted unless e
After installing {product-title}, you can verify if boot disk encryption or mirroring is enabled on the cluster nodes.
. From the installation host, access a cluster node by using a debug pod:
.. Start a debug pod for the node. The following example starts a debug pod for the `compute-1` node:
.. Start a debug pod for the node, for example:
+
[source,terminal]
----
$ oc debug node/compute-1
----
+
.. Set `/host` as the root directory within the debug shell. The debug pod mounts the root file system of the node in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the executable paths on the node:
.. Set `/host` as the root directory within the debug shell.
The debug pod mounts the root file system of the node in `/host` within the pod.
By changing the root directory to `/host`, you can run binaries contained in the executable paths on the node:
+
[source,terminal]
----
@@ -257,7 +301,10 @@ $ oc debug node/compute-1
+
[NOTE]
====
{product-title} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended. However, if the {product-title} API is not available, or `kubelet` is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead.
{product-title} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes.
Accessing cluster nodes using SSH is not recommended.
However, if the {product-title} API is not available, or `kubelet` is not properly functioning on the target node, `oc` operations will be impacted.
In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead.
====
. If you configured boot disk encryption, verify if it is enabled:
@@ -282,9 +329,12 @@ $ oc debug node/compute-1
size: 15683456 sectors
mode: read/write
----
<1> The encryption format. When the TPM v2 or Tang encryption modes are enabled, the {op-system} boot disks are encrypted using the LUKS2 format.
<2> The encryption algorithm used to encrypt the LUKS2 volume. The `aes-cbc-essiv:sha256` cipher is used if FIPS mode is enabled.
<3> The device that contains the encrypted LUKS2 volume. If mirroring is enabled, the value will represent a software mirror device, for example `/dev/md126`.
<1> The encryption format.
When the TPM v2 or Tang encryption modes are enabled, the {op-system} boot disks are encrypted using the LUKS2 format.
<2> The encryption algorithm used to encrypt the LUKS2 volume.
The `aes-cbc-essiv:sha256` cipher is used if FIPS mode is enabled.
<3> The device that contains the encrypted LUKS2 volume.
If mirroring is enabled, the value will represent a software mirror device, for example `/dev/md126`.
+
.. List the Clevis plug-ins that are bound to the encrypted device:
+
@@ -321,10 +371,11 @@ md127 : active raid1 sda4[0] sdb4[1] <2>
unused devices: <none>
----
<1> In the example, the `/dev/md126` software RAID mirror device uses the `/dev/sda3` and `/dev/sdb3` disk devices on the cluster node.
<2> In the example, the `/dev/md127` software RAID mirror device uses the `/dev/sda4` and `/dev/sdb4` disk devices on the cluster node.
<1> The `/dev/md126` software RAID mirror device uses the `/dev/sda3` and `/dev/sdb3` disk devices on the cluster node.
<2> The `/dev/md127` software RAID mirror device uses the `/dev/sda4` and `/dev/sdb4` disk devices on the cluster node.
+
.. Review the details of each of the software RAID devices listed in the output of the preceding command. The following example lists the details of the `/dev/md126` device:
.. Review the details of each of the software RAID devices listed in the output of the preceding command.
The following example lists the details of the `/dev/md126` device:
+
[source,terminal]
----
@@ -361,14 +412,15 @@ Consistency Policy : resync
0 252 3 0 active sync /dev/sda3 <6>
1 252 19 1 active sync /dev/sdb3 <6>
----
<1> Specifies the RAID level of the device. `raid1` indicates RAID 1 disk mirroring.
<1> Specifies the RAID level of the device.
`raid1` indicates RAID 1 disk mirroring.
<2> Specifies the state of the RAID device.
<3> States the number of underlying disk devices that are active and working.
<4> States the number of underlying disk devices that are in a failed state.
<5> The name of the software RAID device.
<6> Provides information about the underlying disk devices that are used by the software RAID device.
<6> Provides information about the underlying disk devices used by the software RAID device.
+
.. List the file systems that are mounted on the software RAID devices:
.. List the file systems mounted on the software RAID devices:
+
[source,terminal]
----
@@ -399,4 +451,4 @@ In the example output, the `/boot` file system is mounted on the `/dev/md126` so
[role="_additional-resources"]
.Additional resources
* For more information about the TPM v2 and Tang encryption modes, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening[Configuring automated unlocking of encrypted volumes using policy-based decryption].
* For more information about the TPM v2 and Tang encryption modes, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening[Configuring automated unlocking of encrypted volumes using policy-based decryption].

View File

@@ -16,11 +16,8 @@ Adding worker nodes to {sno} clusters is only supported for clusters running {pr
.Prerequisites
* Have access to a {sno} cluster installed using link:https://console.redhat.com/openshift/assisted-installer/clusters/~new[Assisted Installer].
* Install the OpenShift CLI (`oc`).
* Log in as a user with `cluster-admin` privileges.
* Ensure that all the required DNS records exist for the cluster that you are adding the worker node to.
.Procedure
@@ -34,3 +31,8 @@ Adding worker nodes to {sno} clusters is only supported for clusters running {pr
. As the installation proceeds, the installation generates pending certificate signing requests (CSRs) for the worker node. When prompted, approve the pending CSRs to complete the installation.
+
When the worker node is sucessfully installed, it is listed as a worker node in the cluster web console.
[IMPORTANT]
====
New worker nodes will be encrypted using the same method as the original cluster.
====