How to create a guest configuration assignment using templates
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
- Read the guest configuration overview.
- Setup a custom guest configuration package development environment.
- Create a package artifact for guest configuration.
- Test the package artifact from your development environment.
- Publish the package artifact so it is accessible to your machines.
- 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 guest configuration policy assignments.