Azure Machine Configuration

https://learn.microsoft.com/en-us/azure/governance/machine-configuration/
Admin
Azure Machine Configuration provides native capability to audit or configure operating system...
Tokens:31,350
Snippets:410
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Input for CIS Benchmarks for Linux

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/specify-custom-parameters-for-baseline-policy

This example demonstrates how to use the structured input format to specify parameters for a Linux service, including its name, expected state, and associated package.

```text
serviceName=named.service expectedUnitFileState=enabled expectedActiveState=active packageName=bind

```

--------------------------------

### Example Custom Input for Windows Security Baseline

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/specify-custom-parameters-for-baseline-policy

This example demonstrates how to apply a rule to specific server roles and OS versions. A wildcard '*' can be used for broader application.

```text
WindowsServer\2025\DomainController:1;WindowsServer\2025\MemberServer:1;WindowsServer\2022\:1
```

--------------------------------

### Configuration Parameter Example for Guest Assignment

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/concepts/assignments

This example shows how to define parameters to override DSC resource properties within a guest assignment configuration. Ensure the 'name' format is correct for targeting specific parameters.

```json
   "configurationParameter": [
        {
          "name": "[SecureWebServer]s1;MinimumTLSVersion",
          "value": "1.2"
        }
      ],

```

--------------------------------

### Install GuestConfiguration Module

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment

Install the machine configuration DSC resource module from the PowerShell Gallery. This module is required for creating and managing machine configurations.

```powershell
# Install the machine configuration DSC resource module from PowerShell Gallery
Install-Module -Name GuestConfiguration
```

--------------------------------

### Install PSDesiredStateConfiguration Module on Linux

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment

Install the prerelease version of the PSDesiredStateConfiguration module on Linux. Use the -AllowPrerelease flag for beta or release candidate versions.

```powershell
# Install PSDesiredStateConfiguration prerelease version 3.0.0
Install-Module -Name PSDesiredStateConfiguration -RequiredVersion 3.0.0-beta1 -AllowPrerelease
Import-Module -Name PSDesiredStateConfiguration
```

--------------------------------

### Install Az.Automation PowerShell Module

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/migrating-from-azure-automation

Install the Az.Automation PowerShell module to manage Azure Automation resources.

```powershell
Install-Module -Name Az.Automation

```

--------------------------------

### Install DSC Module for Windows

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Installs the PSDscResources module required for authoring Windows DSC configurations.

```PowerShell
Install-Module -Name PSDscResources
```

--------------------------------

### Install DSC Module for Linux

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Installs the nxtools module required for authoring Linux DSC configurations.

```PowerShell
Install-Module -Name nxtools
```

--------------------------------

### Example JSON for baselineSettings

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/understand-baseline-settings-parameter

This JSON structure defines a security baseline for Linux, including specific rules and their desired values.

```json
{
  "standard": "Microsoft",
  "baselineSettings": [
    {
      "name": "Azure Security Baseline for Linux",
      "version": "1.0.0",
      "settings": [
        {
          "ruleId": "35868e8c-97eb-4981-ab79-99b25101cc86",
          "name": "Ensure that the SSH protocol is configured;DesiredObjectValue",
          "value": "1"
        }
        // ...
      ]
    }
  ]
}
```

--------------------------------

### CIS Benchmarks (Linux) Settings Example

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/understand-baseline-settings-parameter

This JSON defines settings for CIS benchmarks on Linux. An empty 'settings' array applies all rules for that distribution, while a populated array applies only the specified rules. Omitting a distro block excludes it entirely.

```json
{
  "standard": "CIS",
  "baselineSettings": [
    {
      "name": "CIS Oracle Linux 8",
      "version": "3.0.0",
      "settings": [
        {
          "ruleId": "cis-ssh-5.2.1",
          "name": "Ensure SSH Protocol is set to 2",
          "value": "2"
        },
        {
          "ruleId": "cis-audit-4.1",
          "name": "Ensure auditing for processes that start prior to auditd",
          "value": "1"
        }
        // ....
      ]
    },
    {
      "name": "CIS AlmaLinux 8",
      "version": "3.0.0",
      "settings": [] // apply all settings as default
    }
  ]
}
```

--------------------------------

### Assign a built-in configuration using Bicep

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/bicep

This Bicep example assigns the `AzureWindowBaseline` built-in configuration to a Windows virtual machine. Parameters for the configuration can be specified within the `configurationParameter` block.

```bicep
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'
        }
      ]
    }
  }
}
```

--------------------------------

### Install PSDesiredStateConfiguration Module on Windows

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment

Install the stable release of the PSDesiredStateConfiguration module on Windows. This module is essential for defining and applying desired state configurations.

```powershell
# Install PSDesiredStateConfiguration version 2.0.7 (the stable release)
Install-Module -Name PSDesiredStateConfiguration -RequiredVersion 2.0.7
Import-Module -Name PSDesiredStateConfiguration
```

--------------------------------

### Custom Input Format for CIS Benchmarks for Linux

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/specify-custom-parameters-for-baseline-policy

This example shows the structured input format for advanced customization of parameter values in CIS Benchmarks for Linux. It allows specifying multiple attributes in a single line.

```text
key1=value1 key2=value2 key3=value3

```

--------------------------------

### Download and Install Modules from PowerShell Gallery

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/migrating-from-azure-automation

Pipes the output of `Find-Module` to `Install-Module` to load a local development environment with all modules currently in an Automation Account, provided they are available in the PowerShell Gallery. This approach can also be used for custom NuGet feeds after registering them as PowerShellGet repositories.

```powershell
Get-AzAutomationAccount |
    Get-AzAutomationModule |
    Where-Object IsGlobal -eq $false |
    Find-Module |
    Where-Object { '' -ne $_.Includes.DscResource } |
    Install-Module
```

--------------------------------

### Create an audit policy definition

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/create-policy-definition

Use this cmdlet to create a policy definition that audits a custom configuration package. Ensure the PolicyId is a unique GUID and the ContentUri points to the package.

```PowerShell
$PolicyConfig      = @{
  PolicyId      = '_My GUID_'
  ContentUri    = $contentUri
  DisplayName   = 'My audit policy'
  Description   = 'My audit policy'
  Path          = './policies/auditIfNotExists.json'
  Platform      = 'Windows'
  PolicyVersion = 1.0.0
}

New-GuestConfigurationPolicy @PolicyConfig

```

--------------------------------

### Assign a built-in configuration using Terraform

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/terraform

This example assigns the 'AzureWindowBaseline' built-in configuration. It configures specific parameters for password length and age.

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

```

--------------------------------

### Guest Assignment Metadata Example

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/concepts/assignments

This metadata is included when an Azure Policy is assigned and categorized as 'Guest Configuration'. It links a machine to an Azure Policy scenario.

```json
"metadata": {
    "category": "Guest Configuration",
    "guestConfiguration": {
        "name": "AzureWindowsBaseline",
        "version": "1.*"
    }
  }

```

--------------------------------

### Return reasons for machine configuration compliance

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/psdsc-in-machine-configuration

When authoring a custom DSC resource for machine configuration, the Get method must return a hash table including a 'Reasons' property. This property should be an array of hash tables, each with 'Code' and 'Phrase' keys, to explain compliance status.

```powershell
$reasons = @()
$reasons += @{
  Code   = 'Name:Name:ReasonIdentifier'
  Phrase = 'Explain why the setting is not compliant'
}
return @{
    reasons = $reasons
}

```

--------------------------------

### Azure Resource Manager Deployment Template for Guest Assignment

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/concepts/assignments

This is an example ARM template for creating a guest assignment resource. Ensure the contentUri points to a valid zip package and contentHash is the correct SHA256 hash.

```json
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "apiVersion": "2021-01-25",
      "type": "Microsoft.Compute/virtualMachines/providers/guestConfigurationAssignments",
      "name": "myMachine/Microsoft.GuestConfiguration/myConfig",
      "location": "westus2",
      "properties": {
        "guestConfiguration": {
          "name": "myConfig",
          "contentUri": "https://mystorageaccount.blob.core.windows.net/mystoragecontainer/myConfig.zip?sv=SASTOKEN",
          "contentHash": "SHA256HASH",
          "version": "1.0.0",
          "assignmentType": "ApplyAndMonitor",
          "configurationParameter": [
            "name":"configurationName",
            "value":"configurationValue"
          ]
        }
      }
    }
  ]
}

```

--------------------------------

### Create an enforcement policy definition

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/create-policy-definition

This cmdlet creates a policy definition that enforces a custom configuration package. Set the Mode to 'ApplyAndAutoCorrect' for enforcement. The PolicyId must be a unique GUID.

```PowerShell
$PolicyConfig2      = @{
  PolicyId      = '_My GUID_'
  ContentUri    = $contentUri
  DisplayName   = 'My deployment policy'
  Description   = 'My deployment policy'
  Path          = './policies/deployIfNotExists.json'
  Platform      = 'Windows'
  PolicyVersion = 1.0.0
  Mode          = 'ApplyAndAutoCorrect'
}

New-GuestConfigurationPolicy @PolicyConfig2

```

--------------------------------

### Validate package compliance status in Windows

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/3-test-package

Run this command in an elevated PowerShell 7 session on Windows to verify that the configuration package meets basic requirements. The machine configuration agent will be installed if it's not already present.

```powershell
# Get the current compliance results for the local machine
Get-GuestConfigurationPackageComplianceStatus -Path ./MyConfig.zip
```

--------------------------------

### Validate package compliance status in Linux

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/3-test-package

Execute this command using sudo in a Linux environment to check if the configuration package meets essential criteria. The machine configuration agent is installed automatically if needed.

```bash
# Get the current compliance results for the local machine
sudo pwsh -command 'Get-GuestConfigurationPackageComplianceStatus -Path ./MyConfig.zip'
```

--------------------------------

### Azure Security Baseline (Windows) Settings Example

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/understand-baseline-settings-parameter

This JSON configures Azure Security Baseline for Windows. The 'value' field uses a specific format for scoping rules by Windows Server version and role, supporting wildcards for broader application.

```json
{
  "standard": "Microsoft",
  "baselineSettings": [
    {
      "name": "Azure Security Baseline for Windows",
      "version": "1.0.0",
      "settings": [
        {
          "ruleId": "ab12cd34-5678-90ef-gh12-3456789ijklm",
          "name": "Ensure Windows Firewall is enabled for all profiles",
          "value": "WindowsServer\2025\*:1"
        }
        // .....
      ]
    }
  ]
}
```

--------------------------------

### Get content URI for machine configuration package

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/create-policy-definition

Use this PowerShell code to set the `$contentUri` variable if it's not already defined. It requires a storage account connection string, container name, and published package file name.

```powershell
$connectionString = '<storage-account-connection-string>'
$context = New-AzStorageContext -ConnectionString $connectionString
$getParams = @{
    Context   = $context
    Container = '<container-name>'
    Blob      = '<published-package-file-name>'
}
$blob = Get-AzStorageBlob @getParams
$contentUri = $blob.ICloudBlob.Uri.AbsoluteUri

```

--------------------------------

### Create a machine configuration package

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Use this cmdlet to create a machine configuration package. Specify the configuration MOF file, package type, and frequency for auditing.

```powershell
$params = @{
    Name          = 'MyConfig'
    Configuration = './MyConfig/MyConfig.mof'
    Type          = 'Audit'
    Force         = $true
    FrequencyMinutes = 180
}
New-GuestConfigurationPackage @params
```

--------------------------------

### Get Storage Account Context from Connection String

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/4-publish-package

Use this script to get the storage account context using a connection string. This is useful when working with an existing storage container.

```powershell
$connectionString = @(
    'DefaultEndPointsProtocol=https'
    'AccountName=<storage-account-name>'
    'AccountKey=<storage-key-for-the-account>'
) -join ';'
$context = New-AzStorageContext -ConnectionString $connectionString

```

--------------------------------

### Sign a Linux policy package using GPG

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/6-sign-package

This script outlines the steps to sign a Linux machine configuration package using GPG. It includes generating a GPG key pair, exporting the public and private keys, and then using the `Protect-GuestConfigurationPackage` cmdlet with the exported GPG key paths. Replace placeholders with your actual email address and file paths.

```powershell
# generate gpg key
gpg --gen-key

$emailAddress      = '<email-id-used-to-generate-gpg-key>'
$publicGpgKeyPath  = '<full-path-to-export-public-key-gpg-file>'
$privateGpgKeyPath = '<full-path-to-export-private-key-gpg-file>'

# export public key
gpg --output $publicGpgKeyPath --export $emailAddress

# export private key
gpg --output $privateGpgKeyPath --export-secret-key $emailAddress

# Sign linux policy package
Import-Module GuestConfiguration
$protectParams = @{
    Path              = '<path-to-package-to-sign>'
    PrivateGpgKeyPath = $privateGpgKeyPath
    PublicGpgKeyPath  = $publicGpgKeyPath
    Verbose           = $true
}
Protect-GuestConfigurationPackage

```

--------------------------------

### Test applying configuration on Linux

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/3-test-package

Use this command to test applying the machine configuration package on a local Linux machine. Run PowerShell using sudo. The command only outputs when errors occur.

```powershell
sudo pwsh -command 'Start-GuestConfigurationPackageRemediation -Path ./MyConfig.zip'
```

--------------------------------

### Create Audit and Apply Configuration Package

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Creates a machine configuration package artifact that will audit and apply the configuration if it's out of the desired state. The Force parameter overwrites existing packages.

```PowerShell
# Create a package that will audit and apply the configuration (Set)
$params = @{
    Name          = 'MyConfig'
    Configuration = './MyConfig/MyConfig.mof'
    Type          = 'AuditAndSet'
    Force         = $true
}
New-GuestConfigurationPackage @params

```

--------------------------------

### Create and use a self-signed certificate for Windows package signing

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/6-sign-package

This script demonstrates how to create a self-signed code signing certificate, export it, import it into the local machine's certificate store, and then use it to sign a machine configuration package for Windows. Ensure you replace placeholders with actual paths and provide a password when prompted.

```powershell
# How to create a self sign cert and use it to sign Machine Configuration
# custom policy package

# Create Code signing cert
$codeSigningParams = @{
    Type          = 'CodeSigningCert'
    DnsName       = 'GCEncryptionCertificate'
    HashAlgorithm = 'SHA256'
}
$certificate = New-SelfSignedCertificate @codeSigningParams

# Export the certificates
$privateKey = @{
    Cert     = $certificate
    Password = Read-Host "Enter password for private key" -AsSecureString
    FilePath = '<full-path-to-export-private-key-pfx-file>'
}
$publicKey = @{
    Cert     = $certificate
    FilePath = '<full-path-to-export-public-key-cer-file>'
    Force    = $true
}
Export-PfxCertificate @privateKey
Export-Certificate    @publicKey

# Import the certificate
$importParams = @{
    FilePath          = $privateKey.FilePath
    Password          = $privateKey.Password
    CertStoreLocation = 'Cert:\LocalMachine\My'
}
Import-PfxCertificate @importParams

# Sign the policy package
$certToSignThePackage = Get-ChildItem -Path Cert:\LocalMachine\My |
    Where-Object { $_.Subject -eq "CN=GCEncryptionCertificate" }
$protectParams = @{
    Path        = '<path-to-package-to-sign>'
    Certificate = $certToSignThePackage
    Verbose     = $true
}
Protect-GuestConfigurationPackage @protectParams

```

--------------------------------

### Calculate the uncompressed size of a package

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Get the total size of the uncompressed package contents in MB. This helps ensure the package does not exceed the 100 MB limit.

```powershell
Get-ChildItem -Recurse -Path .\MyConfigZip |
    Measure-Object -Sum Length |
    ForEach-Object -Process {
        $Size = [math]::Round(($_.Sum / 1MB), 2)
        "$Size MB"
    }
```

--------------------------------

### Assign a custom machine configuration using ARM template

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/azure-resource-manager

Use this template to assign a custom machine configuration. Replace placeholders like <vm_name>, <vm_location>, <Url_to_Package.zip>, and <SHA256_hash_of_package.zip> with your specific values.

```json
{
    "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"
        }
    }
}
```

--------------------------------

### Export Public Key from Signing Certificate

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/6-sign-package

Use this Azure PowerShell script to export the public key from your signing certificate. This key needs to be installed on the target machine.

```powershell
$Cert = Get-ChildItem -Path Cert:\LocalMachine\My |
    Where-Object { $_.Subject-eq 'CN=<CN-of-your-signing-certificate>' } |
    Select-Object -First 1

$Cert | Export-Certificate -FilePath '<path-to-export-public-key-cer-file>' -Force

```

--------------------------------

### Get Azure Automation Accounts

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/whats-new/migrating-from-azure-automation

Use Get-AzAutomationAccount to list your Automation Accounts and identify their Resource Group and Automation Account names. These properties are crucial for subsequent commands.

```powershell
Get-AzAutomationAccount

```

--------------------------------

### Prepare Baseline Settings JSON File

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-security-baselines/deploy-a-baseline-policy-assignment

This bash command sets a variable to the path of your customized baseline settings JSON file. Ensure this file is generated from the Azure portal.

```bash
baselineFile="./CustomizedBaselineSettings.json"

```

--------------------------------

### Get Storage Account Context from Container Object

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/4-publish-package

Retrieve the storage account context from a previously created storage container object. This context is needed for subsequent storage operations.

```powershell
$context = $container.Context

```

--------------------------------

### Test applying configuration on Windows

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/3-test-package

Use this command to test applying the machine configuration package on a local Windows machine. The command only outputs when errors occur.

```powershell
Start-GuestConfigurationPackageRemediation -Path ./MyConfig.zip
```

--------------------------------

### Assign a built-in configuration

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/rest-api

This example demonstrates how to assign the 'AuditSecureServer' built-in configuration to a machine using the Azure Rest API. It includes the HTTP PUT request and the required Authorization header.

```APIDOC
## PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{providerType}/{resourceName}/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/{assignmentName}

### Description
Assigns a built-in or custom configuration to a machine.

### Method
PUT

### Endpoint
`https://management.azure.com/subscriptions/<vm_Subscription>/resourceGroups/<vm_ResourceGroup>/providers/<providerType>/<vm_name>/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/<configuration_Name>?api-version=2022-01-25`

### Parameters
#### Path Parameters
- **<vm_Subscription>** (string) - Required - The subscription ID of the virtual machine.
- **<vm_ResourceGroup>** (string) - Required - The resource group of the virtual machine.
- **<providerType>** (string) - Required - The provider type, e.g., `Microsoft.Compute/virtualMachines` or `Microsoft.HybridCompute/machines`.
- **<vm_name>** (string) - Required - The name of the virtual machine or Arc-enabled server.
- **<configuration_Name>** (string) - Required - The name of the configuration to assign.

#### Query Parameters
- **api-version** (string) - Required - The API version, e.g., `2022-01-25`.

#### Request Body
- **Name** (string) - Required - The name of the Built-In Machine Configuration Package.
- **Location** (string) - Required - The location of the Hybrid Compute or Virtual Machine Resource.
- **Properties** (object) - Required - Contains the guest configuration assignment details.
  - **GuestConfiguration** (object) - Required - Defines the guest configuration details.
    - **Name** (string) - Required - The name of the Built-In Machine Configuration Package.
    - **Version** (string) - Required - The version of the package to use. Use `"1.*"` to always deploy the newest version.
    - **ContentUri** (string) - Optional - Required when assigning a custom package. URI of the package content.
    - **ContentHash** (string) - Optional - Required when assigning a custom package.
    - **ContentType** (string) - Optional - `BuiltIn` or `Custom`. Service sets this value automatically.
    - **AssignmentType** (string) - Required - Defines how the Guest Configuration agent processes the assignment. Valid values: `Audit`, `ApplyAndAutoCorrect`, `ApplyAndMonitor`, `ApplyOnce`.
    - **ConfigurationParameters** (array) - Optional - An array of key-value pairs for parameters.
    - **ConfigurationSettings** (object) - Optional - Defines other configuration options for the assignment.

### Request Example
```json
{
  "Name": "AuditSecureServer",
  "Location": "eastus",
  "Properties": {
    "GuestConfiguration": {
      "Name": "AuditSecureServer",
      "Version": "1.0.0",
      "AssignmentType": "Audit",
      "ConfigurationParameters": [
        {
          "Name": "parameter1",
          "Value": "value1"
        }
      ]
    }
  }
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The resource ID of the assignment.
- **name** (string) - The name of the assignment.
- **type** (string) - The resource type.
- **location** (string) - The location of the resource.
- **properties** (object) - The properties of the assignment.

#### Response Example
```json
{
  "id": "/subscriptions/<vm_Subscription>/resourceGroups/<vm_ResourceGroup>/providers/<providerType>/<vm_name>/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/AuditSecureServer",
  "name": "AuditSecureServer",
  "type": "Microsoft.GuestConfiguration/guestConfigurationAssignments",
  "location": "eastus",
  "properties": {
    "guestConfiguration": {
      "name": "AuditSecureServer",
      "version": "1.0.0",
      "assignmentType": "Audit"
    },
    "complianceStatus": "Pending",
    "lastComplianceReport": null
  }
}
```
```

--------------------------------

### Assign a built-in machine configuration using ARM template

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/azure-resource-manager

Use this template to assign a built-in configuration, such as AzureWindowsBaseline. You can specify version and configuration parameters for fine-grained control. Replace placeholders like <vm_name> and <vm_location>.

```json
{
    "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"
                }
            ]
        }
    }
}
```

--------------------------------

### Validate GuestConfiguration Module Import

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment

Verify that the GuestConfiguration module has been successfully imported by listing its available commands. This ensures the module is ready for use.

```powershell
# Get a list of commands for the imported GuestConfiguration module
Get-Command -Module GuestConfiguration
```

--------------------------------

### Expand a machine configuration package

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Expand the created package to inspect its contents. This is useful for verifying the structure and included modules.

```powershell
Expand-Archive -Path .\MyConfig.zip -DestinationPath MyConfigZip
```

--------------------------------

### Define policy parameters for machine configuration

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/create-policy-definition

This PowerShell script demonstrates how to define parameters for a machine configuration policy. It shows how to structure the parameter information as a hash table, including details like name, display name, description, resource type, resource ID, property name, default value, and allowed values.

```powershell
# This DSC resource definition...
Service 'UserSelectedNameExample' {
    Name   = 'ParameterValue'
    Ensure = 'Present'
    State  = 'Running'
}

# ...can be converted to a hash table:
$PolicyParameterInfo     = @(
  @{
    # Policy parameter name (mandatory)
    Name                 = 'ServiceName'
    # Policy parameter display name (mandatory)
    DisplayName          = 'windows service name.'
    # Policy parameter description (optional)
    Description          = 'Name of the windows service to be audited.'
    # DSC configuration resource type (mandatory)
    ResourceType         = 'Service'
    # DSC configuration resource id (mandatory)
    ResourceId           = 'UserSelectedNameExample'
    # DSC configuration resource property name (mandatory)
    ResourcePropertyName = 'Name'
    # Policy parameter default value (optional)
    DefaultValue         = 'winrm'
    # Policy parameter allowed values (optional)
    AllowedValues        = @('BDESVC','TermService','wuauserv','winrm')
  })

# ...and then passed into the `New-GuestConfigurationPolicy` cmdlet
$PolicyParam = @{
  PolicyId      = 'My GUID'
  ContentUri    = $contentUri
  DisplayName   = 'Audit Windows Service.'
  Description   = "Audit if a Windows Service isn't enabled on Windows machine."
  Path          = '.\policies\auditIfNotExists.json'
  Parameter     = $PolicyParameterInfo
  PolicyVersion = 1.0.0
}

New-GuestConfigurationPolicy @PolicyParam

```

--------------------------------

### Create Guest Configuration Package with Versioned Name

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/create-policy-definition

When creating a guest configuration package, include a version number in the package name to make it unique from earlier versions. This helps in managing custom content versions.

```powershell
New-GuestConfigurationPackage -Name "PackageName_1.0.0" -ContentPath "./content" -OutputDirectory "./out"
```

--------------------------------

### Compile DSC Configuration

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package

Compiles the DSC configuration script into a .mof file.

```PowerShell
. \MyConfig.ps1

```

--------------------------------

### Assign a custom configuration using Bicep

Source: https://learn.microsoft.com/en-us/azure/governance/machine-configuration/how-to/assign-configuration/bicep

Use this Bicep snippet to assign a custom machine configuration to a virtual machine. Ensure the `contentUri` points to a valid `.zip` package and `contentHash` matches its SHA256 hash.

```bicep
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'
    }
  }
}
```
Tokens:
Raw