How to test guest configuration package artifacts

  • Article

The PowerShell module GuestConfiguration includes tools to automate testing a configuration package outside of Azure. Use these tools to find issues and iterate quickly before moving on to test in an Azure connected environment.

Before you can begin testing, follow all steps in the page How to setup a guest configuration authoring environment and then How to create custom guest configuration package artifacts to create and publish a custom guest configuration package.

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.

You can test the package from your workstation or continuous integration and continuous deployment (CI/CD) environment. The GuestConfiguration module includes the same agent for your development environment as is used inside Azure machines. The agent includes a stand-alone instance of PowerShell 7.1.3 for Windows and 7.2.0-preview.7 for Linux, so the script environment where the package is tested will be consistent with machines you manage using guest configuration.

The agent service in Azure machines is running as the "LocalSystem" account in Windows and "Root" in Linux. Run the commands below in privileged security context for best results.

To run PowerShell as "LocalSystem" in Windows, use the SysInternals tool PSExec.

To run PowerShell as "Root" in Linux, use the Su command.

Validate the configuration package meets requirements

First test that the configuration package meets basic requirements using Get-GuestConfigurationPackageComplianceStatus . The command verifies the following package requirements.

  • MOF is present and valid, at the right location
  • Required Modules/dependencies are present with the right version, without duplicates
  • Validate the package is signed (optional)
  • Test that Test and Get return information about the compliance status

Parameters of the Get-GuestConfigurationPackageComplianceStatus cmdlet:

  • Path: File path or URI of the guest configuration package.
  • Parameter: Policy parameters provided in hashtable format.

When this command is run for the first time, the guest configuration agent gets installed on the test machine at the path c:\programdata\GuestConfig\bin on Windows and /var/lib/GuestConfig/bin on Linux. This path isn't accessible to a user account so the command requires elevation.

Run the following command to test the package:

In Windows, from an elevated PowerShell 7 session.

# Get the current compliance results for the local machine
Get-GuestConfigurationPackageComplianceStatus -Path ./MyConfig.zip

In Linux, by running PowerShell using sudo.

# Get the current compliance results for the local machine
sudo pwsh -command 'Get-GuestConfigurationPackageComplianceStatus -Path ./MyConfig.zip'

The command outputs an object containing the compliance status and details per resource.

  complianceStatus  resources
  ---------------- ---------
  True              @{BuiltInAccount=localSystem; ConfigurationName=MyConfig; Credential=; Dependencies=System.Obje…

Test the configuration package can apply a configuration

Finally, if the configuration package mode is AuditandSet you can test that the Set method can apply settings to a local machine using the command Start-GuestConfigurationPackageRemediation.

Important

This command attempts to make changes in the local environment where it's run.

Parameters of the Start-GuestConfigurationPackageRemediation cmdlet:

  • Path: Full path of the guest configuration package.

In Windows, from an elevated PowerShell 7 session.

# Test applying the configuration to local machine
Start-GuestConfigurationPackageRemediation -Path ./MyConfig.zip

In Linux, by running PowerShell using sudo.

# Test applying the configuration to local machine
sudo pwsh -command 'Start-GuestConfigurationPackageRemediation -Path ./MyConfig.zip'

The command won't return output unless errors occur. To troubleshoot details about events occurring during Set, use the -verbose parameter.

After running the command Start-GuestConfigurationPackageRemediation, you can run the command Get-GuestConfigurationComplianceStatus again to confirm the machine is now in the correct state.

Next steps