Best practice: Use persistent device names on a Linux VM

---

This document describes how to use persistent device naming on your Linux VM.

For VMs that use a Linux operating system, device names, for example /dev/sda, might change after you perform procedures such as the following:

• Starting and stopping a VM
• Detaching and reattaching disks
• Changing machine types

This device name change occurs because device names are assigned from an available range once a VM starts or a device is attached. Detaching a device or stopping the VM frees up the device name. When the device is reattached or the VM restarted a new device name is then assigned from the available range. The Linux kernel does not guarantee device ordering across reboots.

A device name change might cause any applications or scripts that depend on the original device name to not work properly or it might cause the VM to not boot after a restart.

It is recommended that you use persistent device naming when referencing disks and partitions on your Linux VMs to avoid this issue. You can also use symlinks.

Before you begin

• Review device management for your Linux operating system:
  • Using UUIDs with Ubuntu
  • Red Hat Device Management
• If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

  2. Set a default region and zone.

Device naming on Linux VMs

The Linux device names for the disks attached to your VM depend on the interface that you choose when creating the disks. When you use the lsblk operating system command to view your disk devices, it displays the prefix nvme for disks attached with the NVMe interface, and the prefix sd for disks attached with the SCSI interface.

The ordering of the disk numbers or NVMe controllers is not predictable or consistent across VMs restarts. On the first boot, a persistent disk might be nvme0n1 (or sda for SCSI). On the second boot, the device name for the same persistent disk might be nvme2n1 or nvme0n3 (or sdc for SCSI).

When accessing attached disks, you should use the symbolic links created in /dev/disk/by-id/ instead. These names persist across reboots. For more information about symlinks, see Symbolic links for disks attached to a VM.

SCSI device names

The format of a SCSI-attached disk device is sda for the first attached disk. The disk partitions appear as sda1. Each additional disk uses a sequential letter, such as sdb and sdc. When sdz is reached, the next disks added have the names such as sdaa, sdab, and sdac, up to sddx.

NVMe device names

The format of a NVMe-attached disk device in Linux operating systems is nvmenumbernnamespace. The number represents the NVMe disk controller number and namespace is an NVMe namespace ID that is assigned by the NVMe disk controller. For partitions, pn is appended to the device name, where n is a number, starting with 1, that denotes the n^th partition.

The controller number starts at 0. A single NVMe disk attached to your compute instance has a device name of nvme0n1. Most machine types use a single NVMe disk controller. The NVMe device names are then nvme0n1, nvme0n2, nvme0n3, and so on.

Local SSD disks attached to third generation machine series or later instances have a separate NVMe controller for each disk. On these VMs, the Local SSD NVMe-attached device names look like nvme0n1, nvme1n1, and nvme2n1. The number of attached Local SSD disks depends on the machine type of your VM.

Compute instances based on third generation machine series or later use NVMe for both Persistent Disk and Google Cloud Hyperdisk, and also Local SSD disks. Each VM has 1 NVMe controller for Persistent Disk and Hyperdisk and 1 NVMe controller for each Local SSD disk. The Persistent Disk and Hyperdisk NVMe controller has a single NVMe namespace for all attached disks. So, a third generation machine series instance with one Persistent Disk and one Hyperdisk (each with 2 partitions), and 2 unformatted Local SSD disks uses the following device names:

• nvme0n1 - Persistent Disk
• nvme0n1p1
• nvme0n1p2
• nvme0n2 - Hyperdisk
• nvme0n2p1
• nvme0n2p2
• nvme1n1 - first Local SSD
• nvme2n1 - second Local SSD

Use persistent device naming

To configure a persistent device name, you assign a mount point name for the disk device in the fstab file. There are three ways to configure a persistent device name.

• By using a label. This option requires that the file system supports labels and that you add a label to the disk partitions.
• By using a partition or disk UUID. A UUID is generated when a disk is created with a partition table, and the UUID is unique per partition.
• By using a persistent disk ID (/dev/disk/by-id) for Persistent Disk or Google Cloud Hyperdisk, or a symlink, that is based on the disk resource name.

We recommend using the partition UUID or the symlink for Linux VMs.