How to setup a guest configuration authoring environment

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

  • Creating a guest configuration content artifact (.zip)
  • Validating the package meets requirements
  • Installing the guest 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 guest configuration is introduced in version 3.4.2.

Important

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.0-preview.6

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.
    • Only the Az modules 'Az.Accounts', 'Az.Resources', and 'Az.Storage' are required.
  • PSDesiredStateConfiguration module.

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

# Install the guest 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'

Update and import the PSDesiredStateConfiguration module on Linux

Starting with PowerShell 7.2 Preview 6, DSC is released independently from PowerShell as a module in the PowerShell Gallery. To install DSC version 3 in your PowerShell environment on Linux, run the command below.

# Install the DSC module before compiling using the Configuration keyword
Install-Module PSDesiredStateConfiguration -AllowPreRelease -Force

Next steps