Tutorial: Manage disks with Azure PowerShell

Azure virtual machines (VMs) use disks to store operating systems (OS), applications, and data. When you create a VM, it's important to choose an appropriate disk size and configuration for the expected workload.

This tutorial covers deployment and management of VM disks. In this tutorial, you learn how to:

  • Create, attach, and initialize a data disk
  • Verify a disk's status
  • Initialize a disk
  • Expand and upgrade a disk
  • Detach and delete a disk

Prerequisites

You must have an Azure account with an active subscription. If you don't have an Azure subscription, create a free account before you begin.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

Create a VM

The exercises in this tutorial require a VM. Follow the steps in this section to create one.

Before you begin, find the $azRegion variable located in the first line of sample code and update the value to reflect your desired region. For example, to specify the Central US region, use $azRegion = "Central US". Next, use the code to deploy a VM within a new resource group. You're prompted for username and password values for the VM's local administrator account.

$azRegion = "[Your Region]"
$azResourceGroup = "myDemoResourceGroup"
$azVMName = "myDemoVM"
$azDataDiskName = "myDemoDataDisk"

New-AzVm `
    -Location $azRegion `
    -ResourceGroupName $azResourceGroup `
    -Name $azVMName `
    -Size "Standard_D2s_v3" `
    -VirtualNetworkName "myDemoVnet" `
    -SubnetName "myDemoSubnet" `
    -SecurityGroupName "myDemoNetworkSecurityGroup" `
    -PublicIpAddressName "myDemoPublicIpAddress"

The output confirms the VM's successful creation.

ResourceGroupName        : myDemoResourceGroup
Id                       : /subscriptions/{GUID}/resourceGroups/myDemoResourceGroup/providers/Microsoft.Compute/virtualMachines/myDemoTestVM
VmId                     : [{GUID}]
Name                     : myDemoVM
Type                     : Microsoft.Compute/virtualMachines
Location                 : centralus
Tags                     : {}
HardwareProfile          : {VmSize}
NetworkProfile           : {NetworkInterfaces}
OSProfile                : {ComputerName, AdminUsername, WindowsConfiguration, AllowExtensionOperations, RequireGuestProvisionSignal}
ProvisioningState        : Succeeded
StorageProfile           : {ImageReference, OsDisk, DataDisks}
FullyQualifiedDomainName : mydemovm-abc123.Central US.cloudapp.azure.com

The VM is provisioned, and two disks are automatically created and attached.

  • An operating system disk, which hosts the virtual machine's operating system.
  • A temporary disk, which is primarily used for operations such as temporary data processing.

Add a data disk

We recommend that you separate application and user data from OS-related data when possible. If you need to store user or application data on your VM, you'll typically create and attach additional data disks.

Follow the steps in this section to create, attach, and initialize a data disk on the VM.

Create the data disk

This section guides you through the creation of a data disk.

  1. Before a data disk can be created, you must first create a disk object. The following code sample uses the New-AzDiskConfig cmdlet to configure a disk object.

    $diskConfig = New-AzDiskConfig `
        -Location $azRegion `
        -CreateOption Empty `
        -DiskSizeGB 128 `
        -SkuName "Standard_LRS"
    
  2. After the disk object is created, use the New-AzDisk cmdlet to provision a data disk.

    $dataDisk = New-AzDisk `
        -ResourceGroupName $azResourceGroup `
        -DiskName $azDataDiskName `
        -Disk $diskConfig
    

    You can use the Get-AzDisk cmdlet to verify that the disk was created.

    Get-AzDisk `
        -ResourceGroupName $azResourceGroup `
        -DiskName $azDataDiskName
    

    In this example, the output confirms that the disk was created. The DiskState and ManagedBy property values confirm that the disk is not yet attached.

    ResourceGroupName            : myDemoResourceGroup
    ManagedBy                    :
    ManagedByExtended            : {}
    OsType                       :
    DiskSizeGB                   : 128
    DiskSizeBytes                : 137438953472
    ProvisioningState            : Succeeded
    DiskIOPSReadWrite            : 500
    DiskMBpsReadWrite            : 60
    DiskState                    : Unattached
    Name                         : myDemoDataDisk
    

Attach the data disk

A data disk must be attached to a VM before the VM can access it. Complete the steps in this section to create a reference for the VM, connect the disk, and update the VM's configuration.

  1. Get the VM to which you'll attach the data disk. The following sample code uses the Get-AzVM cmdlet to create a reference to the VM.

    $vm = Get-AzVM `
        -ResourceGroupName $azResourceGroup `
        -Name $azVMName
    
  2. Next, attach the data disk to the VM's configuration with the Add-AzVMDataDisk cmdlet.

    $vm = Add-AzVMDataDisk `
        -VM $vm `
        -Name $azDataDiskName `
        -CreateOption Attach `
        -ManagedDiskId $dataDisk.Id `
        -Lun 1
    
  3. Finally, update the VM's configuration with the Update-AzVM cmdlet.

    Update-AzVM `
        -ResourceGroupName $azResourceGroup `
        -VM $vm
    

    After a brief pause, the output confirms a successful attachment.

    RequestId IsSuccessStatusCode StatusCode ReasonPhrase
    --------- ------------------- ---------- ------------
                             True         OK OK
    

Initialize the data disk

After a data disk is attached to the VM, the OS needs to be configured to use the disk. The following section provides guidance on how to connect to the remote VM and configure the first disk added.

  1. Sign in to the Azure portal.

  2. Locate the VM to which you've attached the data disk. Create a Remote Desktop Protocol (RDP) connection and sign in as the local administrator.

  3. After you establish an RDP connection to the remote VM, select the Windows Start menu. Enter PowerShell in the search box and select Windows PowerShell to open a PowerShell window.

    Image of a remote desktop connection window.

  4. In the open PowerShell window, run the following script.

    Get-Disk | Where PartitionStyle -eq 'raw' |
        Initialize-Disk -PartitionStyle MBR -PassThru |
        New-Partition -AssignDriveLetter -UseMaximumSize |
        Format-Volume -FileSystem NTFS -NewFileSystemLabel "myDemoDataDisk" -Confirm:$false
    

    The output confirms a successful initialization.

    DriveLetter FileSystemLabel FileSystem DriveType HealthStatus OperationalStatus SizeRemaining   Size
    ----------- --------------- ---------- --------- ------------ ----------------- -------------   ----
    F           myDemoDataDisk  NTFS       Fixed     Healthy      OK                    127.89 GB 128 GB
    

Expand a disk

You can expand Azure disks to provide extra storage capacity when your VM is low on available disk space.

Some scenarios require data to be stored on the OS disk. For example, you may be required to support legacy applications that install components on the OS drive. You may also have the need to migrate an on-premises physical PC or VM with a larger OS drive. In such cases, it may become necessary to expand a VM's OS disk.

Shrinking an existing disk isn’t supported, and can potentially result in data loss.

Update the disk's size

Follow the steps below to resize either the OS disk or a data disk.

  1. Select the VM that contains the disk that you'll resize with the Get-AzVM cmdlet.

     $vm = Get-AzVM `
       -ResourceGroupName $azResourceGroup `
       -Name $azVMName
    
  2. Before you can resize a VM's disk, you must stop the VM. Use the Stop-AzVM cmdlet to stop the VM. You'll be prompted for confirmation.

    Important

    Before you initiate a VM shutdown, always confirm that there are no important resources or data that could be lost.

    Stop-AzVM `
        -ResourceGroupName $azResourceGroup `
        -Name $azVMName
    

    After a short pause, the output confirms that the machine is successfully stopped.

    OperationId : abcd1234-ab12-cd34-123456abcdef
    Status      : Succeeded
    StartTime   : 9/13/2021 7:10:23 PM
    EndTime     : 9/13/2021 7:11:12 PM
    Error       :
    
  3. After the VM is stopped, get a reference to either the OS or data disk attached to the VM with the Get-AzDisk cmdlet.

    The following example selects the VM's OS disk.

    $disk= Get-AzDisk `
        -ResourceGroupName $azResourceGroup `
        -DiskName $vm.StorageProfile.OsDisk.Name
    

    The following example selects the VM's first data disk.

        $disk= Get-AzDisk `
            -ResourceGroupName $azResourceGroup `
            -DiskName $vm.StorageProfile.DataDisks[0].Name
    
  4. Now that you have a reference to the disk, set the size of the disk to 250 GiB.

    Important

    The new size should be greater than the existing disk size. The maximum allowed is 4,095 GiB for OS disks.

    $disk.DiskSizeGB = 250
    
  5. Next, update the disk image with the Update-AzDisk cmdlet.

    Update-AzDisk `
        -ResourceGroupName $azResourceGroup `
        -Disk $disk -DiskName $disk.Name
    

    The disk image is updated, and the output confirms the disk's new size.

    ResourceGroupName            : myDemoResourceGroup
    ManagedBy                    : /subscriptions/{GUID}/resourceGroups/myDemoResourceGroup/providers/Microsoft.Compute/virtualMachines/myDemoVM
    Sku                          : Microsoft.Azure.Management.Compute.Models.DiskSku
    TimeCreated                  : 9/135/2021 6:41:10 PM
    CreationData                 : Microsoft.Azure.Management.Compute.Models.CreationData
    DiskSizeGB                   : 250
    DiskSizeBytes                : 268435456000
    UniqueId                     : {GUID}
    ProvisioningState            : Succeeded
    DiskIOPSReadWrite            : 500
    DiskMBpsReadWrite            : 60
    DiskState                    : Reserved
    Encryption                   : Microsoft.Azure.Management.Compute.Models.Encryption
    Id                           : /subscriptions/{GUID}/resourceGroups/myDemoResourceGroup/providers/Microsoft.Compute/disks/myDemoDataDisk
    Name                         : myDemoDataDisk
    Type                         : Microsoft.Compute/disks
    Location                     : centralus
    
    
  6. Finally, restart the VM with the Start-AzVM cmdlet.

    Start-AzVM `
        -ResourceGroupName $azResourceGroup `
        -Name $azVMName
    

    After a short pause, the output confirms that the machine is successfully started.

    OperationId : abcd1234-ab12-cd34-123456abcdef
    Status      : Succeeded
    StartTime   : 9/13/2021 7:44:54 PM
    EndTime     : 9/13/2021 7:45:15 PM
    Error       :
    

Expand the disk volume in the OS

Before you can take advantage of the new disk size, you need to expand the volume within the OS. Follow the steps below to expand the disk volume and take advantage of the new disk size.

  1. Sign in to the Azure portal.

  2. Locate the VM to which you've attached the data disk. Create a Remote Desktop Protocol (RDP) connection and sign in. If you no longer have access to an administrative account, create a credential object for a specified user name and password with the Get-Credential cmdlet.

  3. After you've established an RDP connection to the remote VM, select the Windows Start menu. Enter PowerShell in the search box and select Windows PowerShell to open a PowerShell window.

    Image of a remote desktop connection window.

  4. Open PowerShell and run the following script. Change the value of the -DriveLetter variable as appropriate. For example, to resize the partition on the F: drive, use $driveLetter = "F".

    $driveLetter = "[Drive Letter]" `
    $size = (Get-PartitionSupportedSize -DriveLetter $driveLetter) `
    Resize-Partition `
        -DriveLetter $driveLetter `
        -Size $size.SizeMax
    
  5. Minimize the RDP window and switch back to Azure Cloud Shell. Use the Get-AzDisk cmdlet to verify that the disk was resized successfully.

    Get-AzDisk `
        -ResourceGroupName $azResourceGroup | Out-Host -Paging
    

Upgrade a disk

There are several ways to respond to changes in your organization's workloads. For example, you may choose to upgrade a standard HDD to a premium SSD to handle increased demand.

Follow the steps in this section to upgrade a managed disk from standard to premium.

  1. Select the VM that contains the disk that you'll upgrade with the Get-AzVM cmdlet.

     $vm = Get-AzVM `
       -ResourceGroupName $azResourceGroup `
       -Name $azVMName
    
  2. Before you can upgrade a VM's disk, you must stop the VM. Use the Stop-AzVM cmdlet to stop the VM. You'll be prompted for confirmation.

    Important

    Before you initiate a VM shutdown, always confirm that there are no important resources or data that could be lost.

    Stop-AzVM `
        -ResourceGroupName $azResourceGroup `
        -Name $azVMName
    

    After a short pause, the output confirms that the machine is successfully stopped.

    OperationId : abcd1234-ab12-cd34-123456abcdef
    Status      : Succeeded
    StartTime   : 9/13/2021 7:10:23 PM
    EndTime     : 9/13/2021 7:11:12 PM
    Error       :
    
  3. After the VM is stopped, get a reference to either the OS or data disk attached to the VM with the Get-AzDisk cmdlet.

    The following example selects the VM's OS disk.

    $disk= Get-AzDisk `
        -ResourceGroupName $azResourceGroup `
        -DiskName $vm.StorageProfile.OsDisk.Name
    

    The following example selects the VM's first data disk.

        $disk= Get-AzDisk `
            -ResourceGroupName $azResourceGroup `
            -DiskName $vm.StorageProfile.DataDisks[0].Name
    
  4. Now that you have a reference to the disk, set the disk's SKU to Premium_LRS.

    $disk.Sku = [Microsoft.Azure.Management.Compute.Models.DiskSku]::new('Premium_LRS')
    
  5. Next, update the disk image with the Update-AzDisk cmdlet.

    Update-AzDisk `
        -ResourceGroupName $azResourceGroup `
        -Disk $disk -DiskName $disk.Name
    

    The disk image is updated. Use the following example code to validate that the disk's SKU has been upgraded.

    $disk.Sku.Name
    

    The output confirms the disk's new SKU.

    Premium_LRS
    
  6. Finally, restart the VM with the Start-AzVM cmdlet.

    Start-AzVM `
        -ResourceGroupName $azResourceGroup `
        -Name $azVMName
    

    After a short pause, the output confirms that the machine is successfully started.

    OperationId : abcd1234-ab12-cd34-123456abcdef
    Status      : Succeeded
    StartTime   : 9/13/2021 7:44:54 PM
    EndTime     : 9/13/2021 7:45:15 PM
    Error       :
    

Detach a data disk

You can detach a data disk from a VM when you want to attach it to a different VM, or when it's no longer needed. By default, detached disks are not deleted to prevent unintentional data loss. A detached disk will continue to incur storage charges until it's deleted.

  1. First, select the VM to which the disk is attached with the Get-AzVM cmdlet.

    $vm = Get-AzVM `
       -ResourceGroupName $azResourceGroup `
       -Name $azVMName
    
  2. Select the disk you want to remove with the Get-AzDisk cmdlet.

    $vm = Get-AzVM `
      -ResourceGroupName $azResourceGroup `
      -Name $azVMName
    
  3. Next, detach the disk from the VM with the Remove-AzVMDataDisk cmdlet.

    Remove-AzVMDataDisk `
        -VM $vm `
        -Name $azDataDiskName
    
  4. Update the state of the VM with the Update-AzVM cmdlet to remove the data disk.

    Update-AzVM `
        -ResourceGroupName $azResourceGroup `
        -VM $vm
    

    After a short pause, the output confirms that the VM is successfully updated.

    RequestId IsSuccessStatusCode StatusCode ReasonPhrase
    --------- ------------------- ---------- ------------
                             True         OK OK
    

Delete a data disk

When you delete a VM, data disks attached to the VM remain provisioned and continue to incur charges until they're deleted. This default behavior helps prevent data loss caused by unintentional deletion.

You can use the following sample PowerShell script to delete unattached disks. The retrieval of disks is limited to the myDemoResourceGroup because the -ResourceGroupName switch is used with the Get-AzDisk cmdlet.

# Get all disks in resource group $azResourceGroup
$allDisks = Get-AzDisk -ResourceGroupName $azResourceGroup

# Determine the number of disks in the collection
if($allDisks.Count -ne 0) {

    Write-Host "Found $($allDisks.Count) disks."

    # Iterate through the collection
    foreach ($disk in $allDisks) {

        # Use the disk's "ManagedBy" property to determine if it is unattached
        if($disk.ManagedBy -eq $null) {

            # Confirm that the disk can be deleted
            Write-Host "Deleting unattached disk $($disk.Name)."
            $confirm = Read-Host "Continue? (Y/N)"
            if ($confirm.ToUpper() -ne 'Y') { break }
            else {

                # Delete the disk
                $disk | Remove-AzDisk -Force 
                Write-Host "Unattached disk $($disk.Name) deleted."
            }
        }
    }
}

The unattached data disk is deleted as shown by the output.

Name      : abcd1234-ab12-cd34-ef56-abcdef123456
StartTime : 9/13/2021 10:14:05 AM
EndTime   : 9/13/2021 10:14:35 AM
Status    : Succeeded
Error     :

Clean up resources

When no longer needed, delete the resource group, VM, and all related resources. You can use the following sample PowerShell script to delete the resource group created earlier in this tutorial.

Caution

Use caution when deleting a resource group. To avoid the loss of important data, always confirm that there are no important resources or data contained within the resource group before it is deleted.

    Remove-AzResourceGroup -Name $azResourceGroup

You're prompted for confirmation. After a short pause, the True response confirms that the myDemoResourceGroup is successfully deleted.

Confirm
Are you sure you want to remove resource group 'myDemoResourceGroup'
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): Y
True

Next steps

In this tutorial, you learned how to:

  • Create, attach, and initialize a data disk
  • Verify a disk's status
  • Initialize a disk
  • Expand and upgrade a disk
  • Detach and delete a disk

Advance to the next tutorial to learn how to automate VM configuration.