VM Run Command and Invoke Script

VM Run Command is an Azure feature that enables you to remotely execute scripts on an Azure virtual machine (VM) using the VM agent (either the Windows Guest Agent or Linux Agent). It was introduced to solve a common operational problem: what do you do when a VM becomes unreachable via RDP or SSH due to a misconfigured firewall, network security group (NSG), or broken networking? Traditional troubleshooting requires either console access (which Azure does not provide) or out-of-band management (like Azure Serial Console, which requires boot diagnostics). Run Command fills this gap by leveraging the VM agent's outbound communication channel to Azure management endpoints.

The VM agent on Windows (WindowsAzureGuestAgent) or Linux (waagent) periodically polls Azure Storage for pending commands. When you invoke a Run Command, Azure writes the script to a blob in a hidden storage container associated with the VM, and the agent downloads and executes it. The output is then uploaded back to Azure, where you can retrieve it. This entire process uses only outbound HTTPS from the VM to Azure, so it works even if the VM has no inbound ports open or if the NSG blocks all inbound traffic.

The mechanism is as follows:

Key details:

Azure CLI

# Run an inline script on a Windows VM
az vm run-command invoke -g MyResourceGroup -n MyWinVM --command-id RunPowerShellScript --scripts "Get-Process | Out-String"

# Run an inline script on a Linux VM
az vm run-command invoke -g MyResourceGroup -n MyLinuxVM --command-id RunShellScript --scripts "uptime && df -h"

# Run a script file
az vm run-command invoke -g MyResourceGroup -n MyVM --command-id RunShellScript --scripts @myscript.sh

# Pass parameters
az vm run-command invoke -g MyResourceGroup -n MyVM --command-id RunShellScript --scripts "echo Hello {0}" --parameters "arg1=World"

PowerShell

# Run inline script on Windows VM
Invoke-AzVMRunCommand -ResourceGroupName MyResourceGroup -VMName MyWinVM -CommandId RunPowerShellScript -ScriptPath "C:\scripts\test.ps1"

# Run inline script on Linux VM
Invoke-AzVMRunCommand -ResourceGroupName MyResourceGroup -VMName MyLinuxVM -CommandId RunShellScript -ScriptPath "/home/azureuser/script.sh"

REST API

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/runCommand?api-version=2023-03-01
{
  "commandId": "RunPowerShellScript",
  "script": ["Get-Process"]
}

There are two built-in command IDs: RunPowerShellScript for Windows and RunShellScript for Linux. You must use the correct one for the target OS. Using RunPowerShellScript on a Linux VM will fail because the agent does not have a PowerShell executable. The exam may present a scenario where you need to choose the correct command ID.

A common enterprise scenario: a security administrator accidentally applies an NSG that blocks all inbound RDP (port 3389) and SSH (port 22) traffic to a critical VM. The VM is still running and has outbound internet access. The administrator cannot RDP/SSH to fix the NSG. Using Run Command, the administrator runs a PowerShell script to modify the NSG rules via Azure PowerShell or CLI (since the VM has outbound access, it can call Azure management APIs). For example:

Invoke-AzVMRunCommand -ResourceGroupName 'RG1' -VMName 'VM1' -CommandId RunPowerShellScript -ScriptPath 'C:\scripts\fix-nsg.ps1'

Where fix-nsg.ps1 contains Azure PowerShell commands to update the NSG. This avoids the need for any inbound connectivity. In production, this is often used in conjunction with Azure Automation or as a last-resort recovery method.

A DevOps team manages hundreds of VMs. One VM becomes unresponsive but is still running. The team needs to collect event logs and performance counters to diagnose the issue. Without Run Command, they would need to attach a diagnostic disk or use Serial Console (which requires boot diagnostics). With Run Command, they can execute a script that exports logs to a blob storage account:

az vm run-command invoke -g MyRG -n MyVM --command-id RunShellScript --scripts "dmesg > /tmp/dmesg.log && az storage blob upload -f /tmp/dmesg.log -c logs --account-name mystorageaccount"

This script uses the Azure CLI (installed on the VM) to upload logs. In production, the VM must have the Azure CLI installed and authenticated (e.g., using managed identity). The exam may test that Run Command can run any command the OS supports, including Azure CLI or PowerShell cmdlets, provided the necessary tools are installed.

A security vulnerability requires an immediate registry change on all Windows VMs in a region. Instead of RDPing into each VM, the security team runs a Run Command script against all VMs using a loop in Azure CLI:

for vm in $(az vm list -g MyRG --query "[].name" -o tsv); do
  az vm run-command invoke -g MyRG -n $vm --command-id RunPowerShellScript --scripts "Set-ItemProperty -Path 'HKLM:\Software\MyApp' -Name 'SecurityLevel' -Value 'High'"
done

This scales well but is not fully automated for large fleets (consider Azure Automation or Policy). Common pitfalls: the script runs simultaneously on many VMs, which may cause contention if they share a backend. Also, if the VM agent is not updated, some VMs may fail. In production, always test on a small subset first.