How to create custom machine configuration package artifacts


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

Before you begin, it's a good idea to read the overview page for machine configuration.

When auditing / configuring both Windows and Linux, machine configuration uses a Desired State Configuration (DSC). The DSC configuration defines the condition that the machine should be in.


Custom packages that audit the state of an environment and apply configurations are in generally available (GA) support status. However, the following limitations apply:

To use machine configuration packages that apply configurations, Azure VM guest configuration extension version 1.29.24 or later, or Arc agent 1.10.0 or later, is required.

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

Testing packages on macOS is not available.

Don't use secrets or confidential information in custom content packages.

Use the following steps to create your own configuration for managing the state of an Azure or non-Azure machine.

Install PowerShell 7 and required PowerShell modules

First, make sure you've followed all steps on the page How to setup a machine configuration authoring environment to install the required version of PowerShell for your OS, the GuestConfiguration module, and if needed, the module PSDesiredStateConfiguration.

Author a configuration

Before creating a configuration package, author and compile a DSC configuration. If needed, example configurations are available for Windows and Linux.


When compiling configurations for Windows, use PSDesiredStateConfiguration version 2.0.5 (the stable release). When compiling configurations for Linux install the prerelease version 3.0.0.

An example is provided in the DSC Getting started document for Windows.

For Linux, you'll need to create a custom DSC resource module using PowerShell classes. A full example of a custom resource and configuration is available (and has been tested with machine configuration) in the PowerShell docs page Writing a custom DSC resource with PowerShell classes.

Create a configuration package artifact

Once the MOF is compiled, the supporting files must be packaged together. The completed package is used by machine configuration to create the Azure Policy definitions.

The New-GuestConfigurationPackage cmdlet creates the package. Modules that are needed by the configuration must be in available in $Env:PSModulePath for the development environment so the commands in the module can add them to the package.

Parameters of the New-GuestConfigurationPackage cmdlet when creating Windows content:

  • Name: machine configuration package name.
  • Configuration: Compiled DSC configuration document full path.
  • Path: Output folder path. This parameter is optional. If not specified, the package is created in current directory.
  • Type: (Audit, AuditandSet) Determines whether the configuration should only audit or if the configuration should be applied and change the state of the machine. The default is "Audit".

This step doesn't require elevation. The Force cmdlet is used to overwrite existing packages, if you run the command more than once.

The following commands create a package artifacts:

# Create a package that will only audit compliance
New-GuestConfigurationPackage `
  -Name 'MyConfig' `
  -Configuration './Config/MyConfig.mof' `
  -Type Audit `
# Create a package that will audit and apply the configuration (Set)
New-GuestConfigurationPackage `
  -Name 'MyConfig' `
  -Configuration './Config/MyConfig.mof' `
  -Type AuditAndSet `

An object is returned with the Name and Path of the created package.

Name      Path
----      ----
MyConfig  /Users/.../MyConfig/

Expected contents of a machine configuration artifact

The completed package is used by machine configuration to create the Azure Policy definitions. The package consists of:

  • The compiled DSC configuration as a MOF
  • Modules folder
    • GuestConfiguration module
    • DscNativeResources module
    • DSC resource modules required by the MOF
  • A metaconfig file that stores the package type and version

The PowerShell cmdlet creates the package .zip file. No root level folder or version folder is required. The package format must be a .zip file and can't exceed a total size of 100 MB when uncompressed.

Extending machine configuration with third-party tools

The artifact packages for machine configuration can be extended to include third-party tools. Extending machine configuration requires development of two components.

  • A Desired State Configuration resource that handles all activity related to managing the third-party tool
    • Install
    • Invoke
    • Convert output
  • Content in the correct format for the tool to natively consume

The DSC resource requires custom development if a community solution doesn't already exist. Community solutions can be discovered by searching the PowerShell Gallery for tag GuestConfiguration.


Machine configuration extensibility is a "bring your own license" scenario. Ensure you have met the terms and conditions of any third party tools before use.

After the DSC resource has been installed in the development environment, use the FilesToInclude parameter for New-GuestConfigurationPackage to include content for the third-party platform in the content artifact.

Next steps