How to create a Machine Configuration Assignment using the Azure Rest API

This article shows examples for deploying built-in configurations and can be performed using cUrl or any http client of your choice.

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.

To modify the example for other resource types such as Arc-enabled servers, change the parent type to the name of the resource provider. For Arc-enabled servers, the resource provider is Microsoft.HybridCompute/machines.

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

  • <base_url> - The same for all requests, but be certain to update the provider to specify between Microsoft.Compute/virtualMachines or Microsoft.HybridCompute/machines as appropriate:

    https://management.azure.com/subscriptions/<vm_Subscription>/resourceGroups/<vm_ResourceGroup>/providers/<providerType>

  • <vm_name> - Specify the name of the Machine Resource for this assignment

  • <configuration_name> - Specify the name of the configuration to apply.

  • <api_version> - Select the appropriate API-version. The latest version is 2022-01-25.

Assign a built-in configuration

The following example assigns the AuditSecureServer built-in configuration.

HTTP PUT https://<baseUrl>/<vm_name>/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/<configuration_Name>?api-version=2022-01-25

This request requires authentication in the format of an authorization header. You can use the Get-AzAccessToken cmdlet to retrieve an Azure Access Token.

Authorization Bearer <yourTokenHere>

A request is composed of the following properties, which together make up a Machine Configuration Assignment.

Azure Resource properties

These fields are the top level of properties as depicted in the sample request, and is made of the following properties.

  • Name - The name of the Built-In Machine Configuration Package
  • Location - The location of the Hybrid Compute or Virtual Machine Resource
  • Guest Configuration Parameters - A JSON Object of additional parameters specific to Guest Configuration.

These parameters represent most of a Machine Configuration Assignment and are defined in the following list:

  • Name - The name of the Built-In Machine Configuration Package
  • Version - The version of the package to use. You can use "1.*" to always deploy the newest version of a package.
  • ContentUri - Required when assigning a custom package, this property defines the URI of an accessible location containing the package content.
  • ContentHash - Required when assigning a custom package.
  • ContentType - BuiltIn or Custom. The service sets this value automatically.
  • AssignmentType - Assigns one of the Assignment Types.
  • ConfigurationParameters - An array of parameters to pass in to the assignment. These differ per package.
  • ConfigurationSettings - Defines other configuration options for the assignment. For more information, see Configuration Setting

Toewijzingstype

An assignment type defines how the Guest Configuration agent should process the assignment. Geldige waarden zijn:

  • Audit - Only assess compliance with an assignment. Don't make any changes.
  • ApplyAndAutoCorrect - Continuously audit and autocorrect for compliance.
  • ApplyAndMonitor - Apply the settings once, then monitor for compliance but don't correct settings.
  • ApplyOnce - Apply the settings once.

Configuration parameter

An array of key-value pairs to pass into the Machine Configuration Assignment. For each pair:

  • The key defines the name of the parameter to configure.
  • The value defines the desired value to set or audit for the assignment.

Configuratie-instelling

These properties represent other configurable settings presented by Machine Configuration.

  • ConfigurationMode - Valid values are the same as Assignment type. This value must be the same as the value for Assignment Type.
  • ActionAfterReboot - Controls the action of the Machine Configuration Agent after applying a reboot.
  • RebootIfNeeded - If supported by the module, allows for suppressing of restarts if a reboot is needed.

Voorbeeld van aanvraag

let baseUrl = https://management.azure.com
let subscription = /subscriptions/<yourSubscription>
let resourceGroup = resourceGroups/<yourResourceGroup>
let provider = providers/Microsoft.Compute
let vm = <yourVm>

curl --request PUT \
  --url '$baseUrl/$subscription/$resourceGroup$/$providers/$vm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/AuditSecureProtocol?api-version=2022-01-25' \
  --header 'authorization: Bearer yourKeyHere \
  --header 'content-type: application/json' \
  --data '{
  "properties": {
    "guestConfiguration": {
      "kind": "Machine Configuration",
      "name": "AuditSecureProtocol",
      "version": "1.*",
      "contentType": "Builtin",
      "assignmentType": "Audit",
      "configurationParameter": [
        {
          "name": "[SecureWebServer]s1;MinimumTLSVersion",
          "value": "1.2"
        }
      ],
      "configurationProtectedParameter": [],
      "configurationSetting": {
        "configurationMode": "Audit",
        "allowModuleOverwrite": false,
        "actionAfterReboot": "",
        "refreshFrequencyMins": 5,
        "rebootIfNeeded": true,
        "configurationModeFrequencyMins": 15
      }
    },
    "complianceStatus": "Compliant",
    "assignmentHash": null,
    "provisioningState": "Succeeded",
    "resourceType": null,
    "vmssVMList": null
  },
  "name": "AuditSecureProtocol",
  "location": "westus2"
}'

Reactie

The response contains the created assignment. The response automatically defines every required parameter.

{
  "properties": {
    "name": "AuditSecureProtocol",
    "location": "<vmLocation",
    "guestConfiguration": {
      "name": "AuditSecureProtocol",
      "version": "1.*",
      "contentType": "Builtin",
      "assignmentType": null,
      "configurationParameter": [
        {
          "name": "[SecureWebServer]s1;MinimumTLSVersion",
          "value": "1.2"
        }
      ],
      "configurationSetting": {
        "configurationMode": "MonitorOnly",
        "allowModuleOverwrite": false,
        "actionAfterReboot": "",
        "refreshFrequencyMins": 5,
        "rebootIfNeeded": true,
        "configurationModeFrequencyMins": 15
      }
    }
  },
  "name": "AuditSecureProtocol",
  "location": "westus2"
}
  • Last updated on