Merge pull request #17007 from alkohli/aktvm

TVM changes

Author: denrea

.openpublishing.redirection.azure-local.json

@@ -1911,4 +1911,4 @@
       "redirect_document_id": false
     }
   ]
-}
+}

azure-local/TOC.yml

@@ -275,11 +275,11 @@ items:
 
   - name: Trusted launch for Arc VMs
     items: 
-      - name: What is Trusted Launch for Arc VMs?
+      - name: What is Trusted launch for Arc VMs?
         href: manage/trusted-launch-vm-overview.md
-      - name: Deploy Trusted Launch for Arc VMs
-        href: manage/trusted-launch-vm-deploy.md
-      - name: Manage guest state protection key
+      - name: Automatic virtual TPM state transfer
+        href: manage/trusted-launch-automatic-state-transfer.md
+      - name: Manual backup and recovery
         href: manage/trusted-launch-vm-import-key.md
 
   - name: Non Arc VMs

azure-local/manage/create-arc-virtual-machines.md

@@ -136,7 +136,33 @@ Here we create a VM that uses specific memory and processor counts on a specifie
     | **storage-path-id** |The associated storage path where the VM configuration and the data are saved.  |
     | **proxy-configuration** |Use this optional parameter to configure a proxy server for your VM. For more information, see [Create a VM with proxy configured](#create-a-vm-with-proxy-configured).  |
 
-1. Run the following command to create a VM.
+1. Run the following commands to create the applicable VM.
+
+    **To create a Trusted launch Arc VM:**
+
+    1. Specify additional flags to enable secure boot, enable virtual TPM, and choose security type. Note, when you specify security type as Trusted launch, you must enable secure boot and vTPM, otherwise Trusted launch VM creation will fail.
+
+        ```azurecli
+        az stack-hci-vm create --name $vmName --resource-group $resource_group --admin-username $userName --admin-password $password --computer-name $computerName --image $imageName --location $location --authentication-type all --nics $nicName --custom-location $customLocationID --hardware-profile memory-mb="8192" processors="4" --storage-path-id $storagePathId --enable-secure-boot true --enable-vtpm true --security-type "TrustedLaunch"
+        ```
+
+    1. Once the VM is created, to verify the security type of the VM is `Trusted launch`, do the following.
+
+    1. Run the following cmdlet (on one of the cluster nodes) to find the owner node of the VM:
+
+        ```azurecli
+        Get-ClusterGroup $vmName
+        ```
+
+    1. Run the following cmdlet on the owner node of the VM:
+
+        ```azurecli
+        (Get-VM $vmName).GuestStateIsolationType
+        ```
+
+    1. Ensure a value of `TrustedLaunch` is returned.
+
+    **To create a standard Arc VM:**
 
    ```azurecli
     az stack-hci-vm create --name $vmName --resource-group $resource_group --admin-username $userName --admin-password $password --computer-name $computerName --image $imageName --location $location --authentication-type all --nics $nicName --custom-location $customLocationID --hardware-profile memory-mb="8192" processors="4" --storage-path-id $storagePathId 
@@ -247,7 +273,7 @@ Follow these steps in Azure portal for your Azure Local.
 
         **The Virtual machine kind** is automatically set to **Azure Local**.
 
-    1. **Security type** - For the security of your VM, select **Standard** or **Trusted Launch virtual machines**. For more information on what are Trusted Launch Arc virtual machines, see [What is Trusted Launch for Azure Arc Virtual Machines?](./trusted-launch-vm-overview.md).
+    1. **Security type** - For the security of your VM, select **Standard** or **Trusted launch virtual machines**. For more information on what are Trusted launch Arc virtual machines, see [What is Trusted launch for Azure Arc Virtual Machines?](./trusted-launch-vm-overview.md).
 
    1. **Storage path** - Select the storage path for your VM image. Select **Choose automatically** to have a storage path with high availability automatically selected. Select **Choose manually** to specify a storage path to store VM images and configuration files on your Azure Local. In this case, ensure that the selected storage path has sufficient storage space.
 

azure-local/manage/trusted-launch-automatic-state-transfer.md

@@ -0,0 +1,85 @@
+---
+title: Automatic virtual TPM state transfer for Azure Local
+description: Learn how automatic virtual TPM state transfer works for Azure Local.
+ms.topic: how-to
+author: alkohli
+ms.author: alkohli
+ms.service: azure-local
+ms.date: 02/27/2025
+---
+
+# Automatic transfer of virtual TPM state for Trusted launch VMs on Azure Local
+
+[!INCLUDE [applies-to](../includes/hci-applies-to-23h2.md)]
+
+This article uses an example to illustrate the automatic transfer of virtual TPM (vTPM) state in the case of Trusted launch Arc VMs on Azure Local, even as the VM migrates or fails over to another machine in the system. This operation allows the applications that use the vTPM to function normally during VM migration or fail over.
+
+
+## Example
+
+This example shows a Trusted launch Arc VM running Windows 11 guest with BitLocker encryption enabled. Here are the steps to run this example:
+
+1. Create a Trusted launch Arc VM running a supported Windows 11 guest operating system (OS).
+
+1. Enable BitLocker encryption for the OS volume on the Win 11 guest. Sign on to the Windows 11 guest and enable BitLocker encryption for the OS volume:
+
+    1. In the search box on the task bar, type "Manage BitLocker," and then select it from the list of results.
+
+    1. Select **Turn on BitLocker** and then follow the instructions to encrypt the OS volume (C:). BitLocker uses vTPM as a key protector for the OS volume.
+
+1. Confirm the owner node of the VM.
+
+    ```powershell
+    Get-ClusterGroup <VM name>
+    ```
+
+1. Migrate the VM to another machine in the system. Run the following PowerShell command from the machine that the VM is on.
+
+    ```powershell
+    Move-ClusterVirtualMachineRole -Name <VM name> -Node <destination node> -MigrationType Shutdown
+    ```
+
+1. Confirm that the owner node of the VM is the specified destination node.
+
+    ```powershell
+    Get-ClusterGroup <VM name>
+    ```
+
+1. After VM migration completes, verify if the VM is available and BitLocker is enabled.
+
+1. Verify that you can sign on to the Windows 11 guest in the VM, and if BitLocker encryption for the OS volume remains enabled. If true, this confirms that the vTPM state was preserved during VM migration.
+
+    > [!NOTE]
+    > If vTPM state wasn't preserved during VM migration, VM startup would result in BitLocker recovery during guest boot up. You would be prompted for the BitLocker recovery password when you attempted to sign on to the Windows 11 guest. This situation occurs because the boot measurement (stored in the vTPM) of the migrated VM on the destination node is different from that of the original VM.
+
+1. Force the VM to fail over to another machine in the system.
+
+    1. Confirm the owner node of the VM using the following command.
+
+        ```powershell
+        Get-ClusterGroup <VM name>
+        ```
+
+    1. Use Failover Cluster Manager to stop the cluster service on the owner node as follows: Select the owner node as displayed in Failover Cluster Manager.  On the **Actions** right pane, select **More Actions** and then select **Stop Cluster Service**.
+
+    1. Stopping the cluster service on the owner node causes the VM to be automatically migrated to another available machine in the system. Restart the cluster service afterwards.
+
+1. After failover completes, verify if the VM is available and BitLocker is enabled after failover.
+
+1. Confirm that the owner node of the VM is the specified destination node.
+
+    ```powershell
+    Get-ClusterGroup <VM name>
+    ```
+
+1. After VM failover completes, verify if the VM is available and BitLocker is enabled.
+
+1. Verify that you can sign on to the Windows 11 guest in the VM, and if BitLocker encryption for the OS volume remains enabled. If true, the vTPM state was preserved during VM failover.
+
+    > [!NOTE]
+    > If vTPM state wasn't preserved during VM migration, VM startup would result in BitLocker recovery during guest boot up. You would be prompted for the BitLocker recovery password when you attempted to sign on to the Windows 11 guest. This situation occurs because the boot measurement (stored in the vTPM) of the migrated VM on the destination node is different from that of the original VM.
+
+
+## Next steps
+
+- [Manage Trusted launch Arc VM guest state protection key](trusted-launch-vm-import-key.md).

azure-local/manage/trusted-launch-vm-import-key.md

@@ -1,92 +1,151 @@
 ---
-title: Manage Trusted launch Arc VM guest state protection key on Azure Local, version 23H2
-description: Learn how to manage a Trusted launch Arc VM guest state protection key on Azure Local, version 23H2.
+title: Manage Trusted launch Arc VM guest state protection key on Azure Local
+description: Learn how to manage a Trusted launch Arc VM guest state protection key on Azure Local.
 author: alkohli
 ms.author: alkohli
 ms.topic: how-to
 ms.service: azure-local
 ms.reviewer: alkohli
-ms.date: 01/28/2025
+ms.date: 02/21/2025
 ---
 
-# Manage Trusted launch Arc VM guest state protection key on Azure Local
+# Manage backup and recovery of Trusted launch Arc VMs on Azure Local
 
 [!INCLUDE [applies-to](../includes/hci-applies-to-23h2.md)]
 
-This article describes how to manage a Trusted launch Arc VM guest state protection key on Azure Local.
+This article describes how to manually back up and restore a Trusted launch Arc VM on Azure Local.
 
-A VM guest state protection key is used to protect the VM guest state, like the vTPM state, while at rest in storage. It's not possible to boot up a Trusted launch Arc VM without the guest state protection key. The key is stored in a key vault in the Azure Local system where the VM is located.
+Unlike standard Azure Arc VMs, Trusted launch Arc VMs use a VM guest state protection (GSP) key to protect the VM guest state, including the virtual TPM (vTPM) state, while at rest. The VM GSP key is stored in a local key vault in the Azure Local system where the VM resides. 
 
+Trusted launch Arc VMs store the VM guest state in two files, VM Guest state (VMGS) and VM Runtime state (VMRS). If the VM GSP key is lost, you can't boot up a Trusted launch Arc VM.
 
-## Export and import the VM
+It is important that you back up your Trusted launch Arc VM periodically, so you can recover your VM in the event of a data loss. To back up a Trusted launch VM, back up all the VM files, including VMGS and VMRS files. Additionally, back up the VM GSP key to a backup key vault. 
 
-The first step is to export the VM from the source Azure Local system and then import it into the target Azure Local system.
+Similarly, to restore a Trusted launch Arc VM to a target Azure Local system, restore all the VM files, including VMGS and VMRS files. Additionally, restore the VM GSP key from the backup key vault to another key vault on the target Azure Local system.
 
-1. To export the VM from the source cluster, see [Export-VM (Hyper-V)](/powershell/module/hyper-v/export-vm).
+The following sections describe how you can back up the Trusted launch Arc VM and restore it in the event of a data loss.
 
-2. To import the VM to the target cluster, see [Import-VM (Hyper-V)](/powershell/module/hyper-v/import-vm).
+## Back up the VM
 
-## Transfer the VM guest state protection key
+You can use [Export-VM](/powershell/module/hyper-v/export-vm) to obtain a copy of all the VM files, including VMGS and VMRS files, for your Trusted launch Arc VM. You can then back up those VM files.
 
-After you have exported and then imported the VM, use the following steps to transfer the VM guest state protection key from the source Azure Local system to the target Azure Local system:
+Follow these steps to copy the VM GSP key from the key vault on the Azure Local system (where the VM resides) to a backup key vault on a different Azure Local system:
 
-### 1. On the target Azure Local system
 
-Run the following commands from the target Azure Local system.
-
-1. Sign into the key vault using administrative privileges.
+### 1. On the Azure Local system with the backup key vault
 
-   ```azurepowershell
-   mocctl.exe security login --identity --loginpath (Get-MocConfig).mocLoginYAML --cloudFqdn (Get-MocConfig).cloudFqdn
-   ```
+Run the following commands on the Azure Local system with the backup key vault.
 
-1. Create a master key in the target key vault. Run the following command.
+1. Create a wrapping key in the backup key vault.
 
-   ```azurepowershell
-   mocctl.exe security keyvault key create --location VirtualMachineLocation --group AzureStackHostAttestation --vault-name AzureStackTvmKeyVault --key-size 2048 --key-type RSA --name master
-   ```
+    ```azurecli
+    New-MocKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type RSA -size 2048
+    ```
 
 1. Download the Privacy Enhanced Mail (PEM) file.
 
-   ```azurepowershell
-   mocctl.exe security keyvault key download --name master --file-path C:\master.pem --vault-name AzureStackTvmKeyVault
-   ```
+    ```azurecli
+    Get-MocKeyPublicKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -outputFile wrappingKey.pem
+    ```
+
+### 2. On the Azure Local system where the VM resides
+
+Run the following commands on the Azure Local system.
+
+1. Copy the PEM file to the Azure Local system.
+
+1. Confirm the owner node of the VM.
+
+    ```azurecli
+    Get-ClusterGroup <VM name>
+    ```
+
+1. Run the following cmdlet on the owner node to determine the VM ID.
+
+    ```azurecli
+    (Get-VM -Name <VM name>).vmid
+    ```
+
+1. Export the GSP key for the VM.
+
+    ```azurecli
+    Export-MocKey -name <VM ID> -wrappingKeyName wrappingKey -wrappingPubKeyFile wrappingKey.pem -outFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -size 256
+    ```
+
+### 3. On the Azure Local system with the backup key vault
+
+Run the following steps on the Azure Local system.
+
+1. Copy the `<VM ID>` and `<VM ID>.json` file to the Azure Local system.
 
-### 2. On the source Azure Local system
+1. Import the GSP key for the VM to the backup key vault.
 
-Run the following commands from the source Azure Local system.
+    ```azurecli
+    Import-MocKey -name <VM ID> -importKeyFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type AES -size 256
+    ```
 
-1. Copy the PEM file from the target cluster to the source cluster.
+## Restore the VM
 
-1. Run the following cmdlet to determine the ID of the VM.
+In the event of a data loss, use the backup copy of your VM files, and restore the VM to a target Azure Local system using [Import-VM](/powershell/module/hyper-v/import-vm). This restores all the VM files, including VMGS and VMRS files.
 
-   ```azurepowershell
-   (Get-VM -Name <vmName>).vmid  
-   ```
+Follow these steps to copy the VM GSP key from the backup key vault in the Azure Local system (where the backup copy of the VM GSP key was stored) to the key vault on the target Azure Local system (where the VM needs to be restored).
 
-1. Sign into the key vault using administrative privileges.
+> [!NOTE]
+> Trusted launch Arc VMs restored on an alternate Azure Local system (different from the Azure Local system where the VM originally resided) can't be managed from the Azure control plane.
 
-   ```azurepowershell
-     mocctl.exe security login --identity --loginpath (Get-MocConfig).mocLoginYAML --cloudFqdn (Get-MocConfig).cloudFqdn
-   ```
 
-1. Export the VM guest state protection key for the VM.
+### 1. On the source Azure Local system where the VM needs to be restored
 
-   ```azurepowershell
-   mocctl.exe security keyvault key export --vault-name AzureStackTvmKeyVault --name <vmID> --wrapping-pub-key-file C:\master.pem --out-file C:\<vmID>.json  
-   ```
+Run the following commands on the Azure Local system.
 
-### 3. On the target Azure Local system
+1. Create a wrapping key in the key vault.
+
+    ```azurecli
+    New-MocKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type RSA -size 2048
+    ```
+
+1. Download the Privacy Enhanced Mail (PEM) file.
+
+    ```azurecli
+   Get-MocKeyPublicKey -name wrappingKey -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -outputFile wrappingKey.pem
+    ```
+
+### 2. On the Azure Local system with the backup key vault
+
+Run the following commands on the Azure Local system.
+
+1. Copy the PEM file to the Azure Local system.
+
+1. Get the `<VM ID>` from the VM files stored on disk (wherever this is located). There will be a VM config file (.xml) that has the `<VM ID>` as its name. You can also use the following command to obtain the `<VM ID>` if you know the VM name. You need to do this step on a Hyper-V host that has the VM files.
+
+    ```azurecli
+    (Get-VM -Name <VM name>).vmid
+    ```
+
+1. Export the VM GSP key for the VM.
+
+    ```azurecli
+    Export-MocKey -name <VM ID> -wrappingKeyName wrappingKey -wrappingPubKeyFile wrappingKey.pem -outFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -size 256
+    ```
+
+### 3. On the Azure Local system where the VM needs to be restored
 
 Run the following commands from the target Azure Local system.
 
-1. Copy the `vmID` and `vmID.json` file from the source cluster to the target cluster.
+1. Copy the `<VM ID>` and `<VM ID>.json` file to the Azure Local system.
+
+1. Import the VM GSP key for the VM.
+
+    ```azurecli
+    Import-MocKey -name <VM ID> -importKeyFile <VM ID>.json -group AzureStackHostAttestation -keyvaultName AzureStackTvmKeyVault -type AES -size 256
+    ```
 
-1. Import the VM guest state protection key for the VM.
+    > [!NOTE]
+    > Restore the VM GSP key (complete the steps above) before you start the VM on the Azure Local system (where the VM needs to be restored). This ensures that the VM uses the restored VM GSP key. Otherwise, the VM creation fails, and a new VM GSP key is created by the system. If this happens by mistake (human error), delete the VM GSP key and then repeat the steps to restore the VM GSP key.
 
-   ```azurepowershell
-   mocctl.exe security keyvault key import --key-file-path C:\<vmID>.json --name <vmID> --vault-name AzureStackTvmKeyVault --wrapping-key-name master --key-type AES --key-size 256
-   ```
+    ```azurecli
+    Remove-MocKey -name <vm id> -group AzureStackHostAttestation -keyvaultName > AzureStackTvmKeyVault
+    ```
 
 ## Next steps