How to create custom guest configuration package artifacts

  • Article

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

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

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 use guest configuration packages that apply configurations, Azure VM guest configuration extension version 1.29.24 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 distro/version supported in Azure.

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 guest 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.

Important

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 guest 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 guest 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: guest 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 `
  -Force

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

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

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

Expected contents of a guest configuration artifact

The completed package is used by guest 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 guest configuration with third-party tools

The artifact packages for guest configuration can be extended to include third-party tools. Extending guest 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.

Note

Guest 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