Azure VM Custom Script Extensions: Post-Boot Automation

What VM extensions are

Azure VM extensions are small agent-managed programs that run inside a VM in response to commands from the Azure control plane. The Azure VM Agent (installed by default on all Azure Marketplace images) listens for extension commands and executes them. Extensions are available for common tasks: running scripts (Custom Script Extension), enrolling in antivirus, deploying monitoring agents, and joining Azure Active Directory.

The Custom Script Extension specifically allows you to point at a script file or specify inline commands, and Azure executes them inside the VM as root (Linux) or SYSTEM (Windows). The script runs once unless you update the extension configuration to trigger a new run.

Running a script on a Linux VM

The simplest usage: run an inline command on an already-provisioned VM.

az vm extension set \
  --resource-group my-rg \
  --vm-name my-vm \
  --name customScript \
  --publisher Microsoft.Azure.Extensions \
  --settings '{"commandToExecute": "apt-get update && apt-get install -y nginx"}'

For longer scripts, store the script in Azure Blob Storage and reference it by URI:

# Upload script to blob storage first
az storage blob upload \
  --account-name mystorageaccount \
  --container-name scripts \
  --name setup.sh \
  --file ./setup.sh

# Run the script on the VM
az vm extension set \
  --resource-group my-rg \
  --vm-name my-vm \
  --name customScript \
  --publisher Microsoft.Azure.Extensions \
  --settings '{
    "fileUris": ["https://mystorageaccount.blob.core.windows.net/scripts/setup.sh"],
    "commandToExecute": "bash setup.sh"
  }'

Running a script on a Windows VM

Windows VMs use a different extension name and publisher:

az vm extension set \
  --resource-group my-rg \
  --vm-name my-windows-vm \
  --name CustomScriptExtension \
  --publisher Microsoft.Compute \
  --settings '{
    "fileUris": ["https://mystorageaccount.blob.core.windows.net/scripts/setup.ps1"],
    "commandToExecute": "powershell -ExecutionPolicy Unrestricted -File setup.ps1"
  }'

PowerShell scripts on Windows have the same pattern: reference a file in Blob Storage, execute it with PowerShell. For simple inline commands, use commandToExecute directly with the PowerShell invocation inline.

Checking extension status and logs

After running an extension, check whether it succeeded:

# Check extension status on the VM
az vm extension list \
  --resource-group my-rg \
  --vm-name my-vm \
  --output table

# Get detailed status including error messages
az vm extension show \
  --resource-group my-rg \
  --vm-name my-vm \
  --name customScript

For deeper diagnostics, connect to the VM and check the log file. On Linux:

# Script output and error logs
cat /var/log/azure/custom-script/handler.log

# See the actual stdout/stderr from the last script run
ls /var/lib/waagent/custom-script/download/
cat /var/lib/waagent/custom-script/download/0/stdout
cat /var/lib/waagent/custom-script/download/0/stderr

Running a script at VM creation time

You can attach a Custom Script Extension at the same time you create the VM, so the script runs immediately after the OS boots:

az vm create \
  --resource-group my-rg \
  --name my-vm \
  --image Ubuntu2204 \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --custom-data cloud-init.yaml

Note the shift to —custom-data here: for at-creation bootstrapping on Linux, cloud-init is generally preferred over Custom Script Extensions. Cloud-init is a widely supported Linux initialisation system that runs before the Azure agent processes extensions, supports multi-step configurations, and has better logging. Custom Script Extension is more flexible for ad hoc post-boot automation and works equally well on Linux and Windows.

When to use Custom Script Extension vs alternatives