MTV-3397-Enabling nbde vmware

documentation/doc-Planning_your_migration/assemblies/assembly_planning-migration-vmware.adoc

@@ -13,12 +13,12 @@ ifdef::context[:parent-context: {context}]
 
 You prepare and create your VMware vSphere migration plan by performing the following high-level steps in the MTV UI:
 
-- Create ownerless network maps
-- Add a VMware vSphere source provider
-- Select a migration network for a VMware source provider
-- Add an OpenShift Virtualization destination provider
-- Select a migration network for an OpenShift Virtualization provider
-- Create a VMware vSphere migration plan
+- Create ownerless network maps.
+- Add a VMware vSphere source provider.
+- Select a migration network for a VMware source provider.
+- Add an OpenShift Virtualization destination provider.
+- Select a migration network for an OpenShift Virtualization provider.
+- Create a VMware vSphere migration plan.
 
 :context: vmware
 :vmware:
@@ -47,9 +47,12 @@ include::../modules/selecting-migration-network-for-virt-provider.adoc[leveloffs
 
 include::../modules/creating-plan-wizard-vmware.adoc[leveloffset=+1]
 
-
 :!vmware:
 
+include::../modules/con_migration-of-luks-encrypted-disks.adoc[leveloffset=+1]
+
+include::../modules/proc_enabling-nbde-with-clevis.adoc[leveloffset=+1]
+
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]
 

documentation/modules/con_migration-of-luks-encrypted-disks.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// assembly_planning-migration-vmware.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="con_migration-of-luks-encrypted-disks_{context}"]
+
+= Migration of LUKS-encrypted disks
+
+[role="_abstract"]
+If you have virtual machines (VMs) with LUKS-encrypted disks in your source VMware VSphere environment, you can migrate them to Red Hat {virt} by enabling Network-Bound Disk Encryption (NBDE) with Clevis. Alternatively, you can manually add passwords for LUKS-encrypted devices in your migration plan. 
+
+If you enable NBDE, passwords are retrieved from the Clevis server. When you manually add LUKS passwords to your migration plan, you provide the list of passwords, and you cannot use NBDE to retrieve them. The two methods for migrating LUKS-encrypted disks are incompatible. You must use either NBDE or manual LUKS passwords to migrate LUKS-encrypted disks.
+
+MTV transfers the data of VMs with LUKS-encrypted disks from the source environment to the target {virt} cluster. MTV reads only the blocks that are required for guest conversion, decrypting the required blocks and re-encrypting them locally with the same key.
+
+Clevis is a client-side framework that automates the decryption of LUKS volumes by binding a LUKS key slot to a policy. During the migration of VMs with LUKS-encrypted disks, MTV authenticates with the configured network service by requesting the key to unlock the LUKS-encrypted disk from the Tang server. The automatic retrieval of the key allows the VM to boot without a manual passphrase entry from an administrator.
+
+Benefits of NBDE::
+
+* *Automation:* Eliminates the need to enter keys manually during migration.
+* *Enhanced security:* Maintains the security of VMs throughout their migration lifecycle by preserving LUKS encryption from the source to the destination.
+* *Seamless operation:* Ensures that VMs with encrypted disks can be brought online in the new OpenShift Virtualization environment with minimal interruption.
+
+

documentation/modules/proc_enabling-nbde-with-clevis.adoc

@@ -0,0 +1,60 @@
+// Module included in the following assemblies:
+//
+// assembly_planning-migration-vmware.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc_enabling-nbde-with-clevis_{context}"]
+
+= Enabling Network-Bound Disk Encryption with Clevis 
+
+[role="_abstract"]
+When you enable Network-Bound Disk Encryption (NBDE) with Clevis, the Tang server manages the keys for Linux Unified Key Setup (LUKS)-encrypted disks during a migration. If you do not use NBDE to migrate LUKS-encrypted disks from your source environment, you can manually add passwords for LUKS-encrypted devices instead. You must use either NBDE or manual LUKS passwords to migrate LUKS-encrypted disks.
+
+You can enable NBDE with Clevis either in the MTV UI or in the YAML file for your migration plan:
+
+* In the MTV UI, you must select either NBDE with Clevis or LUKS passphrases. You can have only one encryption type, and you apply the setting to all VMs in your migration plan.
+* In the YAML file for your migration plan, you can combine encryption types and apply the setting to selected VMs in the YAML file.
+
+.Prerequisites
+* The Tang server is accessible from your OpenShift cluster and from the migration network.
+* You have a LUKS key slot bound to the Tang server policy.
++
+NOTE: For MTV to access the keys from the Tang server, the keys must be on a different subnet range than a user-defined network (UDN).
+
+.Procedure
+. Enable NBDE with Clevis in the MTV UI.
+.. In the Create migration plan wizard, navigate to *Other settings* under *Additional setup* in the left navigation pane.
+.. Select *Use NBDE/Clevis*. 
++
+If you are not using NBDE with Clevis, you add passphrases for LUKS-encrypted devices so that the Tang servers can decrypt the disks during a migration.
+.. Click *Next*, and verify that *Use NBDE/Clevis* shows as *Enabled* under *Other settings (optional)*.
+.. When you create your migration plan, click *Migration plans* in the left navigation menu, and open the *Plan Details* page for your migration plan.
+.. Click the *Edit* icon for *Disk decryption* under *Plan settings*.
+.. Verify that *Use network-bound disk encryption (NBDE/Clevis)* is selected. 
++
+If you are not using NBDE with Clevis, verify that the passphrases for LUKS-encrypted devices are added. 
+
+. Enable NBDE with Clevis in the YAML file.
+.. Click *Migration plans* in the left navigation menu and open the *Plan Details* page for your migration plan.
+.. Click the *YAML* tab to open the `Plan` custom resource (CR) for your migration plan.
+.. For each VM under `vms` in the YAML file, enter the encryption type. In this example, you set `nbdeClevis` as the encryption type for `vm-1`, LUKS passphrase as the encryption type for `vm-2`, and no encryption type for `vm-3`:
++
+Example:
++
+----
+vms:
+  - id: vm-1
+    name: vm-1-esx8.0-rhel8.10-raid1
+    targetPowerState: on
+    nbdeClevis: true
+  - id: vm-2
+    name: vm-2-esx8.0-rhel8.10-raid1
+    luks: { name: 'test-secret-1' }
+  - id: vm-3
+    name: vm-3-esx8.0-rhel8.10-raid1
+----
+
+.Troubleshooting
+* For information about LUKS or Clevis configuration on the source VM, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html-single/security_hardening/index#configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening[Configuring automated unlocking of encrypted volumes by using policy-based decryption] in the RHEL _Security hardening_ guide.
+
+