How to set up a machine configuration authoring environment


Azure Policy Guest Configuration is now called Azure Automanage Machine Configuration. Learn more about the recent renaming of Microsoft configuration management services.

The PowerShell module GuestConfiguration automates the process of creating custom content including:

  • Creating a machine configuration content artifact (.zip)
  • Validating the package meets requirements
  • Installing the machine configuration agent locally for testing
  • Validating the package can be used to audit settings in a machine
  • Validating the package can be used to configure settings in a machine
  • Publishing the package to Azure storage
  • Creating a policy definition
  • Publishing the policy

Support for applying configurations through machine configuration is introduced in version 3.4.2.


Custom packages that audit the state of an environment are Generally Available, but packages that apply configurations are in preview. The following limitations apply:

To test creating and applying configurations on Linux, the GuestConfiguration module is only available on Ubuntu 18 but the package and policy definitions produced by the module can be used on any Linux distro/version supported in Azure or Arc.

Testing packages on MacOS isn't available.

Base requirements

Operating Systems where the module can be installed:

  • Ubuntu 18
  • Windows

The module can be installed on a machine running PowerShell 7. Install the versions of PowerShell listed below.

OS PowerShell Version
Windows PowerShell 7.1.3
Ubuntu 18 PowerShell 7.2.4

The GuestConfiguration module requires the following software:

  • Azure PowerShell 5.9.0 or higher. The required Az modules are installed automatically with the GuestConfiguration module, or you can follow these instructions.

To install the GuestConfiguration module on either Windows or Linux, run the following command in PowerShell 7.

# Install the machine configuration DSC resource module from PowerShell Gallery
Install-Module -Name GuestConfiguration

Validate that the module has been imported:

# Get a list of commands for the imported GuestConfiguration module
Get-Command -Module 'GuestConfiguration'

Next steps