How to create a guest configuration assignment using templates

  • Article

The best way to assign guest configuration packages to multiple machines is using Azure Policy. You can also assign guest configuration packages to a single machine.

Built-in and custom configurations

To assign a guest configuration package to a single machine, modify the following examples. There are one scenarios.

  • Apply a custom configuration to a machine using a link to a package that you published.

Extending other resource types

In each of the following sections, the example includes a type property where the name starts with Microsoft.Compute/virtualMachines. The guest configuration resource provider Microsoft.GuestConfiguration is an extension resource that must reference a parent type.

Replace the following "<>" fields with values specific to you environment:

  • <vm_name>: Name of the machine resource where the configuration will be applied
  • <configuration_name>: Name of the configuration to apply
  • <vm_location>: Azure region where the guest configuration assignment will be created
  • <Url_to_Package.zip>: For custom content package, an HTTPS link to the .zip file
  • <SHA256_hash_of_package.zip>: For custom content package, a SHA256 hash of the .zip file

Assign a configuration using an Azure Resource Manager template

You can deploy an Azure Resource Manager template containing guest configuration assignment resources.

The following example assigns a custom configuration.

{
    "apiVersion": "2020-06-25",
    "type": "Microsoft.Compute/virtualMachines/providers/guestConfigurationAssignments",
    "name": "<vm_name>/Microsoft.GuestConfiguration/<configuration_name>",
    "location": "<vm_location>",
    "dependsOn": [
        "Microsoft.Compute/virtualMachines/<vm_name>"
    ],
    "properties": {
        "guestConfiguration": {
            "name": "<configuration_name>",
            "contentUri": "<Url_to_Package.zip>",
            "contentHash": "<SHA256_hash_of_package.zip>",
            "assignmentType": "ApplyAndMonitor"
        }
    }
}

The following example assigns the AzureWindowBaseline built-in configuration.

{
    "apiVersion": "2020-06-25",
    "type": "Microsoft.Compute/virtualMachines/providers/guestConfigurationAssignments",
    "name": "<vm_name>/Microsoft.GuestConfiguration/<configuration_name>",
    "location": "<vm_location>",
    "dependsOn": [
        "Microsoft.Compute/virtualMachines/<vm_name>"
    ],
    "properties": {
        "guestConfiguration": {
            "name": "AzureWindowsBaseline",
            "version": "1.*",
            "assignmentType": "ApplyAndMonitor",
            "configurationParameter": [
            {
                "name": "Minimum Password Length;ExpectedValue",
                "value": "16"
            },
            {
                "name": "Minimum Password Length;RemediateValue",
                "value": "16"
            },
            {
                "name": "Maximum Password Age;ExpectedValue",
                "value": "75"
            },
            {
                "name": "Maximum Password Age;RemediateValue",
                "value": "75"
            }
        ]
        }
    }
}

Assign a configuration using Bicep

You can use Azure Bicep to deploy guest configuration assignments.

The following example assigns a custom configuration.

resource myVM 'Microsoft.Compute/virtualMachines@2021-03-01' existing = {
  name: '<vm_name>'
}

resource myConfiguration 'Microsoft.GuestConfiguration/guestConfigurationAssignments@2020-06-25' = {
  name: '<configuration_name>'
  scope: myVM
  location: resourceGroup().location
  properties: {
    guestConfiguration: {
      name: '<configuration_name>'
      contentUri: '<Url_to_Package.zip>'
      contentHash: '<SHA256_hash_of_package.zip>'
      version: '1.*'
      assignmentType: 'ApplyAndMonitor'
    }
  }
}

The following example assigns the AzureWindowBaseline built-in configuration.

resource myWindowsVM 'Microsoft.Compute/virtualMachines@2021-03-01' existing = {
  name: '<vm_name>'
}

resource AzureWindowsBaseline 'Microsoft.GuestConfiguration/guestConfigurationAssignments@2020-06-25' = {
  name: 'AzureWindowsBaseline'
  scope: myWindowsVM
  location: resourceGroup().location
  properties: {
    guestConfiguration: {
      name: 'AzureWindowsBaseline'
      version: '1.*'
      assignmentType: 'ApplyAndMonitor'
      configurationParameter: [
        {
          name: 'Minimum Password Length;ExpectedValue'
          value: '16'
        }
        {
          name: 'Minimum Password Length;RemediateValue'
          value: '16'
        }
        {
          name: 'Maximum Password Age;ExpectedValue'
          value: '75'
        }
        {
          name: 'Maximum Password Age;RemediateValue'
          value: '75'
        }
      ]
    }
  }
}

Assign a configuration using Terraform

You can use Terraform to deploy guest configuration assignments.

Important

The Terraform provider azurerm_policy_virtual_machine_configuration_assignment hasn't been updated to support the assignmentType property so only configurations that perform audits are supported.

Please also be notice that we should add environment = "china" in provider resource when necessary.

provider "azurerm" {
  ....
  environment  = "china"
  subscription_id = "<your_subscription_id>"
  ....
  features {}
}

The following example assigns a custom configuration.

resource "azurerm_virtual_machine_configuration_policy_assignment" "<configuration_name>" {
  name               = "<configuration_name>"
  location           = azurerm_windows_virtual_machine.example.location
  virtual_machine_id = azurerm_windows_virtual_machine.example.id
  configuration {
    name            = "<configuration_name>"
    contentUri      =  '<Url_to_Package.zip>'
    contentHash     =  '<SHA256_hash_of_package.zip>'
    version         = "1.*"
    assignmentType  = "ApplyAndMonitor
  }
}

The following example assigns the AzureWindowBaseline built-in configuration.

resource "azurerm_virtual_machine_configuration_policy_assignment" "AzureWindowsBaseline" {
  name               = "AzureWindowsBaseline"
  location           = azurerm_windows_virtual_machine.example.location
  virtual_machine_id = azurerm_windows_virtual_machine.example.id
  configuration {
    name    = "AzureWindowsBaseline"
    version = "1.*"
    parameter {
      name  = "Minimum Password Length;ExpectedValue"
      value = "16"
    }
    parameter {
      name  = "Minimum Password Length;RemediateValue"
      value = "16"
    }
    parameter {
      name  = "Minimum Password Age;ExpectedValue"
      value = "75"
    }
    parameter {
      name  = "Minimum Password Age;RemediateValue"
      value = "75"
    }
  }
}

Next steps