azure-ephemeral-disk-setup - Man Page

azure-ephemeral-disk-setup

azure-ephemeral-disk-setup is a systemd-managed one-shot initialization service for Microsoft Azure virtual machines that prepares ephemeral (temporary) disks for use. It supports both NVMe and SCSI ephemeral disks and is capable of aggregating multiple NVMe devices into a RAID-0 array using mdadm.

The service is opt-in and should be configured through /etc/azure-ephemeral-disk-setup.conf. It runs early in the boot process and aims to be idempotent, safe, and compatible with existing tools such as cloud-init and WALinuxAgent.

Logs are printed to stderr and are accessible via journalctl if using the systemd service:

journalctl -u azure-ephemeral-disk-setup.service

Configuration is loaded from:

• /etc/azure-ephemeral-disk-setup.conf (preferred)
• Environment variables (fallback)

The following environment variables are supported:

• AZURE_EPHEMERAL_DISK_SETUP_AGGREGATION Supported values: mdadm, none, auto mdadm: require mdadm and use it for aggregation if multiple disks are found, exiting with error if mdadm is not installed (regardless of number of disks) auto: use mdadm for aggregation only if installed, otherwise fall back to use a single disk none: never aggregate disks, only use one Default: auto
• AZURE_EPHEMERAL_DISK_SETUP_FS_TYPE Supported values: ext4, xfs Default: ext4 (universally available; xfs requires xfsprogs)
• AZURE_EPHEMERAL_DISK_SETUP_MDADM_CHUNK Supported values: Any valid mdadm chunk size Default: 512K (mdadm default)
• AZURE_EPHEMERAL_DISK_SETUP_MDADM_NAME Supported values: Any valid mdadm name Default: azure-ephemeral-md
• AZURE_EPHEMERAL_DISK_SETUP_MOUNT_POINT Supported values: Any valid mount point path Default: /mnt (matches cloud-init default mount point)
• AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE Supported values: true, false Default: false (minimizes risk of conflict with cloud-init and WALinuxAgent)
• AZURE_EPHEMERAL_DISK_SETUP_SYSTEMD_UNIT_TIMEOUT_SECS Supported values: positive integer (>=1) Default: 60
• AZURE_EPHEMERAL_DISK_SETUP_UDEVADM_SETTLE_TIMEOUT_SECS Supported values: positive integation (>=1) Default: 60

The service performs the following steps:

mdadm --create "/dev/md/${AZURE_EPHEMERAL_DISK_SETUP_MDADM_NAME}_0" \
  --level=0 \
  --raid-devices=N \
  --metadata=1.2 \
  --chunk="$AZURE_EPHEMERAL_DISK_SETUP_MDADM_CHUNK" \
  --name="$AZURE_EPHEMERAL_DISK_SETUP_MDADM_NAME" \
  ${DISKS[@]}

This service only formats NVMe disks that are:

• Not mounted
• Unpartitioned
• Unformatted

SCSI resource disks are only reformatted if it:

• Has a single NTFS partition labeled Temporary Storage

• Is empty except for dataloss_warning_readme.txt and System Volume Information

  • To check if disk is empty, this service will attempt to mount the resource disk partition read-only via ntfs3, with fallback to ntfs. If both fail due to lack of driver, it is assumed safe to reformat.

Calls to mkfs and mdadm do not use --force for formatting or mdadm array creation unless reformatting validated NTFS SCSI disk.

• 0 — Success
• 1 — Any error (invalid config, conflicting mount, unsafe disk, etc.)

The following values are used when generating an /etc/fstab entry for the ephemeral disk:

• fs_spec: LABEL=AzureEphmDsk Refers to the disk label. This assumes the script has ownership of the AzureEphmDsk label.
• fs_vfstype: $AZURE_EPHEMERAL_DISK_SETUP_FS_TYPE The filesystem type, determined by configuration (e.g., ext4 or xfs).

• fs_mntops: defaults,nofail,comment=azure-ephemeral-disk-setup

  • defaults: standard mount options
  • nofail: ensures the VM boots even if the ephemeral disk is missing or has been re-allocated
  • comment=azure-ephemeral-disk-setup: tags the entry to show it’s managed by this setup
• fs_freq: 0 Disables dump backups for the filesystem.
• fs_passno: 2 Sets the order for fsck during boot. Non-root filesystems typically use 2.

If AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=false, this service will exit with success if cloud-init is managing the SCSI resource disk at the same mount point. Given the widespread usage of cloud-init for managing the SCSI resource disk, this is the default case.

If AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true, cloud-init management of the resource disk must be disabled. There are two options for disabling cloud-init’s management of SCSI resource disk:

ln -sf /dev/null /etc/udev/rules.d/66-azure-ephemeral.rules

WALinuxAgent must be configured with ResourceDisk.Format=n.

If AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true, this service will exit with error if /etc/waagent.conf sets ResourceDisk.Format=y.

Basic usage:

sudo azure-ephemeral-disk-setup

Enable management of SCSI resource disk:

# /etc/azure-ephemeral-disk-setup.conf
AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true

• /etc/azure-ephemeral-disk-setup.conf — user configuration
• /etc/fstab — mount persistence

DefaultDependencies=no to avoid typical service dependencies as we want to start early.

After:

• cloud-init.service (a.k.a. cloud-init-network.service) allows users to customize service configuration using cloud-config
• local-fs.target ensures local filesystems are mounted (necessary if no cloud-init)

Before:

• cloud-init.target ensures we start before cloud-init completes which services may use to determine if system is fully configured
• walinuxagent.service waagent.service ensures we start prior to walinuxagent and avoid conflicts
• network-online.target to ensure we start before networking is considered online
• sshd.service to ensure we start before sshd starts accepting connections
• systemd-user-sessions.service to ensure we start before user sessions are enabled
• sysinit.target to ensure we run before most services requiring mounts (Debian/Ubuntu only)

All logs are written to stderr and accessible with:

journalctl -u azure-ephemeral-disk-setup.service

mdadm(8), mount(8), cloud-init(8), waagent(8)

Project Home: <https://github.com/Azure/azure-vm-utils>