Enable guest management for migrated VMs (preview)

Article
11/19/2024

Applies to: Azure Local 2311.2 and later

This article describes how to enable guest management after migration for Arc virtual machines (VMs) running on Azure Local, version 23H2.

For more information on other scenarios, see Manage Arc VMs on Azure Local.

The output properties may vary depending on whether VMs were migrated or not.

Important

This feature is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Prerequisites

Before you begin, complete the following:

You have access to a deployed and registered Azure Local instance, with an Arc Resource Bridge and custom location configured.
Your system is running Azure Local, version 23H2, release 2405 or later.
Azure CLI is installed on the Azure Local instance. For instructions, see Install the Azure CLI for Windows.

Add the stack-hci-vm Azure extension by running PowerShell as administrator:

To add the stack-hci-vm extension, run the following cmdlet:
```
az extension add --name stack-hci-vm --upgrade 
```

To verify the installation and check that the stack-hci-vm version is 1.1.5 or later:

PS C:\Users\AzureStackAdminD> az version
{
    "azure-cli": ”2.60.0”,
    "azure-cli-core": ”2.60.0”,
    "azure-cli-telemetry": "1.1.0",
    "extensions": {
        "aksarc": ‘1. 2.20" ,
        "arcappliance": "1.1.1", 
        "connectedk8s": "1.6. 2‘ ,
        "customlocation": "0.1.3",
        "k8s-extension": "1.4. 5" ,
        "stack-hci-vm": "1.1.8"
}

Familiarize yourself with Arc VMs and guest management features and considerations - see Enable guest management.

Enable the guest agent on migrated VMs

All Hyper-V generation 1 VMs must be powered off before proceeding with the following steps. There is no such requirement for Hyper-V generation 2 VMs, they can be either on or off and both power states are expected to work.

Step 1: Check the power state of the migrated VMs as follows:

For Hyper-V Generation 1, make sure the VM is stopped. See the Appendix for the error message if it is not stopped.

Using Azure portal (recommended)
1. To stop migrated VM from Azure portal, select Stop on the VM details page:
1. Wait and refresh the page to see the VM Status is shown as Stopped.
Using Azure CLI
1. Connect to Azure Local machine and open a PowerShell window. Sign on with Azure CLI.
```
az login --use-device-code --tenant $tenantId
```
2. Check the VM power state using Azure CLI as follows:
```
az stack-hci-vm show --name $vmName --resource-group $rgName --query "properties.status"
```
  Sample output:
```
PS C : \Users\AzureStackAdminD> az stack-hci-vm show --name <VM name> --resource-group <resource group> --query "properties.status"
{
    "errorCode":
    "errorMessage" :
    "powerstate": "Stopped",
    "provisioningstatus": null
}
```
For Hyper-V generation 2 VMs, ensure the power status shown on Azure portal matches the actual power state of the migrated VM on Hyper-V Manager, regardless of whether it is On or Off:

Azure portal view

Hyper-V Manager view

Step 2: Attach the ISO for the guest agent on the migrated VM as follows:

Connect to an Azure Local machine and run the following command in PowerShell, where $vmName is the name of the migrated VM to have guest agent enabled and $rgName is the name of the resource group where this VM lives on Azure:

az stack-hci-vm update --name $vmName --resource-group $rgName --enable-vm-config-agent true

Sample output:

PS C:\Users\AzureStackAdminD> az stack-hci-vm update --name $vmName -enable-vm-config-agent true --resource-group $resourceGroup
{
"endTime": "2024-08-19T22:01:22.1060463z",
"error": {},
"extendedLocation": null ,
"id": "<ID>",
"identity": null,
"name": "<Name>",
"properties": null,
"resourceld": "<Resource ID>",
"startTime": "2024-08-19T22: 01:09.4898702z" ,
"status": "Succeeded",
"systemData" : null,
"type": null
}

Sample state of the VM with the ISO attached, viewed from the Azure Local system:

Step 3: Turn on the migrated VM, if needed, in Azure portal and ensure it has public network connectivity as follows:

Check that the VM Status on Azure portal is Running:

Check that the VM powerState is Running by running following command on your Azure Local machine in a PowerShell window:

az stack-hci-vm show --name $vmName --resource-group $rgName --query “properties.status”

PS C: \Users\AzureStackAdminD> az stack-hci-vm show --name <Name> --resource-group <Resource group> --query "properties.status" 
{
"errorCode":
"errorMessage":
"powerState": "Running",
"provisioningStatus": null
}

Step 4: Install the guest agent ISO on the migrated VM as follows:

Connect to the VM using your applicable OS-specific steps.
Establish public network connectivity on the VM.

Run the following command to enable the guest agent on the VM based on the OS you are using:

If on Linux, open Terminal and run:

sudo -- sh -c 'mkdir /mociso && mount -L mocguestagentprov /mociso && bash /mociso/install.sh && umount /mociso && rm -df /mociso'

Sample output (Linux):

migration@migration-virtual-machine: $ sudo -- sh -c 'mkdir /mociso && mount -L mocguestagentprov /nociso && bash /mociso/install.sh && umount /mociso && rm -df/mociso && eject LABEL=mocguestagentprov'
[sudo] password for migration:
mount: /moctso: WARNING: device write-protected, mounted read-only.
Loading configuration version 've.16.5'...
The agent could not find the '/opt/mocguestagent/v0.16.5/config.yaml' config file. Looking for older versions to upgrade from...
Service installed.
Service started.
The guest agent was successfully installed.

If on Windows, open PowerShell as administrator and run:

  $d=Get-Volume -FileSystemLabel mocguestagentprov;$p=Join-Path ($d.DriveLetter+':\') 'install.ps1';powershell $p

Sample output (Windows):

PS C:\Users\Administrator> $d=Get-Volume -FilesystemLabel mocguestagentprov;$p=Join-Path ($d.DriveLetter+':\') 'install ps1';powershell $p

Directory : C : \ProgramData\mocguestagent


Mode	LastWriteTime	Length Name
----    -------------   -----------
d------	8/19/2024	5:46 PM	certs
Loading configuration version 'v0.16.5'...
The agent could not find the 'C:\ProgramData\mocguestagent\v0.16.5\config.yaml' config file. Looking for older versions to upgrade from...
Service installed.
Service started.
The guest agent was successfully installed.

Enable guest management

You can enable guest management after the guest agent is running as follows:

Enable guest management from your Azure Local instance by running the following command in Azure CLI:

az stack-hci-vm update --name $vmName --resource-group $rgName --enable-agent true

Sample output:

PS C:\Users\AzureStackAdminD> az stack-hci-vm update --name $vmName --resource-group $resourceGroup --enable-agent true
{
"endTime": "2024-08-19T22:59:13.9583373Z”,
"error": {},
"extendedLocation" : null,
"id": "/<ID>",
"identity": null,
"name": "<Name>",
"properties": null,
"resourceld": "<Resource ID",
"startTime": "2024-08-19t22:28:23.8158331Z",
"status": "Succeeded",
"systemData": null,
"type": null
}

Check for guest management enablement status in Azure portal:
You are now ready to add the Azure extensions of your choice.

If you encounter any issues, contact Microsoft Support and provide your logs and deployment details.

Appendix

If you forgot to turn off Hyper-V Generation 1 VM before running the update command with --enable-vm-config-agent true, the update command will fail and the VM may become unmanageable from Azure portal:

PS C:\Users\AzureStackAdminD> az stack-hci-vm update --name <VM name> -- resource-group <Resource group> --enable-vm-config-agent true
(Failed) moc-operator virtualmachine serviceclient returned an error while reconciling: rpc error: code = Unknown dasc = AddlSODisk for IsoFile mocguestagentprov.iso failed. Error: ErrorCode[32768] ErrorDescription[<VM name>' failed to add device 'Synthetic DVD Drive'. (Virtual machine ID <VM ID>)] ErrorSummaryDescription [Failed to add device 'Synthetic DVD Drive'.]: WMI Error 0x00008000: Failed
Code: Failed
Message: moc-operator virtualmachine serviceclient returned an error while reconciling: rpc error: code = Unknown desc = AddlSODisk for IsoFile mocguestagentprov.iso failed. Error: ErrorCode[32768] ErrorDescription['<VM name>' failed to add device 'Synthetic DVD Drive'. (Virtual machine ID <VM ID>)] ErrorSummaryDescription [Failed to add device 'Synthetic DVD Drive'.]: WMI Error 0x00008000: Failed

To resolve this, stop the VM in Azure portal by selecting Stop. If this doesn't work, run the following command from Azure CLI:

az stack-hci-vm stop --name $vmName --resource-group $rgName

You may see a Resource failed to provision error in Azure portal with Start, Restart, and Stop selections disabled, but Hyper-V Manager should show the VM is actually stopped:

az stack-hci-vm update --name $vmName --resource-group $rgName --enable-vm-config-agent true

Next steps

If you experience any issues, see Troubleshoot VMware migration issues.

Share via