How To Rename an Azure Virtual Machine

Updated – 25/07/2024 – This article has been updated to consider renaming Azure Virtual Machine (VM) with multiple network interfaces (NICs).

Updated – 24/01/2023 – This article has been updated to consider renaming Azure Virtual Machine (VM) with Trusted Launch and Secure Boot enabled.

Updated – 07/03/2022 – Depending on how you delete a VM, it may only delete the VM resource, not the networking and disk resources. Microsoft has added a new capability where you can change the default settings for what other resources are deleted when you delete a VM (OS Disk, Data disk, and Network Interfaces). This article has been updated to take into consideration the recent changes by Microsoft and prevent disk deletion if you have this new option enabled.

In this article, we will share with you how to rename an Azure virtual machine using PowerShell. The same can apply whether you want to rename a Linux or Windows VM.

Introduction

Renaming an Azure VM is not a new problem. If you are coming from the on-premises world, you know how simple it is to rename a virtual machine in Hyper-V, VMware, or any other virtualization platform. This is not the case when you deploy a Virtual Machine using the Azure Portal, and you find yourself having to rename it afterward, you know how painful it is.

If you deploy your VMs with any infrastructure-as-code (IaC) tool such as ARM template, Bicep, or Terraform, or you use PowerShell or Azure CLI, then you can specify the Azure VM name at deployment time. But again, we can’t rename it after the deployment is completed.

Well, this is the purpose of this article, we have developed a nifty PowerShell tool that will help you to rename an Azure VM (Windows or Linux) by destroying the VM resource without touching the existing resources and then re-creating it with a new name and attach all the resources. This will apply to Azure virtual machine(s) with Managed Disks and Unmanaged Disks.

Related: If you want to rename the OS Disk for an Azure virtual machine, please check the following article.

Related: If you want to rename the Data Disks for an Azure virtual machine, please check the following article.

Related: If you want to rename the NIC interface for an Azure virtual machine, please check the following article.

Update the delete behavior on an existing VM

Updated – 07/03/2022 – Depending on how you delete a VM, it may only delete the VM resource, not the networking and disk resources. Microsoft has recently added a new capability where you can change the default settings for what other resources are deleted when you delete a VM (OS Disk, Data Disk, and Network Interface) delete option.

By default, disks, NICs, and Public IPs associated with a VM are persisted when the VM is deleted. However, if you configured these resources to be automatically deleted, then make sure to update the settings before you run the PowerShell (Rename-AzVM.ps1) tool below so the resources remain after the VM is deleted. The PowerShell tool was also updated to take into consideration this new behavior and prevent renaming the VM if the delete behavior is set to “Delete“.

To keep these resources intact, we need to use and set the (deleteOption) property to “Detach” by using the Azure REST API to change the behavior when you delete a VM. At the time of this writing, updating the behavior when you delete a VM is not supported with the Azure portal, Azure CLI, or Azure PowerShell.

The following REST API example will update the VM delete behavior to “Detach” instead of “Delete” so the NIC, OS disk, and data disk will be preserved when the VM is deleted.

I strongly recommend running the Get (REST API) first before performing the Update: Run Virtual Machines – Get REST API to verify the current delete behavior of your existing VM.

Then make sure to update the {subscriptionId}, {RGName}, and {vmName} values before you update the virtual machine. You can perform this operation directly using the Microsoft REST API service here.

PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{RGName}/
providers/Microsoft.Compute/virtualMachines/{vmName}?api-version=2021-07-01 

{ 
    "properties": {        
        "hardwareProfile": { 
            "vmSize": "Standard_D2s_v3" 
        }, 
        "storageProfile": { 
            "imageReference": { 
                "publisher": "MicrosoftWindowsServer", 
                "offer": "WindowsServer", 
                "sku": "2019-Datacenter", 
                "version": "latest", 
                "exactVersion": "17763.3124.2111130129" 
            }, 
            "osDisk": { 
                "osType": "Windows", 
                "name": "OsDisk_1", 
                "createOption": "FromImage", 
                "caching": "ReadWrite", 
                "managedDisk": { 
                    "storageAccountType": "Premium_LRS", 
                    "id": "/subscriptions/subID/resourceGroups/resourcegroup/providers/Microsoft.Compute/disks/OsDisk_1" 
                }, 
                "deleteOption": "Detach", 
                "diskSizeGB": 127 
            }, 
            "dataDisks": [ 
                { 
                    "lun": 0, 
                    "name": "DataDisk_0", 
                    "createOption": "Attach", 
                    "caching": "None", 
                    "writeAcceleratorEnabled": false, 
                    "managedDisk": { 
                        "storageAccountType": "Premium_LRS", 
                        "id": "/subscriptions/subID/resourceGroups/resourcegroup/providers/Microsoft.Compute/disks/DataDisk_0" 
                    }, 
                    "deleteOption": "Detach", 
                    "diskSizeGB": 1024, 
                    "toBeDetached": false 
                }, 
                { 
                    "lun": 1, 
                    "name": "DataDisk_1", 
                    "createOption": "Attach", 
                    "caching": "None", 
                    "writeAcceleratorEnabled": false, 
                    "managedDisk": { 
                        "storageAccountType": "Premium_LRS", 
                        "id": "/subscriptions/subID/resourceGroups/resourcegroup/providers/Microsoft.Compute/disks/DataDisk_1" 
                    }, 
                    "deleteOption": "Detach", 
                    "diskSizeGB": 1024, 
                    "toBeDetached": false 
                } 
            ] 
        }, 
        "osProfile": { 
            "computerName": "testvm", 
            "adminUsername": "azureuser", 
            "windowsConfiguration": { 
                "provisionVMAgent": true, 
                "enableAutomaticUpdates": true, 
                "patchSettings": { 
                    "patchMode": "AutomaticByOS", 
                    "assessmentMode": "ImageDefault", 
                    "enableHotpatching": false 
                } 
            }, 
            "secrets": [], 
            "allowExtensionOperations": true, 
            "requireGuestProvisionSignal": true 
        }, 
        "networkProfile": { 
            "networkInterfaces": [ 
                { 
                    "id": "/subscriptions/subID/resourceGroups/resourcegroup/providers/Microsoft.Network/networkInterfaces/nic336" 
                , 
                   "properties": { 
                   "deleteOption": "Detach" 
} 
} 
            ] 
        } 
} 
}

Rename Azure VM

You have a couple of options to run the script, you can either use the Azure Cloud Shell, Visual Studio (VS) Code, or the new Windows Terminal. The Script works with PowerShell 5.1 or PowerShell 7.3.x (core) with the Az module installed.

You can use the following PowerShell command to install and update the “Az module” locally on your machine.

# Make sure you have the latest version of PowerShellGet installed
Install-Module -Name PowerShellGet -Force

 # Install and update to the latest Az PowerShell module
Install-Module -Name Az -AllowClobber -Force

.EXAMPLE

.\Rename-AzVM.ps1 -resourceGroup [ResourceGroupName] -OldVMName [VMName] -NewVMName [VMName] -Verbose

This example will rename an existing Azure virtual machine, you need to specify the Resource Group name, the old VM name, and the new VM name. The script will preserve the old VM settings and resources, and then apply them to the new Azure VM whether it’s Windows or Linux.

Please note that the tool below was updated to work for virtual machines with Azure Managed Disks and UnManaged Disks. If you still have very old VMs with UnManaged Disks, we highly recommend converting them to unmanaged disks as described in this article.

Here is an example of the output once you run this tool:

PowerShell Code

The complete script is detailed below to automate the entire VM rename process:

<#
.SYNOPSIS
Rename Azure VM.

.DESCRIPTION
Rename an Azure virtual machine for Linux and Windows OS.

.NOTES
File Name : Rename-AzVM.ps1
Author    : Microsoft MVP/MCT - Charbel Nemnom
Version   : 2.4
Date      : 29-August-2021
Update    : 25-July-2024
Requires  : PowerShell 5.1 or PowerShell 7.2.x (Core)
Module    : Az Module
OS        : Windows or Linux VMs
Support   : Managed and UnManaged Disks   

.LINK
To provide feedback or for further assistance please visit: https://charbelnemnom.com

.EXAMPLE
.\Rename-AzVM.ps1 -resourceGroup [ResourceGroupName] -OldVMName [VMName] -NewVMName [VMName] -Verbose
This example will rename an existing Azure virtual machine, you need to specify the Resource Group name, old VM name and the new VM name.
The script will preserve the old VM settings and resources, and then apply them to the new Azure VM.
#>

[CmdletBinding()]
Param (
    [Parameter(Position = 0, Mandatory = $true, HelpMessage = 'Enter the Resource Group of the Azure VM')]
    [Alias('rg')]
    [String]$resourceGroup,

    [Parameter(Position = 1, Mandatory = $True, HelpMessage = 'Enter the existing Azure VM name')]
    [Alias('OldVM')]
    [String]$OldVMName,

    [Parameter(Position = 2, Mandatory = $true, HelpMessage = 'Enter the desired new Azure VM name')]
    [Alias('NewVM')]
    [String]$NewVMName
)

#! Check Azure Connection
Try {
    Write-Verbose "Connecting to Azure Cloud..."
    Connect-AzAccount -ErrorAction Stop | Out-Null
}
Catch {
    Write-Warning "Cannot connect to Azure Cloud. Please check your credentials. Exiting!"
    Break
}

$azSubs = Get-AzSubscription
$azSub = 0
Do {
    Write-Verbose "Set Azure Subscription context to: $($azSubs[$azSub].Name)"
    Set-AzContext -Subscription $azSubs[$azSub] | Out-Null
    $VMInfo = Get-AzVM | Where-Object { $_.Name -eq $OldVMName -and $_.ResourceGroupName -eq $resourceGroup }
    if ($VMInfo) {
        #! Get original Azure VM properties and export it
        Try {
            Write-Verbose "Get original Azure VM properties and export its configuration to $(get-location)"
            Get-AzVM -ResourceGroupName $resourceGroup -Name $OldVMName -ErrorAction Stop | Export-Clixml .\AzVM_Backup.xml -Depth 5
        }
        Catch {
            Write-Warning "Cannot Export Azure VM $OldVMName to $(get-location) - Exiting!"
            Break
        }
    }
    $azSub++
} while ((!$VMInfo) -and ($azSub -lt $azSubs.count))

If (!$VMInfo) {
    Write-Warning "The Azure VM $OldVMName does not exist. Please check your virtual machine name!"
    Exit
}

#! Import Azure VM settings from backup XML and store it in a variable
Write-Verbose "Importing the old Azure VM properties..."
$oldVM = Import-Clixml .\AzVM_Backup.xml

#! Check if the delete behavior on existing VM is set to "Delete"
If ($oldVM.StorageProfile.OsDisk.DeleteOption -eq "Delete") {
    Write-Warning "The Azure VM $($OldVMName) has the OS Disk Deletion set to [Delete]. Please update it to [Detach] before you continue renaming your virtual machine. Exiting!"
    Exit
}

If ($oldVM.StorageProfile.DataDisks.DeleteOption -contains "Delete") {
    Write-Warning "The Azure VM $($OldVMName) has the Data Disk Deletion set to [Delete]. Please update it to [Detach] before you continue renaming your virtual machine. Exiting!"
    Exit
}

If ($oldVM.NetworkProfile.NetworkInterfaces.DeleteOption -eq "Delete") {
    Write-Warning "The Azure VM $($OldVMName) has the NIC Interface Deletion set to [Delete]. Please update it to [Detach] before you continue renaming your virtual machine. Exiting!"
    Exit 
}

#! Delete the Old Azure VM
Write-Verbose "Deleting the old Azure VM and keeping the other resources intact..."
Remove-AzVM -ResourceGroupName $oldVM.ResourceGroupName -Name $oldVM.Name -Force

#! Creating the new Azure VM configuration
Write-Verbose "Creating the new Azure VM configuration..."
$newVM = New-AzVMConfig -VMName $NewVMName -VMSize $oldVM.HardwareProfile.VmSize -Tags $oldVM.Tags

#! Attaching the OS Managed Disk of the old VM to the new Azure VM (Windows/Linux)
if ($oldVM.StorageProfile.OsDisk.vhd -eq $null -and $oldvm.StorageProfile.osdisk.ostype.value -eq "Windows") {
    Write-Verbose "Attaching the Windows OS Managed Disk of the old VM to the new Azure VM..."
    Set-AzVMOSDisk -VM $newVM -CreateOption Attach -ManagedDiskId $oldVM.StorageProfile.OsDisk.ManagedDisk.Id -Name $oldVM.StorageProfile.OsDisk.Name -Windows -Caching $oldVM.StorageProfile.OsDisk.Caching.Value | Out-Null
}
elseif ($oldVM.StorageProfile.OsDisk.vhd -eq $null -and $oldvm.StorageProfile.osdisk.ostype.value -eq "Linux") {
    Write-Verbose "Attaching the Linux OS Managed Disk of the old VM to the new Azure VM..."
    Set-AzVMOSDisk -VM $newVM -CreateOption Attach -ManagedDiskId $oldVM.StorageProfile.OsDisk.ManagedDisk.Id -Name $oldVM.StorageProfile.OsDisk.Name -Linux -Caching $oldVM.StorageProfile.OsDisk.Caching.Value | Out-Null
}

#! Attaching the OS UnManaged Disk of the old VM to the new Azure VM (Windows/Linux)
if ($oldVM.StorageProfile.OsDisk.vhd -ne $null -and $oldvm.StorageProfile.osdisk.ostype.value -eq "Windows") {
    Write-Verbose "Attaching the Windows OS UnManaged Disk of the old VM to the new Azure VM..."
    Set-AzVMOSDisk -VM $newVM -CreateOption Attach -VhdUri $oldVM.StorageProfile.OsDisk.vhd.value -Name $oldVM.StorageProfile.OsDisk.Name -Windows -Caching $oldVM.StorageProfile.OsDisk.Caching.Value | Out-Null
}
elseif ($oldVM.StorageProfile.OsDisk.vhd -ne $null -and $oldvm.StorageProfile.osdisk.ostype.value -eq "Linux") {
    Write-Verbose "Attaching the Linux OS UnManaged Disk of the old VM to the new Azure VM..."
    Set-AzVMOSDisk -VM $newVM -CreateOption Attach -VhdUri $oldVM.StorageProfile.OsDisk.vhd.value -Name $oldVM.StorageProfile.OsDisk.Name -Linux -Caching $oldVM.StorageProfile.OsDisk.Caching.Value | Out-Null
}

# Checking if the old VM is deployed with Trusted Launch enabled
$securityType = Get-AzDisk -Name $oldVM.StorageProfile.OsDisk.Name
Write-Verbose "Checking if the old VM is deployed with Trusted Launch enabled..."
if ($securityType.SecurityProfile.SecurityType -eq "TrustedLaunch") {
    Write-Verbose "Setting the OS Disk Security Profile to [TrustedLaunch] and enable [SecureBoot]"
    $newVM = Set-AzVmSecurityProfile -VM $newVM -SecurityType "TrustedLaunch" 
    $newVM = Set-AzVmUefi -VM $newVM -EnableVtpm $true  -EnableSecureBoot $true 
}

#! Attaching all NICs of the old VM to the new Azure VM
Write-Verbose "Attaching all NICs of the old VM to the new Azure VM..."
$oldVM.NetworkProfile.NetworkInterfaces.Item(0).primary = $true
$oldVM.NetworkProfile.NetworkInterfaces | % { Add-AzVMNetworkInterface -VM $newVM -Id $_.Id } | Out-Null

#! Attaching all Data Disks (if any) of the old VM to the new Azure VM
Write-Verbose "Attaching all Data Disks (if any) of the old VM to the new Azure VM..."
$oldVM.StorageProfile.DataDisks | % { Add-AzVMDataDisk -VM $newVM -Name $_.Name -ManagedDiskId $_.ManagedDisk.Id -Caching $_.Caching -Lun $_.Lun -DiskSizeInGB $_.DiskSizeGB -CreateOption Attach }

#! Creating the new Azure VM
Write-Verbose "Creating the new Azure VM..."
New-AzVM -ResourceGroupName $oldVM.ResourceGroupName -Location $oldVM.Location -VM $newVM

If you look back in the Azure Portal, we can see that the old VM name is renamed successfully.

If you have any feedback or changes that everyone should receive, please feel free to leave a comment below.

That’s it there you have it. Happy Azure VM Renaming!

Summary

In this article, you have learned how to rename an Azure virtual machine using PowerShell. We first back up the VM configuration and export it to an (.XML) file for later reference, then delete a VM, package a new VM configuration, attach all disks and network profiles, and finally create the new VM.

Please note that the PowerShell script outlined above is for a basic VM. There might be other important details that need to be included in the renamed virtual machine. Because some settings can only be set during the creation so these must be carefully considered too before running the script.

A couple of examples where careful planning is required, Availability Set to which the VM can be added only when the VM is created, however, you can change the Availability Set for an Azure VM using Azure PowerShell as described here, another example is if the VM is attached to a load balancer, attached to an Azure Application Gateway, or protected with Azure Backup.

We highly recommend planning carefully before you proceed with the renaming process to increase the chance of success.

__
Thank you for reading my blog.

If you have any questions or feedback, please leave a comment.

-Charbel Nemnom-