Configure machines to a desired state

Azure Automation State Configuration allows you to specify configurations for your servers and ensure that those servers are in the specified state over time.

  • Onboard a VM to be managed by Azure Automation DSC
  • Upload a configuration to Azure Automation
  • Compile a configuration into a node configuration
  • Assign a node configuration to a managed node
  • Check the compliance status of a managed node

For this tutorial, we use a simple DSC configuration that ensures that IIS is installed on the VM.


Support for partial configurations

Azure Automation State Configuration supports the use of partial configurations. In this scenario, DSC is configured to manage multiple configurations independently, and each configuration is retrieved from Azure Automation. However, only one configuration can be assigned to a node per automation account. This means if you are using two configurations for a node you will require two Automation accounts.

For details about how to register a partial configuration from a pull service, see the documentation for partial configurations.

For more information about how teams can work together to collaboratively manage servers using configuration as code, see Understanding DSC's role in a CI/CD Pipeline.

Log in to Azure

Log in to your Azure subscription with the Connect-AzAccount cmdlet and follow the on-screen directions.


Create and upload a configuration to Azure Automation

In a text editor, type the following and save it locally as TestConfig.ps1.

configuration TestConfig {
   Node WebServer {
      WindowsFeature IIS {
         Ensure               = 'Present'
         Name                 = 'Web-Server'
         IncludeAllSubFeature = $true


In more advanced scenarios where you require multiple modules to be imported that provide DSC Resources, make sure each module has a unique Import-DscResource line in your configuration.

Call the Import-AzAutomationDscConfiguration cmdlet to upload the configuration into your Automation account.

 Import-AzAutomationDscConfiguration -SourcePath 'C:\DscConfigs\TestConfig.ps1' -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -Published

Compile a configuration into a node configuration

A DSC configuration must be compiled into a node configuration before it can be assigned to a node. See DSC configurations.

Call the Start-AzAutomationDscCompilationJob cmdlet to compile the TestConfig configuration into a node configuration named TestConfig.WebServer in your Automation account.

Start-AzAutomationDscCompilationJob -ConfigurationName 'TestConfig' -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount'

Register a VM to be managed by State Configuration

You can use Azure Automation State Configuration to manage Azure VMs (both Classic and Resource Manager), on-premises VMs, Linux machines, AWS VMs, and on-premises physical machines. In this topic, we cover how to register only Azure Resource Manager VMs. For information about registering other types of machines, see Onboarding machines for management by Azure Automation State Configuration.

Call the Register-AzAutomationDscNode cmdlet to register your VM with Azure Automation State Configuration as a managed node.

Register-AzAutomationDscNode -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -AzureVMName 'DscVm'

Specify configuration mode settings

Use the Register-AzAutomationDscNode cmdlet to register a VM as a managed node and specify configuration properties. For example, you can specify that the state of the machine is to be applied only once by specifying ApplyOnly as the value of the ConfigurationMode property. State Configuration doesn't try to apply the configuration after the initial check.

Register-AzAutomationDscNode -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -AzureVMName 'DscVm' -ConfigurationMode 'ApplyOnly'

You can also specify how often DSC checks the configuration state by using the ConfigurationModeFrequencyMins property. For more information about DSC configuration settings, see Configuring the Local Configuration Manager.

# Run a DSC check every 60 minutes
Register-AzAutomationDscNode -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -AzureVMName 'DscVm' -ConfigurationModeFrequencyMins 60

Assign a node configuration to a managed node

Now we can assign the compiled node configuration to the VM we want to configure.

# Get the ID of the DSC node
$node = Get-AzAutomationDscNode -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -Name 'DscVm'

# Assign the node configuration to the DSC node
Set-AzAutomationDscNode -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -NodeConfigurationName 'TestConfig.WebServer' -NodeId $node.Id

This assigns the node configuration named TestConfig.WebServer to the registered DSC node DscVm. By default, the DSC node is checked for compliance with the node configuration every 30 minutes. For information about how to change the compliance check interval, see Configuring the Local Configuration Manager.

Check the compliance status of a managed node

You can get reports on the compliance status of a managed node using the Get-AzAutomationDscNodeReport cmdlet.

# Get the ID of the DSC node
$node = Get-AzAutomationDscNode -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -Name 'DscVm'

# Get an array of status reports for the DSC node
$reports = Get-AzAutomationDscNodeReport -ResourceGroupName 'MyResourceGroup' -AutomationAccountName 'myAutomationAccount' -NodeId $node.Id

# Display the most recent report

Remove nodes from service

When you add a node to Azure Automation State Configuration, the settings in Local Configuration Manager are set to register with the service and pull configurations and required modules to configure the machine. If you choose to remove the node from the service, you can do so using either the Azure portal or the Az cmdlets.


Unregistering a node from the service only sets the Local Configuration Manager settings so the node is no longer connecting to the service. This does not effect the configuration that is currently applied to the node. To remove the current configuration, use the PowerShell or delete the local configuration file (this is the only option for Linux nodes).

Azure portal

From Azure Automation, click on State configuration (DSC) in the table of contents. Next click Nodes to view the list of nodes that are registered with the service. Click on the name of the node you wish to remove. In the Node view that opens, click Unregister.


To unregister a node from Azure Automation State Configuration service using PowerShell, follow the documentation for the cmdlet Unregister-AzAutomationDscNode.

Next steps