Understand the guest configuration feature of Azure Policy ...

Understand the guest configuration feature of Azure Policy

07/15/20218 minutes to read

In this article

Azure Policy can audit or configure settings inside a machine, both for machinesrunning in Azure andArc-enabled machines.Each task is performed by the guest configuration agent in Windows and Linux.The guest configuration extension, through the agent, manages settings such as:

The configuration of the operating systemApplication configuration or presenceEnvironment settings

A video walk-through of this document is available.

Enable guest configuration

To manage the state of machines in your environment, including machines in Azureand Arc-enabled servers, review the following details.

Resource provider

Before you can use the guest configuration feature of Azure Policy, you mustregister the Microsoft.GuestConfiguration resource provider. If assignment ofa guest configuration policy is done through the portal, or if the subscriptionis enrolled in Azure Security Center, the resource provider is registeredautomatically. You can manually register through theportal,Azure PowerShell,orAzure CLI.

Deploy requirements for Azure virtual machines

To manage settings inside a machine, avirtual machine extension isenabled and the machine must have a system-managed identity. The extensiondownloads applicable guest configuration assignment and the correspondingdependencies. The identity is used to authenticate the machine as it reads andwrites to the guest configuration service. The extension isn't required for Arc-enabledservers because it's included in the Arc Connected Machine agent.

To deploy the extension at scale across many machines, assign the policy initiativeDeploy prerequisites to enable guest configuration policies on virtual machinesto a management group, subscription, or resource group containing the machinesthat you plan to manage.

If you prefer to deploy the extension and managed identity to a single machine,follow the guidance for each:

To use guest configuration packages that apply configurations, Azure VM guestconfiguration extension version 1.29.24 or later is required.

Limits set on the extension

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

Inside the machine, the guest configuration agent uses local tools to performtasks.

The following table shows a list of the local tools used on each supportedoperating system. For built-in content, guest configuration handles loadingthese tools automatically.

Operating systemValidation toolNotesWindowsPowerShell Desired State Configuration v3Side-loaded to a folder only used by Azure Policy. Won't conflict with Windows PowerShell DSC. PowerShell Core isn't added to system path.LinuxPowerShell Desired State Configuration v3Side-loaded to a folder only used by Azure Policy. PowerShell Core isn't added to system path.LinuxChef InSpecInstalls 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 agent checks for new or changed guest assignments every5 minutes. Once a guest assignment is received, the settings for thatconfiguration are rechecked on a 15-minute interval. If multiple configurationsare assigned, each is evaluated sequentially. Long-running configurations impactthe interval for all configurations, because the next will not run until theprior configuration has finished.

Results are sent to the guest configuration service when the audit completes.When a policyevaluation triggeroccurs, the state of the machine is written to the guest configuration resourceprovider. This update causes Azure Policy to evaluate the Azure Resource Managerproperties. An on-demand Azure Policy evaluation retrieves the latest value fromthe guest configuration resource provider. However, it doesn't trigger a newactivity within the machine. The status is then written to AzureResource Graph.

Supported client types

Guest configuration policy definitions are inclusive of new versions. Older versions of operatingsystems available in Azure Marketplace are excluded if the Guest Configuration client isn'tcompatible. 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.

PublisherNameVersionsAmazonLinux2CanonicalUbuntu Server14.04 - 20.xCredativDebian8 - 10.xMicrosoftWindows Server2012 - 2019MicrosoftWindows ClientWindows 10OracleOracle-Linux7.x-8.xOpenLogicCentOS7.3 -8.xRed HatRed Hat Enterprise Linux*7.4 - 8.xSUSESLES12 SP3-SP5, 15.x

* Red Hat CoreOS isn't supported.

Custom virtual machine images are supported by guest configuration policydefinitions 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 aprivate link to communicate with the guest configuration service.

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

Communicate over virtual networks in Azure

To communicate with the guest configuration resource provider in Azure, machinesrequire outbound access to Azure datacenters on port 443. If a network inAzure doesn't allow outbound traffic, configure exceptions withNetwork Security Grouprules. Theservice tags"AzureArcInfrastructure" and "Storage" can be used to reference the guestconfiguration and Storage services rather than manually maintaining thelist of IP rangesfor Azure datacenters. Both tags are required because guest configurationcontent packages are hosted by Azure Storage.

Communicate over Private Link in Azure

Virtual machines can useprivate linkfor communication to the guest configuration service. Apply tag with the nameEnablePrivateNetworkGC and value TRUE to enable this feature. The tag can beapplied before or after guest configuration policy definitions are applied tothe machine.

Traffic is routed using the Azurevirtual public IP addressto establish a secure, authenticated channel with Azure platform resources.

Azure Arc-enabled servers

Nodes located outside Azure that are connected by Azure Arc require connectivityto the guest configuration service. Details about network and proxy requirementsprovided in theAzure Arc documentation.

For Arc-enabled servers in private datacenters, allow traffic using thefollowing patterns:

Port: Only TCP 443 required for outbound internet accessGlobal URL: *.guestconfiguration.azure.com

Assigning policies to machines outside of Azure

The Audit policy definitions available for guest configuration include theMicrosoft.HybridCompute/machines resource type. Any machines onboarded toAzure Arc for servers that are in thescope of the policy assignment are automatically included.

Managed identity requirements

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

If the machine doesn't currently have any managed identities, the effectivepolicy is: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 effectivepolicy is:Add system-assigned managed identity to enable guest configuration assignments on VMs with a user-assigned identity

Availability

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

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

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

Data residency

Guest configuration stores/processes customer data. By default, customer data is replicated to thepaired region.For single resident region all customer data is stored and processed in the region.

Troubleshooting guest configuration

For more information about troubleshooting guest configuration, seeAzure Policy troubleshooting.

Multiple assignments

Guest configuration policy definitions currently only support assigning the sameguest assignment once per machine when the policy assignment uses differentparameters.

Assignments to Azure Management Groups

Azure Policy definitions in the category 'Guest Configuration' can be assignedto Management Groups only when the effect is 'AuditIfNotExists'. Policydefinitions with effect 'DeployIfNotExists' aren't supported as assignments toManagement Groups.

Client log files

The guest configuration extension writes log files to the following locations:

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

Linux

Azure VM: /var/lib/GuestConfig/gc_agent_logs/gc_agent.logArc-enabled server: /var/lib/GuestConfig/arc_policy_logs/gc_agent.log

Collecting logs remotely

The first step in troubleshooting guest configuration configurations or modulesshould be to use the cmdlets following the steps inHow to test guest configuration package artifacts.If that isn't successful, collecting client logs can help diagnose issues.

Windows

Capture information from log files usingAzure VM Run Command, thefollowing 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 10Linux

Capture information from log files usingAzure VM Run Command, thefollowing example Bash script can be helpful.

linesToIncludeBeforeMatch=0linesToIncludeAfterMatch=10logPath=/var/lib/GuestConfig/gc_agent_logs/gc_agent.logegrep -B $linesToIncludeBeforeMatch -A $linesToIncludeAfterMatch 'DSCEngine|DSCManagedEngine' $logPath | tail

Agent files

The guest configuration agent downloads content packages to a machine andextracts 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 followinglocations:

Next steps