Configure machines to a desired state

  • Article

Note

Azure Automation State Configuration will be retired on September 30, 2027, please transition to Azure Machine Configuration by that date. For more information, see the blog post announcement. The Azure Machine Configuration service combines features of DSC Extension, Azure Automation State Configuration, and the most commonly requested features from customer feedback. Azure Machine Configuration also includes hybrid machine support through Arc-enabled servers.

Caution

Azure Automation DSC for Linux has retired on 30 September 2023. For more information, see the announcement.

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.

Prerequisites

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're using two configurations for a node you need 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.

Sign in to Azure

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

Connect-AzAccount

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
      }
   }
}

Note

Configuration names in Azure Automation must be limited to no more than 100 characters.

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.

$importAzAutomationDscConfigurationSplat = @{
    SourcePath = 'C:\DscConfigs\TestConfig.ps1'
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
    Published = $ture
}
Import-AzAutomationDscConfiguration @importAzAutomationDscConfigurationSplat

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.

$startAzAutomationDscCompilationJobSplat = @{
    ConfigurationName = 'TestConfig'
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
}
Start-AzAutomationDscCompilationJob @startAzAutomationDscCompilationJobSplat

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 article, 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.

$registerAzAutomationDscNodeSplat = @{
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
    AzureVMName = 'DscVm'
}
Register-AzAutomationDscNode @registerAzAutomationDscNodeSplat

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.

$registerAzAutomationDscNodeSplat = @{
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
    AzureVMName = 'DscVm'
    ConfigurationMode = 'ApplyOnly'
}
Register-AzAutomationDscNode @registerAzAutomationDscNodeSplat```

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][05].

```powershell
# Run a DSC check every 60 minutes
$registerAzAutomationDscNodeSplat = @{
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
    AzureVMName = 'DscVm'
    ConfigurationModeFrequencyMins = 60
}
Register-AzAutomationDscNode @registerAzAutomationDscNodeSplat```

## Assign a node configuration to a managed node

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

```powershell
# Get the ID of the DSC node
$getAzAutomationDscNodeSplat = @{
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
    Name = 'DscVm'
}
$node = Get-AzAutomationDscNode @getAzAutomationDscNodeSplat

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

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
$getAzAutomationDscNodeSplat = @{
    ResourceGroupName = 'MyResourceGroup'
    AutomationAccountName = 'myAutomationAccount'
    Name = 'DscVm'
}
$node = Get-AzAutomationDscNode @getAzAutomationDscNodeSplat

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

# Display the most recent report
$reports[0]

Next steps