Tilbakemeldinger Rediger

Overview of the guest configuration extension

  • Artikkel
  • 4 minutter å lese

The Guest Configuration extension is a component of Azure Policy that performs audit and configuration operations inside virtual machines. Policies such as security baseline definitions for Linux and Windows can't check settings inside machines until the extension is installed.

Prerequisites

For the machine to authenticate to the Guest Configuration service, the machine must have a System-Assigned Managed Identity. The identity requirement on a virtual machine is met if the following property is set.

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

Operating Systems

Support for the Guest Configuration extension is the same as operating system support documented for the end to end solution.

Internet connectivity

The agent installed by the Guest Configuration extension must be able to reach content packages listed by Guest Configuration assignments, and report status to the Guest Configuration service. The machine can connect using outbound HTTPS over TCP port 443, or if a connection is provided through private networking. To learn more about private networking, see the following articles:

How can I install the extension?

The instance name of the extension must be set to "AzurePolicyforWindows" or "AzurePolicyforLinux", because the policies referenced above require these specific strings.

By default, all deployments update to the latest version. The value of property autoUpgradeMinorVersion defaults to "true" unless it is otherwise specified. You do not need to worry about updating your code when new versions of the extension are released.

Automatic upgrade

The guest configuration extension supports property enableAutomaticUpgrade. When this property is set to true, Azure will automatically upgrade to the latest version of the extension as future releases become available. For more information, see the page Automatic Extension Upgrade for VMs and Scale Sets in Azure

Azure Policy

To deploy the latest version of the extension at scale including identity requirements, assign the Azure Policy:

Deploy prerequisites to enable Guest Configuration policies on virtual machines.

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' -Type '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' -Type 'ConfigurationforWindows' -Name 'AzurePolicyforWindows' -TypeHandlerVersion 1.0 -ResourceGroupName 'myResourceGroup' -Location 'myLocation' -VMName 'myVM' -EnableAutomaticUpgrade $true

Resource Manager 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

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

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"
}

Settings

There's no need to include any settings or protected-settings properties on the extension. All such information is retrieved by the agent from Guest Configuration assignment resources. For example, the ConfigurationUri, Mode, and ConfigurationSetting properties are each managed per-configuration rather than on the VM extension.

Guest Configuration resource provider error codes

See below for a list of the possible error messages when enabling the extension

Error Code Description
NoComplianceReport VM has not reported the compliance data.
GCExtensionMissing Guest Configuration extension is missing.
ManagedIdentityMissing Managed identity is missing.
UserIdentityMissing User assigned identity is missing.
GCExtensionManagedIdentityMissing Guest Configuration extension and managed identity is missing.
GCExtensionUserIdentityMissing Guest Configuration extension and user identity is missing.
GCExtensionIdentityMissing Guest Configuration extension, managed identity and user identity are missing.

Next steps