Understand Azure Policy's Guest Configuration

Azure Policy can audit settings inside a machine, both for machines running in Azure and Arc Connected Machines. The validation is performed by the Guest Configuration extension and client. The extension, through the client, validates settings such as:

  • The configuration of the operating system
  • Application configuration or presence
  • Environment settings

At this time, most Azure Policy Guest Configuration policy definitions only audit settings inside the machine. They don't apply configurations. The exception is one built-in policy referenced below.

A video walk-through of this document is available.

Enable Guest Configuration

To audit the state of machines in your environment, including machines in Azure and Arc Connected Machines, review the following details.

Resource provider

Before you can use Guest Configuration, you must register the resource provider. If assignment of a Guest Configuration policy is done through the portal, or if the subscription is enrolled in Azure Security Center, the resource provider is registered automatically. You can manually register through the portal, Azure PowerShell, or Azure CLI.

Deploy requirements for Azure virtual machines

To audit settings inside a machine, a virtual machine extension is enabled and the machine must have a system-managed identity. The extension downloads applicable policy assignment and the corresponding configuration definition. The identity is used to authenticate the machine as it reads and writes to the Guest Configuration service. The extension isn't required for Arc Connected Machines because it's included in the Arc Connected Machine agent.


The Guest Configuration extension and a managed identity is required to audit Azure virtual machines. To deploy the extension at scale, assign the following policy initiative:

Deploy prerequisites to enable Guest Configuration policies on virtual machines

Limits set on the extension

To limit the extension from impacting applications running inside the machine, the Guest Configuration isn't allowed to exceed more than 5% of CPU. This limitation exists for both built-in and custom definitions. The same is true for the Guest Configuration service in Arc Connected Machine agent.

Validation tools

Inside the machine, the Guest Configuration client uses local tools to run the audit.

The following table shows a list of the local tools used on each supported operating system. For built-in content, Guest Configuration handles loading these tools automatically.

Operating system Validation tool Notes
Windows PowerShell Desired State Configuration v2 Side-loaded to a folder only used by Azure Policy. Won't conflict with Windows PowerShell DSC. PowerShell Core isn't added to system path.
Linux Chef InSpec Installs Chef InSpec version 2.2.61 in default location and added to system path. Dependencies for the InSpec package including Ruby and Python are installed as well.

Validation frequency

The Guest Configuration client checks for new or changed guest assignments every 5 minutes. Once a guest assignment is received, the settings for that configuration are rechecked on a 15-minute interval. Results are sent to the Guest Configuration resource provider when the audit completes. When a policy evaluation trigger occurs, the state of the machine is written to the Guest Configuration resource provider. This update causes Azure Policy to evaluate the Azure Resource Manager properties. An on-demand Azure Policy evaluation retrieves the latest value from the Guest Configuration resource provider. However, it doesn't trigger a new audit of the configuration within the machine. The status is simultaneously written to Azure Resource Graph.

Supported client types

Guest Configuration policy definitions are inclusive of new versions. Older versions of operating systems available in Azure Marketplace are excluded if the Guest Configuration client isn't compatible. The following table shows a list of supported operating systems on Azure images. The ".x" text is symbolic to represent new minor versions of Linux distributions.

Publisher Name Versions
Canonical Ubuntu Server 14.04 - 20.x
Credativ Debian 8 - 10.x
Microsoft Windows Server 2012 - 2019
Microsoft Windows Client Windows 10
OpenLogic CentOS 7.3 -8.x
Red Hat Red Hat Enterprise Linux* 7.4 - 8.x
SUSE SLES 12 SP3-SP5, 15.x

* Red Hat CoreOS isn't supported.

Custom virtual machine images are supported by Guest Configuration policy definitions as long as they're one of the operating systems in the table above.

Network requirements

Virtual machines in Azure can use either their local network adapter or a private link to communicate with the Guest Configuration service.

Azure Arc machines connect using the on-premises network infrastructure to reach Azure services and report compliance status.

Communicate over virtual networks in Azure

To communicate with the Guest Configuration resource provider in Azure, machines require outbound access to Azure datacenters on port 443. If a network in Azure doesn't allow outbound traffic, configure exceptions with Network Security Group rules. The service tags "AzureArcInfrastructure" and "Storage" can be used to reference the Guest Configuration and Storage services rather than manually maintaining the list of IP ranges for Azure datacenters. Both tags are required because Guest Configuration content packages are hosted by Azure Storage.

Virtual machines can use private link for communication to the Guest Configuration service. Apply tag with the name EnablePrivateNetworkGC and value TRUE to enable this feature. The tag can be applied before or after Guest Configuration policy definitions are applied to the machine.

Traffic is routed using the Azure virtual public IP address to establish a secure, authenticated channel with Azure platform resources.

Azure Arc connected machines

Nodes located outside Azure that are connected by Azure Arc require connectivity to the Guest Configuration service. Details about network and proxy requirements provided in the Azure Arc documentation.

For Arc connected servers in private datacenters, allow traffic using the following patterns:

  • Port: Only TCP 443 required for outbound internet access
  • Global URL: *.guestconfiguration.azure.com

Managed identity requirements

Policy definitions in the initiative Deploy prerequisites to enable Guest Configuration policies on virtual machines enable a system-assigned managed identity, if one doesn't exist. There are two policy definitions in the initiative that manage identity creation. The IF conditions in the policy definitions ensure the correct behavior based on the current state of the machine resource in Azure.

If the machine doesn't currently have any managed identities, the effective policy will be: Add system-assigned managed identity to enable Guest Configuration assignments on virtual machines with no identities

If the machine currently has a user-assigned system identity, the effective policy will be: Add system-assigned managed identity to enable Guest Configuration assignments on VMs with a user-assigned identity

Guest Configuration definition requirements

Guest Configuration policy definitions use the AuditIfNotExists effect. When the definition is assigned, a back-end service automatically handles the lifecycle of all requirements in the Microsoft.GuestConfiguration Azure resource provider.

The AuditIfNotExists policy definitions won't return compliance results until all requirements are met on the machine. The requirements are described in section Deploy requirements for Azure virtual machines


In a prior release of Guest Configuration, an initiative was required to combine DeployIfNotExists and AuditIfNotExists definitions. DeployIfNotExists definitions are no longer required. The definitions and initiatives are labeled [Deprecated] but existing assignments will continue to function. For information see the blog post: Important change released for Guest Configuration audit policies

What is a Guest Assignment?

When an Azure Policy is assigned, if it's in the category "Guest Configuration" there's metadata included to describe a Guest Assignment. You can think of a Guest Assignment as a link between a machine and an Azure Policy scenario. For example, the following snippet associates the Azure Windows Baseline configuration with minimum version 1.0.0 to any machines in scope of the policy. By default, the Guest Assignment will only perform an audit of the machine.

"metadata": {
    "category": "Guest Configuration",
    "guestConfiguration": {
        "name": "AzureWindowsBaseline",
        "version": "1.*"
//additional metadata properties exist

Guest Assignments are created automatically per machine by the Guest Configuration service. The resource type is Microsoft.GuestConfiguration/guestConfigurationAssignments. Azure Policy uses the complianceStatus property of the Guest Assignment resource to report compliance status. For more information, see getting compliance data.

Auditing operating system settings following industry baselines

One initiative in Azure Policy audits operating system settings following a "baseline". The definition, [Preview]: Windows machines should meet requirements for the Azure security baseline includes a set of rules based on Active Directory Group Policy.

Most of the settings are available as parameters. Parameters allow you to customize what is audited. Align the policy with your requirements or map the policy to third-party information such as industry regulatory standards.

Some parameters support an integer value range. For example, the Maximum Password Age setting could audit the effective Group Policy setting. A "1,70" range would confirm that users are required to change their passwords at least every 70 days, but no less than one day.

If you assign the policy using an Azure Resource Manager template (ARM template), use a parameters file to manage exceptions. Check in the files to a version control system such as Git. Comments about file changes provide evidence why an assignment is an exception to the expected value.

Applying configurations using Guest Configuration

Only the definition Configure the time zone on Windows machines makes changes to the machine by configuring the time zone. Custom policy definitions for configuring settings inside machines aren't supported.

When assigning definitions that begin with Configure, you must also assign the definition Deploy prerequisites to enable Guest Configuration Policy on Windows VMs. You can combine these definitions in an initiative if you choose.


The built-in time zone policy is the only definition that supports configuring settings inside machines and custom policy definitions that configure settings inside machines aren't supported.

Assigning policies to machines outside of Azure

The Audit policy definitions available for Guest Configuration include the Microsoft.HybridCompute/machines resource type. Any machines onboarded to Azure Arc for servers that are in the scope of the policy assignment are automatically included.


Customers designing a highly available solution should consider the redundancy planning requirements for virtual machines because guest assignments are extensions of machine resources in Azure. When guest assignment resources are provisioned in to an Azure region that is paired, as long as at least one region in the pair is available, then guest assignment reports are available. If the Azure region isn't paired and it becomes unavailable, then it isn't possible to access reports for a guest assignment until the region is restored.

When considering an architecture for highly available applications, especially where virtual machines are provisioned in Availability Sets behind a load balancer solution to provide high availability, it's best practice to assign the same policy definitions with the same parameters to all machines in the solution. If possible, a single policy assignment spanning all machines would offer the least administrative overhead.

For machines protected by Azure Site Recovery, ensure that machines in a secondary site are within scope of Azure Policy assignments for the same definitions using the same parameter values as machines in the primary site.

Troubleshooting guest configuration

For more information about troubleshooting Guest Configuration, see Azure Policy troubleshooting.

Multiple assignments

Guest Configuration policy definitions currently only support assigning the same Guest Assignment once per machine, even if the Policy assignment uses different parameters.

Client log files

The Guest Configuration extension writes log files to the following locations:

Windows: C:\ProgramData\GuestConfig\gc_agent_logs\gc_agent.log


  • Azure VM: /var/lib/GuestConfig/gc_agent_logs/gc_agent.log
  • Azure VM: /var/lib/GuestConfig/arc_policy_logs/gc_agent.log

Collecting logs remotely

The first step in troubleshooting Guest Configuration configurations or modules should be to use the Test-GuestConfigurationPackage cmdlet following the steps how to create a custom Guest Configuration audit policy for Windows. If that isn't successful, collecting client logs can help diagnose issues.


Capture information from log files using Azure VM Run Command, the following example PowerShell script can be helpful.

$linesToIncludeBeforeMatch = 0
$linesToIncludeAfterMatch = 10
$logPath = 'C:\ProgramData\GuestConfig\gc_agent_logs\gc_agent.log'
Select-String -Path $logPath -pattern 'DSCEngine','DSCManagedEngine' -CaseSensitive -Context $linesToIncludeBeforeMatch,$linesToIncludeAfterMatch | Select-Object -Last 10


Capture information from log files using Azure VM Run Command, the following example Bash script can be helpful.

egrep -B $linesToIncludeBeforeMatch -A $linesToIncludeAfterMatch 'DSCEngine|DSCManagedEngine' $logPath | tail

Client files

The Guest Configuration client downloads content packages to a machine and extracts the contents. To verify what content has been downloaded and stored, view the folder locations given below.

Windows: c:\programdata\guestconfig\configuration

Linux: /var/lib/GuestConfig/Configuration

Guest Configuration samples

Guest Configuration built-in policy samples are available in the following locations:

Video overview

The following overview of Azure Policy Guest Configuration is from ITOps Talks 2021.

Governing baselines in hybrid server environments using Azure Policy Guest Configuration

Next steps