VM Extensions: Custom Script, DSC, Diagnostics

Azure VM Extensions are small applications that provide post-deployment configuration and automation on Azure virtual machines. They are executed by the Azure VM Agent — a process that runs on every Azure VM (Windows or Linux) and acts as a bridge between the Azure fabric and the guest OS. The agent receives extension commands from the Azure Resource Manager (ARM) and executes them locally.

Extensions are not permanent residents; they are installed, run, and then can be removed. However, some extensions (like Diagnostics) remain installed to collect ongoing data. The key purpose is to avoid manual SSH/RDP sessions for common tasks like running scripts, enforcing configuration, or enabling monitoring.

When you deploy an extension to a VM, the following sequence occurs:

Purpose: Run a script (PowerShell, Bash, or custom) on a VM after deployment. It is ideal for one-time tasks like installing software, joining a domain, or formatting disks.

Key Properties: - Publisher: Microsoft.Compute (for Windows) or Microsoft.Azure.Extensions (for Linux) - Type: CustomScriptExtension (Windows) or CustomScript (Linux) - TypeHandlerVersion: 1.10 (Windows) or 2.1 (Linux) — these are the latest stable versions as of 2025. - Settings: - fileUris: Array of URLs to script files (must be accessible from the VM). - commandToExecute: The command to run (e.g., powershell -ExecutionPolicy Unrestricted -File script.ps1). - timestamp: Optional; forces re-run even if the script hasn't changed (by incrementing the value).

Execution Behavior: - The extension downloads scripts to %SYSTEMROOT%\Temp (Windows) or /var/lib/waagent/custom-script (Linux). - The script runs with SYSTEM (Windows) or root (Linux) privileges. - If the script fails (non-zero exit code), the extension reports Failed status. The VM Agent will not retry automatically — you must re-deploy the extension. - If the script succeeds, the extension reports Succeeded and is considered 'provisioned'. Re-running the same extension with identical settings will not re-execute the script (unless timestamp is changed).

Troubleshooting: - Logs are in C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension (Windows) or /var/log/azure/custom-script (Linux). - Common failures: script timeout (default 90 minutes), network access to fileUris blocked by NSG/firewall, script syntax errors.

Purpose: Enforce a desired state on a VM, ensuring configurations remain consistent over time. DSC is a pull-based or push-based configuration management system (similar to PowerShell DSC on-premises).

Key Properties: - Publisher: Microsoft.Powershell - Type: DSC - TypeHandlerVersion: 2.83 (latest for Windows; Linux DSC is separate but less common on exam) - Settings: - modulesUrl: URL to a .zip file containing the DSC module (compiled MOF or script). - configurationFunction: The function to invoke (e.g., MyConfig.ps1\MyConfig). - properties: Optional hashtable of configuration parameters. - wmfVersion: Specify WMF version (e.g., latest). - privacy: dataCollection (for telemetry).

Execution Behavior: - The extension downloads the module .zip, extracts it, and runs the specified configuration function. - DSC applies the configuration and then monitors the state. By default, the Local Configuration Manager (LCM) on the VM will re-apply the configuration every 15 minutes (the RefreshFrequencyMins setting). - If the VM drifts from the desired state (e.g., a service is stopped), DSC will correct it automatically. - The extension reports Succeeded if the initial application succeeds, but ongoing compliance is handled by the LCM.

Key Difference from CSE: DSC is idempotent and continuous — it ensures the state is maintained, not just applied once. CSE is a one-shot execution.

Purpose: Collect diagnostic data (performance counters, event logs, crash dumps, etc.) from the VM and send it to Azure Storage (or Azure Monitor).

Key Properties: - Windows: Microsoft.Azure.Diagnostics.IaaSDiagnostics (version 1.12) - Linux: Microsoft.OSTCExtensions.LinuxDiagnostic (version 3.0) - Settings: Complex JSON with three main sections: - xmlCfg: Base64-encoded XML (Windows) or JSON (Linux) defining data sources. - StorageAccount: Name of the storage account to send data to. - ladCfg (Linux): Defines performance counters, syslog, etc.

Data Collected: - Performance counters (CPU, memory, disk, network) — sampled every 30 seconds by default. - Event logs (System, Application, Security) — Windows only. - Syslog (Linux). - Crash dumps (Windows). - IIS logs and failed request traces (Windows).

Storage Destinations: - Azure Storage Tables: WADPerformanceCountersTable, WADWindowsEventLogsTable, etc. - Azure Storage Blobs: wad-control-container, wad-iis-logfiles, etc. - Azure Monitor Metrics (via diagnostics settings configured separately).

Troubleshooting: - Verify the storage account exists and the VM has access (via SAS or network connectivity). - Check extension status: az vm extension list --vm-name <vm> --resource-group <rg>. - Common issue: tables not created because the extension is not configured to send data.

Deploy Custom Script Extension (Windows) via Azure CLI:

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

Deploy DSC Extension via PowerShell:

$settings = @{
  modulesUrl = "https://mystorage.blob.core.windows.net/dsc/MyConfig.zip"
  configurationFunction = "MyConfig.ps1\\MyConfig"
  properties = @{
    ServerName = "WebServer"
  }
}
Set-AzVMExtension -ResourceGroupName myRG -VMName myVM -Name "DSC" -Publisher Microsoft.Powershell -ExtensionType DSC -TypeHandlerVersion 2.83 -Settings $settings

Deploy Diagnostics Extension (Windows) via portal:

Navigate to VM > Diagnostics settings > Enable guest-level monitoring. This automatically configures the extension with default performance counters and event logs.

Verify extension status:

az vm extension list --vm-name myVM --resource-group myRG -o table

Output shows Name, Publisher, Version, and ProvisioningState (Succeeded/Failed).

Scenario 1: Enterprise Onboarding of Web Servers A company provisions hundreds of Windows Server VMs for a web farm. They need to install IIS, .NET Framework, and join a domain automatically. Using Custom Script Extension in an ARM template, they deploy a PowerShell script that installs IIS via Install-WindowsFeature, configures the default website, and runs Add-Computer to join the domain. The script is stored in Azure Blob Storage with a SAS token for access. At scale, they must ensure the storage account is in the same region to avoid egress costs and latency. A common misconfiguration is forgetting to include the SAS token or placing the script in a private container without proper authentication, causing the extension to fail with 'Access Denied'. They also use the timestamp property to force re-run when the script changes.

Scenario 2: Compliance Enforcement with DSC A financial institution requires all VMs to have specific security settings: Windows Firewall enabled, certain ports blocked, and audit policies configured. They use the DSC extension to apply a baseline configuration. The configuration is compiled into a MOF file and zipped with required modules. The DSC extension ensures that if an administrator accidentally disables the firewall, the LCM will re-enable it within 15 minutes. A pitfall is that the DSC extension does not automatically update when the configuration changes — they must increment the version of the module URL or use a new timestamp to trigger re-application. They also monitor compliance via Azure Automation State Configuration (formerly Azure Automation DSC) for centralized reporting.

Scenario 3: Performance Monitoring for Production VMs A SaaS company needs to monitor CPU, memory, and disk performance across 500 VMs. They enable the Diagnostics extension on each VM with default performance counters (sampled every 30 seconds). The data flows into a storage account where they use Azure Monitor Logs (via diagnostic settings) to create dashboards and alerts. At scale, they must be careful about storage costs — each VM generates ~5 MB of diagnostics data per day. A common issue is that the Diagnostics extension on Linux (LAD) requires a separate storage account for metrics (called 'sinks') and if the storage account key is not provided correctly, data collection silently fails. They also enable boot diagnostics separately for crash analysis.