Azure Machine Configuration extension

The Machine Configuration extension performs audit and configuration operations inside virtual machines (VMs).

Prerequisites

To enable your VM to authenticate to the Machine Configuration service, your VM must have a system-assigned managed identity. You can satisfy the identity requirement for your VM by setting the "type": "SystemAssigned" property:

"identity": {
   "type": "SystemAssigned"
}

Operating systems

Operating system support for the Machine Configuration extension is the same as documented operating system support for the end-to-end solution.

Internet connectivity

The agent installed by the Machine Configuration extension must be able to reach content packages listed by guest configuration assignments, and report status to the Machine Configuration service. The VM can connect by using outbound HTTPS over TCP port 443, or a connection provided through private networking.

To learn more about private networking, see the following articles:

• Use private endpoints for Azure Storage

Install the extension

You can install and deploy the Machine Configuration extension directly from the Azure CLI or PowerShell. Deployment templates are also available for Azure Resource Manager (ARM), Bicep, and Terraform. For deployment template details, see Microsoft.GuestConfiguration guestConfigurationAssignments.

Deployment considerations

Before you install and deploy the Machine Configuration extension, review the following considerations.

• Instance name. When you install the Machine Configuration extension, the instance name of the extension must be set to AzurePolicyforWindows or AzurePolicyforLinux. The security baseline definition policies described earlier require these specific strings.

• Versions. By default, all deployments update to the latest version. The value of the autoUpgradeMinorVersion property defaults to true unless otherwise specified. This feature helps to alleviate concerns about updating your code when new versions of the Machine Configuration extension are released.

• Automatic upgrade. The Machine Configuration extension supports the enableAutomaticUpgrade property. When this property is set to true, Azure automatically upgrades to the latest version of the extension as future releases become available.

• Azure Policy. To deploy the latest version of the Machine Configuration extension at scale including identity requirements, follow the steps in Create a policy assignment to identify noncompliant resources. Create the following assignment with Azure Policy:

  • Deploy prerequisites to enable Guest Configuration policies on virtual machines

• Other properties. You don't need to include any settings or protected-settings properties on the Machine Configuration extension. The agent retrieves this class of information from the Azure REST API Guest Configuration assignment resources. For example, the ConfigurationUri, Mode, and ConfigurationSetting properties are each managed per-configuration rather than on the VM extension.

Azure CLI

To deploy the extension for Linux:

az vm extension set  --publisher Microsoft.GuestConfiguration --name ConfigurationForLinux --extension-instance-name AzurePolicyforLinux --resource-group <myResourceGroup> --vm-name <myVM> --enable-auto-upgrade true

To deploy the extension for Windows:

az vm extension set  --publisher Microsoft.GuestConfiguration --name ConfigurationforWindows --extension-instance-name AzurePolicyforWindows --resource-group <myResourceGroup> --vm-name <myVM> --enable-auto-upgrade true

PowerShell

To deploy the extension for Linux:

Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -ExtensionType 'ConfigurationForLinux' -Name 'AzurePolicyforLinux' -TypeHandlerVersion 1.0 -ResourceGroupName '<myResourceGroup>' -Location '<myLocation>' -VMName '<myVM>' -EnableAutomaticUpgrade $true

To deploy the extension for Windows:

Set-AzVMExtension -Publisher 'Microsoft.GuestConfiguration' -ExtensionType 'ConfigurationforWindows' -Name 'AzurePolicyforWindows' -TypeHandlerVersion 1.0 -ResourceGroupName '<myResourceGroup>' -Location '<myLocation>' -VMName '<myVM>' -EnableAutomaticUpgrade $true

ARM template

To deploy the extension for Linux:

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/AzurePolicyforLinux')]",
  "apiVersion": "2020-12-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.GuestConfiguration",
    "type": "ConfigurationForLinux",
    "typeHandlerVersion": "1.0",
    "autoUpgradeMinorVersion": true,
    "enableAutomaticUpgrade": true, 
    "settings": {},
    "protectedSettings": {}
  }
}

To deploy the extension for Windows:

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/AzurePolicyforWindows')]",
  "apiVersion": "2020-12-01",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', parameters('VMName'))]"
  ],
  "properties": {
    "publisher": "Microsoft.GuestConfiguration",
    "type": "ConfigurationforWindows",
    "typeHandlerVersion": "1.0",
    "autoUpgradeMinorVersion": true,
    "enableAutomaticUpgrade": true, 
    "settings": {},
    "protectedSettings": {}
  }
}

Bicep template

To deploy the extension for Linux:

resource virtualMachine 'Microsoft.Compute/virtualMachines@2021-03-01' existing = {
  name: 'VMName'
}
resource windowsVMGuestConfigExtension 'Microsoft.Compute/virtualMachines/extensions@2020-12-01' = {
  parent: virtualMachine
  name: 'AzurePolicyforLinux'
  location: resourceGroup().location
  properties: {
    publisher: 'Microsoft.GuestConfiguration'
    type: 'ConfigurationForLinux'
    typeHandlerVersion: '1.0'
    autoUpgradeMinorVersion: true
    enableAutomaticUpgrade: true
    settings: {}
    protectedSettings: {}
  }
}

To deploy the extension for Windows:

resource virtualMachine 'Microsoft.Compute/virtualMachines@2021-03-01' existing = {
  name: 'VMName'
}
resource windowsVMGuestConfigExtension 'Microsoft.Compute/virtualMachines/extensions@2020-12-01' = {
  parent: virtualMachine
  name: 'AzurePolicyforWindows'
  location: resourceGroup().location
  properties: {
    publisher: 'Microsoft.GuestConfiguration'
    type: 'ConfigurationforWindows'
    typeHandlerVersion: '1.0'
    autoUpgradeMinorVersion: true
    enableAutomaticUpgrade: true
    settings: {}
    protectedSettings: {}
  }
}

Terraform template

To deploy the extension for Linux:

resource "azurerm_virtual_machine_extension" "gc" {
  name                       = "AzurePolicyforLinux"
  virtual_machine_id         = "<myVMID>"
  publisher                  = "Microsoft.GuestConfiguration"
  type                       = "ConfigurationForLinux"
  type_handler_version       = "1.0"
  auto_upgrade_minor_version = "true"
}

To deploy the extension for Windows:

resource "azurerm_virtual_machine_extension" "gc" {
  name                       = "AzurePolicyforWindows"
  virtual_machine_id         = "<myVMID>"
  publisher                  = "Microsoft.GuestConfiguration"
  type                       = "ConfigurationforWindows"
  type_handler_version       = "1.0"
  auto_upgrade_minor_version = "true"
}

Error messages

The following table lists possible error messages related to enabling the Guest Configuration extension.

Error code	Description
NoComplianceReport	The VM hasn't reported the compliance data.
GCExtensionMissing	The Machine Configuration (guest configuration) extension is missing.
ManagedIdentityMissing	The managed identity is missing.
UserIdentityMissing	The user-assigned identity is missing.
GCExtensionManagedIdentityMissing	The Machine Configuration (guest configuration) extension and managed identity are missing.
GCExtensionUserIdentityMissing	The Machine Configuration (guest configuration) extension and user-assigned identity are missing.
GCExtensionIdentityMissing	The Machine Configuration (guest configuration) extension, managed identity, and user-assigned identity are missing.

Next steps

• For more information about how the Linux Agent and extensions work, see Virtual machine extensions and features for Linux.
• For more information about how the Windows Guest Agent and extensions work, see Virtual machine extensions and features for Windows.
• To install the Windows Guest Agent, see Azure Virtual Machine Agent overview.
• To install the Linux Agent, see Understanding and using the Azure Linux Agent.