Edit

Add a disk to a Linux VM

  • Article

Applies to: ✔️ Linux VMs ✔️ Flexible scale sets

This article shows you how to attach a persistent disk to your VM so that you can preserve your data - even if your VM is reprovisioned due to maintenance or resizing.

Attach a new disk to a VM

If you want to add a new, empty data disk on your VM, use the az vm disk attach command with the --new parameter. If your VM is in an Availability Zone, the disk is automatically created in the same zone as the VM. For more information, see Overview of Availability Zones. The following example creates a disk named myDataDisk that is 50 Gb in size:

az vm disk attach \
   -g myResourceGroup \
   --vm-name myVM \
   --name myDataDisk \
   --new \
   --size-gb 50

Lower latency

In select regions, the disk attach latency has been reduced, so you'll see an improvement of up to 15%. This is useful if you have planned/unplanned failovers between VMs, you're scaling your workload, or are running a high scale stateful workload such as Azure Kubernetes Service. However, this improvement is limited to the explicit disk attach command, az vm disk attach. You won't see the performance improvement if you call a command that may implicitly perform an attach, like az vm update. You don't need to take any action other than calling the explicit attach command to see this improvement.

Lower latency is currently available in every public region except for:

  • Canada Central
  • Central US
  • East US
  • East US 2
  • South Central US
  • West US 2
  • Germany North
  • Jio India West
  • North Europe
  • West Europe

Attach an existing disk

To attach an existing disk, find the disk ID and pass the ID to the az vm disk attach command. The following example queries for a disk named myDataDisk in myResourceGroup, then attaches it to the VM named myVM:

diskId=$(az disk show -g myResourceGroup -n myDataDisk --query 'id' -o tsv)

az vm disk attach -g myResourceGroup --vm-name myVM --name $diskId

Format and mount the disk

To partition, format, and mount your new disk so your Linux VM can use it, SSH into your VM. For more information, see How to use SSH with Linux on Azure. The following example connects to a VM with the public IP address of 10.123.123.25 with the username azureuser:

ssh azureuser@10.123.123.25

Find the disk

Once you connect to your VM, find the disk. In this example, we're using lsblk to list the disks.

lsblk -o NAME,HCTL,SIZE,MOUNTPOINT | grep -i "sd"

The output is similar to the following example:

sda     0:0:0:0      30G
├─sda1             29.9G /
├─sda14               4M
└─sda15             106M /boot/efi
sdb     1:0:1:0      14G
└─sdb1               14G /mnt
sdc     3:0:0:0      50G

Here, sdc is the disk that we want, because it's 50G. If you add multiple disks, and aren't sure which disk it's based on size alone, you can go to the VM page in the portal, select Disks, and check the LUN number for the disk under Data disks. Compare the LUN number from the portal to the last number of the HTCL portion of the output, which is the LUN. Another option is to list the contents of the /dev/disk/azure/scsi1 directory:

ls -l /dev/disk/azure/scsi1

The output should be similar to the following example:

lrwxrwxrwx 1 root root 12 Mar 28 19:41 lun0 -> ../../../sdc

Format the disk

Format the disk with parted, if the disk size is two tebibytes (TiB) or larger then you must use GPT partitioning, if it is under 2TiB, then you can use either MBR or GPT partitioning.

Note

It is recommended that you use the latest version parted that is available for your distro. If the disk size is 2 tebibytes (TiB) or larger, you must use GPT partitioning. If disk size is under 2 TiB, then you can use either MBR or GPT partitioning.

The following example uses parted on /dev/sdc, which is where the first data disk will typically be on most VMs. Replace sdc with the correct option for your disk. We're also formatting it using the XFS filesystem.

sudo parted /dev/sdc --script mklabel gpt mkpart xfspart xfs 0% 100%
sudo partprobe /dev/sdc
sudo mkfs.xfs /dev/sdc1

Use the partprobe utility to make sure the kernel is aware of the new partition and filesystem. Failure to use partprobe can cause the blkid or lsblk commands to not return the UUID for the new filesystem immediately.

Mount the disk

Now, create a directory to mount the file system using mkdir. The following example creates a directory at /datadrive:

sudo mkdir /datadrive

Use mount to then mount the filesystem. The following example mounts the /dev/sdc1 partition to the /datadrive mount point:

sudo mount /dev/sdc1 /datadrive

Persist the mount

To ensure that the drive is remounted automatically after a reboot, it must be added to the /etc/fstab file. It's also highly recommended that the UUID (Universally Unique Identifier) is used in /etc/fstab to refer to the drive rather than just the device name (such as, /dev/sdc1). If the OS detects a disk error during boot, using the UUID avoids the incorrect disk being mounted to a given location. Remaining data disks would then be assigned those same device IDs. To find the UUID of the new drive, use the blkid utility:

sudo blkid

The output looks similar to the following example:

/dev/sda1: LABEL="cloudimg-rootfs" UUID="11111111-1b1b-1c1c-1d1d-1e1e1e1e1e1e" TYPE="ext4" PARTUUID="1a1b1c1d-11aa-1234-1a1a1a1a1a1a"
/dev/sda15: LABEL="UEFI" UUID="BCD7-96A6" TYPE="vfat" PARTUUID="1e1g1cg1h-11aa-1234-1u1u1a1a1u1u"
/dev/sdb1: UUID="22222222-2b2b-2c2c-2d2d-2e2e2e2e2e2e" TYPE="ext4" TYPE="ext4" PARTUUID="1a2b3c4d-01"
/dev/sda14: PARTUUID="2e2g2cg2h-11aa-1234-1u1u1a1a1u1u"
/dev/sdc1: UUID="33333333-3b3b-3c3c-3d3d-3e3e3e3e3e3e" TYPE="xfs" PARTLABEL="xfspart" PARTUUID="c1c2c3c4-1234-cdef-asdf3456ghjk"

Note

Improperly editing the /etc/fstab file could result in an unbootable system. If unsure, refer to the distribution's documentation for information on how to properly edit this file. It is also recommended that a backup of the /etc/fstab file is created before editing.

Next, open the /etc/fstab file in a text editor. Add a line to the end of the file, using the UUID value for the /dev/sdc1 device that was created in the previous steps, and the mountpoint of /datadrive. Using the example from this article, the new line would look like the following:

UUID=33333333-3b3b-3c3c-3d3d-3e3e3e3e3e3e   /datadrive   xfs   defaults,nofail   1   2

When you're done editing the file, save and close the editor.

Alternatively, you can run the following command to add the disk to the /etc/fstab file:

echo "UUID=33333333-3b3b-3c3c-3d3d-3e3e3e3e3e3e   /datadrive   xfs   defaults,nofail   1   2" >> /etc/fstab

Note

Later removing a data disk without editing fstab could cause the VM to fail to boot. Most distributions provide either the nofail and/or nobootwait fstab options. These options allow a system to boot even if the disk fails to mount at boot time. Consult your distribution's documentation for more information on these parameters.

The nofail option ensures that the VM starts even if the filesystem is corrupt or the disk does not exist at boot time. Without this option, you may encounter behavior as described in Cannot SSH to Linux VM due to FSTAB errors

The Azure VM Serial Console can be used for console access to your VM if modifying fstab has resulted in a boot failure. More details are available in the Serial Console documentation.

TRIM/UNMAP support for Linux in Azure

Some Linux kernels support TRIM/UNMAP operations to discard unused blocks on the disk. This feature is primarily useful to inform Azure that deleted pages are no longer valid and can be discarded. This feature can save money on disks that are billed based on the amount of consumed storage, such as unmanaged standard disks and disk snapshots.

There are two ways to enable TRIM support in your Linux VM. As usual, consult your distribution for the recommended approach:

  • Use the discard mount option in /etc/fstab, for example:

    UUID=33333333-3b3b-3c3c-3d3d-3e3e3e3e3e3e   /datadrive   xfs   defaults,discard   1   2

  • In some cases, the discard option may have performance implications. Alternatively, you can run the fstrim command manually from the command line, or add it to your crontab to run regularly:

sudo apt install util-linux
sudo fstrim /datadrive

Troubleshooting

When adding data disks to a Linux VM, you may encounter errors if a disk does not exist at LUN 0. If you are adding a disk manually using the az vm disk attach -new command and you specify a LUN (--lun) rather than allowing the Azure platform to determine the appropriate LUN, take care that a disk already exists / will exist at LUN 0.

Consider the following example showing a snippet of the output from lsscsi:

[5:0:0:0]    disk    Msft     Virtual Disk     1.0   /dev/sdc 
[5:0:0:1]    disk    Msft     Virtual Disk     1.0   /dev/sdd

The two data disks exist at LUN 0 and LUN 1 (the first column in the lsscsi output details [host:channel:target:lun]). Both disks should be accessible from within the VM. If you had manually specified the first disk to be added at LUN 1 and the second disk at LUN 2, you may not see the disks correctly from within your VM.

Note

The Azure host value is 5 in these examples, but this may vary depending on the type of storage you select.

This disk behavior is not an Azure problem, but the way in which the Linux kernel follows the SCSI specifications. When the Linux kernel scans the SCSI bus for attached devices, a device must be found at LUN 0 in order for the system to continue scanning for additional devices. As such:

  • Review the output of lsscsi after adding a data disk to verify that you have a disk at LUN 0.
  • If your disk does not show up correctly within your VM, verify a disk exists at LUN 0.

Next steps