Understanding Azure Machine Configuration
Dėmesio
This article references CentOS, a Linux distribution that is End Of Life (EOL) status. Please consider your use and planning accordingly. For more information, see the CentOS End Of Life guidance.
Azure Policy's machine configuration feature provides native capability to audit or configure operating system settings as code for machines running in Azure and hybrid Arc-enabled machines. You can use the feature directly per-machine, or orchestrate it at scale by using Azure Policy.
Configuration resources in Azure are designed as an extension resource. You can imagine each configuration as an extra set of properties for the machine. Configurations can include settings such as:
- Operating system settings
- Application configuration or presence
- Environment settings
Configurations are distinct from policy definitions. Machine configuration uses Azure Policy to dynamically assign configurations to machines. You can also assign configurations to machines manually, or by using other Azure services such as Automanage.
Examples of each scenario are provided in the following table.
Type | Description | Example story |
---|---|---|
Configuration management | You want a complete representation of a server, as code in source control. The deployment should include properties of the server (size, network, storage) and configuration of operating system and application settings. | "This machine should be a web server configured to host my website." |
Compliance | You want to audit or deploy settings to all machines in scope either reactively to existing machines or proactively to new machines as they're deployed. | "All machines should use TLS 1.2. Audit existing machines so I can release change where it's needed, in a controlled way, at scale. For new machines, enforce the setting when they're deployed." |
You can view the per-setting results from configurations in the Guest assignments page. If an Azure Policy assignment orchestrated the configuration is orchestrated, you can select the "Last evaluated resource" link on the "Compliance details" page.
In order to provide greater flexibility in the enforcement and monitoring of server settings, applications and workloads, Machine Configuration offers three main enforcement modes for each policy assignment as described in the following table.
Mode | Description |
---|---|
Audit | Only report on the state of the machine |
Apply and Monitor | Configuration applied to the machine and then monitored for changes |
Apply and Autocorrect | Configuration applied to the machine and brought back into conformance in the event of drift |
A video walk-through of this document is available. (Update coming soon)
To manage the state of machines in your environment, including machines in Azure and Arc-enabled servers, review the following details.
Before you can use the machine configuration feature of Azure Policy, you must register the
Microsoft.GuestConfiguration
resource provider. If assignment of a machine configuration policy
is done through the portal, or if the subscription is enrolled in Microsoft Defender for Cloud, the
resource provider is registered automatically. You can manually register through the portal,
Azure PowerShell, or Azure CLI.
To manage settings inside a machine, a virtual machine extension is enabled and the machine must have a system-managed identity. The extension downloads applicable machine configuration assignments and the corresponding dependencies. The identity is used to authenticate the machine as it reads and writes to the machine configuration service. The extension isn't required for Arc-enabled servers because it's included in the Arc Connected Machine agent.
Svarbu
The machine configuration extension and a managed identity are required to manage Azure virtual machines.
To deploy the extension at scale across many machines, assign the policy initiative
Deploy prerequisites to enable Guest Configuration policies on virtual machines
to a management group, subscription, or resource group containing the machines that you plan to
manage.
If you prefer to deploy the extension and managed identity to a single machine, see Configure managed identities for Azure resources on a VM using the Azure portal.
To use machine configuration packages that apply configurations, Azure VM guest configuration extension version 1.26.24 or later is required.
Svarbu
The creation of a managed identity or assignment of a policy with "Guest Configuration Resource Contributor" role are actions that require appropriate Azure RBAC permissions to perform. To learn more about Azure Policy and Azure RBAC, see role-based access control in Azure Policy.
To limit the extension from impacting applications running inside the machine, the machine configuration agent 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 machine configuration service in Arc Connected Machine agent.
Inside the machine, the machine configuration agent uses local tools to perform tasks.
The following table shows a list of the local tools used on each supported operating system. For built-in content, machine 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. Doesn't conflict with Windows PowerShell DSC. PowerShell isn't added to system path. |
Linux | PowerShell Desired State Configuration v3 | Side-loaded to a folder only used by Azure Policy. PowerShell isn't added to system path. |
Linux | Chef InSpec | Installs Chef InSpec version 2.2.61 in default location and adds it to system path. It installs InSpec's dependencies, including Ruby and Python, too. |
The machine configuration agent 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. If multiple configurations are assigned, each is evaluated sequentially. Long-running configurations affect the interval for all configurations, because the next can't run until the prior configuration has finished.
Results are sent to the machine configuration service when the audit completes. When a policy evaluation trigger occurs, the state of the machine is written to the machine 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 machine configuration resource provider. However, it doesn't trigger a new activity within the machine. The status is then written to Azure Resource Graph.
Machine 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. Additionally, Linux server versions that are out of lifetime support by their respective publishers are excluded from the support matrix.
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 |
---|---|---|
Alma | AlmaLinux | 9 |
Amazon | Linux | 2 |
Canonical | Ubuntu Server | 16.04 - 22.x |
Credativ | Debian | 10.x - 12.x |
Microsoft | CBL-Mariner | 1 - 2 |
Microsoft | Windows Client | Windows 10, 11 |
Microsoft | Windows Server | 2012 - 2022 |
Oracle | Oracle-Linux | 7.x - 8.x |
OpenLogic | CentOS | 7.3 - 8.x |
Red Hat | Red Hat Enterprise Linux* | 7.4 - 9.x |
Rocky | Rocky Linux | 8 |
SUSE | SLES | 12 SP5, 15.x |
* Red Hat CoreOS isn't supported.
Machine configuration policy definitions support custom virtual machine images as long as they're one of the operating systems in the previous table. Machine Configuration does not support VMSS uniform but does support VMSS Flex.
Azure virtual machines can use either their local virtual network adapter (vNIC) or Azure Private Link to communicate with the machine configuration service.
Azure Arc-enabled machines connect using the on-premises network infrastructure to reach Azure services and report compliance status.
Following is a list of the Azure Storage endpoints required for Azure and Azure Arc-enabled virtual machines to communicate with the machine configuration resource provider in Azure:
oaasguestconfigac2s1.blob.core.windows.net
oaasguestconfigacs1.blob.core.windows.net
oaasguestconfigaes1.blob.core.windows.net
oaasguestconfigases1.blob.core.windows.net
oaasguestconfigbrses1.blob.core.windows.net
oaasguestconfigbrss1.blob.core.windows.net
oaasguestconfigccs1.blob.core.windows.net
oaasguestconfigces1.blob.core.windows.net
oaasguestconfigcids1.blob.core.windows.net
oaasguestconfigcuss1.blob.core.windows.net
oaasguestconfigeaps1.blob.core.windows.net
oaasguestconfigeas1.blob.core.windows.net
oaasguestconfigeus2s1.blob.core.windows.net
oaasguestconfigeuss1.blob.core.windows.net
oaasguestconfigfcs1.blob.core.windows.net
oaasguestconfigfss1.blob.core.windows.net
oaasguestconfiggewcs1.blob.core.windows.net
oaasguestconfiggns1.blob.core.windows.net
oaasguestconfiggwcs1.blob.core.windows.net
oaasguestconfigjiws1.blob.core.windows.net
oaasguestconfigjpes1.blob.core.windows.net
oaasguestconfigjpws1.blob.core.windows.net
oaasguestconfigkcs1.blob.core.windows.net
oaasguestconfigkss1.blob.core.windows.net
oaasguestconfigncuss1.blob.core.windows.net
oaasguestconfignes1.blob.core.windows.net
oaasguestconfignres1.blob.core.windows.net
oaasguestconfignrws1.blob.core.windows.net
oaasguestconfigqacs1.blob.core.windows.net
oaasguestconfigsans1.blob.core.windows.net
oaasguestconfigscuss1.blob.core.windows.net
oaasguestconfigseas1.blob.core.windows.net
oaasguestconfigsecs1.blob.core.windows.net
oaasguestconfigsfns1.blob.core.windows.net
oaasguestconfigsfws1.blob.core.windows.net
oaasguestconfigsids1.blob.core.windows.net
oaasguestconfigstzns1.blob.core.windows.net
oaasguestconfigswcs1.blob.core.windows.net
oaasguestconfigswns1.blob.core.windows.net
oaasguestconfigswss1.blob.core.windows.net
oaasguestconfigswws1.blob.core.windows.net
oaasguestconfiguaecs1.blob.core.windows.net
oaasguestconfiguaens1.blob.core.windows.net
oaasguestconfigukss1.blob.core.windows.net
oaasguestconfigukws1.blob.core.windows.net
oaasguestconfigwcuss1.blob.core.windows.net
oaasguestconfigwes1.blob.core.windows.net
oaasguestconfigwids1.blob.core.windows.net
oaasguestconfigwus2s1.blob.core.windows.net
oaasguestconfigwus3s1.blob.core.windows.net
oaasguestconfigwuss1.blob.core.windows.net
To communicate with the machine 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 Azure Storage hosts the machine configuration content packages.
Virtual machines can use private link for communication to the machine configuration service.
Apply tag with the name EnablePrivateNetworkGC
and value TRUE
to enable this feature. The tag
can be applied before or after machine configuration policy definitions are applied to the machine.
Svarbu
To communicate over private link for custom packages, the link to the location of the package must be added to the list of allowed URLs.
Traffic is routed using the Azure virtual public IP address to establish a secure, authenticated channel with Azure platform resources.
Servers located on-premises or in other clouds can be managed with machine configuration by connecting them to Azure Arc.
For Azure Arc-enabled servers, allow traffic using the following patterns:
- Port: Only TCP 443 required for outbound internet access
- Global URL:
*.guestconfiguration.azure.com
See the Azure Arc-enabled servers network requirements for a full list of all network endpoints required by the Azure Connected Machine Agent for core Azure Arc and machine configuration scenarios.
When you use private link with Arc-enabled servers, built-in policy packages are automatically downloaded over the private link. You don't need to set any tags on the Arc-enabled server to enable this feature.
The Audit policy definitions available for machine configuration include the Microsoft.HybridCompute/machines resource type. Any machines onboarded to Azure Arc-enabled servers that are in the scope of the policy assignment are automatically included.
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.
Svarbu
These definitions create a System-Assigned managed identity on the target resources, in addition to existing User-Assigned Identities (if any). For existing applications unless they specify the User-Assigned identity in the request, the machine will default to using System-Assigned Identity instead. Learn More
If the machine doesn't currently have any managed identities, the effective policy 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 effective policy is: Add system-assigned managed identity to enable Guest Configuration assignments on VMs with a user-assigned identity
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 into an Azure region that's paired, you can view guest assignment reports if at least one region in the pair is available. When the Azure region isn't paired and it becomes unavailable, you can't access reports for a guest assignment. When the region is restored, you can access the reports again.
It's best practice to assign the same policy definitions with the same parameters to all machines in the solution for highly available applications. This is especially true for scenarios where virtual machines are provisioned in Availability Sets behind a load balancer solution. A single policy assignment spanning all machines has the least administrative overhead.
For machines protected by Azure Site Recovery, ensure that the machines in the primary and secondary site are within scope of Azure Policy assignments for the same definitions. Use the same parameter values for both sites.
Machine configuration stores and processes customer data. By default, customer data is replicated to the paired region. For the regions Singapore, Brazil South, and East Asia, all customer data is stored and processed in the region.
For more information about troubleshooting machine configuration, see Azure Policy troubleshooting.
At this time, only some built-in machine configuration policy definitions support multiple assignments. However, all custom policies support multiple assignments by default if you used the latest version of the GuestConfiguration PowerShell module to create machine configuration packages and policies.
Following is the list of built-in machine configuration policy definitions that support multiple assignments:
ID | DisplayName |
---|---|
/providers/Microsoft.Authorization/policyDefinitions/5fe81c49-16b6-4870-9cee-45d13bf902ce | Local authentication methods should be disabled on Windows Servers |
/providers/Microsoft.Authorization/policyDefinitions/fad40cac-a972-4db0-b204-f1b15cced89a | Local authentication methods should be disabled on Linux machines |
/providers/Microsoft.Authorization/policyDefinitions/f40c7c00-b4e3-4068-a315-5fe81347a904 | [Preview]: Add user-assigned managed identity to enable Guest Configuration assignments on virtual machines |
/providers/Microsoft.Authorization/policyDefinitions/63594bb8-43bb-4bf0-bbf8-c67e5c28cb65 | [Preview]: Linux machines should meet STIG compliance requirement for Azure compute |
/providers/Microsoft.Authorization/policyDefinitions/50c52fc9-cb21-4d99-9031-d6a0c613361c | [Preview]: Windows machines should meet STIG compliance requirements for Azure compute |
/providers/Microsoft.Authorization/policyDefinitions/e79ffbda-ff85-465d-ab8e-7e58a557660f | [Preview]: Linux machines with OMI installed should have version 1.6.8-1 or later |
/providers/Microsoft.Authorization/policyDefinitions/934345e1-4dfb-4c70-90d7-41990dc9608b | Audit Windows machines that do not contain the specified certificates in Trusted Root |
/providers/Microsoft.Authorization/policyDefinitions/08a2f2d2-94b2-4a7b-aa3b-bb3f523ee6fd | Audit Windows machines on which the DSC configuration is not compliant |
/providers/Microsoft.Authorization/policyDefinitions/c648fbbb-591c-4acd-b465-ce9b176ca173 | Audit Windows machines that do not have the specified Windows PowerShell execution policy |
/providers/Microsoft.Authorization/policyDefinitions/3e4e2bd5-15a2-4628-b3e1-58977e9793f3 | Audit Windows machines that do not have the specified Windows PowerShell modules installed |
/providers/Microsoft.Authorization/policyDefinitions/58c460e9-7573-4bb2-9676-339c2f2486bb | Audit Windows machines on which Windows Serial Console is not enabled |
/providers/Microsoft.Authorization/policyDefinitions/e6ebf138-3d71-4935-a13b-9c7fdddd94df | Audit Windows machines on which the specified services are not installed and 'Running' |
/providers/Microsoft.Authorization/policyDefinitions/c633f6a2-7f8b-4d9e-9456-02f0f04f5505 | Audit Windows machines that are not set to the specified time zone |
Pastaba
Please check this page periodically for updates to the list of built-in machine configuration policy definitions that support multiple assignments.
Azure Policy definitions in the category Guest Configuration
can be assigned to management groups
when the effect is AuditIfNotExists
or DeployIfNotExists
.
The machine configuration extension writes log files to the following locations:
Windows
- Azure VM:
C:\ProgramData\GuestConfig\gc_agent_logs\gc_agent.log
- Arc-enabled server:
C:\ProgramData\GuestConfig\arc_policy_logs\gc_agent.log
Linux
- Azure VM:
/var/lib/GuestConfig/gc_agent_logs/gc_agent.log
- Arc-enabled server:
/var/lib/GuestConfig/arc_policy_logs/gc_agent.log
The first step in troubleshooting machine configurations or modules should be to use the cmdlets following the steps in How to test machine configuration package artifacts. 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
$params = @{
Path = 'C:\ProgramData\GuestConfig\gc_agent_logs\gc_agent.log'
Pattern = @(
'DSCEngine'
'DSCManagedEngine'
)
CaseSensitive = $true
Context = @(
$linesToIncludeBeforeMatch
$linesToIncludeAfterMatch
)
}
Select-String @params | Select-Object -Last 10
Capture information from log files using Azure VM Run Command, the following example Bash script can be helpful.
LINES_TO_INCLUDE_BEFORE_MATCH=0
LINES_TO_INCLUDE_AFTER_MATCH=10
LOGPATH=/var/lib/GuestConfig/gc_agent_logs/gc_agent.log
egrep -B $LINES_TO_INCLUDE_BEFORE_MATCH -A $LINES_TO_INCLUDE_AFTER_MATCH 'DSCEngine|DSCManagedEngine' $LOGPATH | tail
The machine configuration agent downloads content packages to a machine and extracts the contents. To verify what content has been downloaded and stored, view the folder locations in the following list.
- Windows:
C:\ProgramData\guestconfig\configuration
- Linux:
/var/lib/GuestConfig/Configuration
A new open-source nxtools module has been released to help make managing Linux systems easier for PowerShell users.
The module helps in managing common tasks such as:
- Managing users and groups
- Performing file system operations
- Managing services
- Performing archive operations
- Managing packages
The module includes class-based DSC resources for Linux and built-in machine configuration packages.
To provide feedback about this functionality, open an issue on the documentation. We currently don't accept PRs for this project, and support is best effort.
Machine configuration built-in policy samples are available in the following locations:
- Built-in policy definitions - Guest Configuration
- Built-in initiatives - Guest Configuration
- Azure Policy samples GitHub repository
- Sample DSC resource modules
- Set up a custom machine configuration package development environment.
- Create a package artifact for machine configuration.
- Test the package artifact from your development environment.
- Use the GuestConfiguration module to create an Azure Policy definition for at-scale management of your environment.
- Assign your custom policy definition using Azure portal.
- Learn how to view compliance details for machine configuration policy assignments.