Azure Machine Configuration extension

1. Open the Azure portal.
2. In the search box, enter Virtual machines and then select Virtual machines to display the list of available VMs.
3. Select the virtual machines you want to use.
4. In the search box of virtual machine page, enter Extensions+applications and then select it.
5. Click on Add in the extensions page.
6. In the search box of extension page, enter Azure Machine Configuration extension for Windows or Azure Machine Configuration extension for Linux based on the OS type and select it.
7. Click Next and then select Review + create to install the extension.
8. Once validation passes, select Create.
9. Once installation finishes, you can see AzurePolicyforWindows or AzurePolicyforLinux extension installed in the extension page.

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

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

Deployment templates

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. For more information, see Automatic Extension Upgrade for VMs and Virtual Machine Scale Sets in Azure.

• 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.

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.

Next steps

• For more information about the Machine Configuration extension, see Understand Azure Machine Configuration.
• 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.