Guest Configuration Assignments - Create Or Update

Creates an association between a VM and guest configuration

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/{guestConfigurationAssignmentName}?api-version=2024-04-05

URI Parameters

Name In Required Type Description
guestConfigurationAssignmentName
path True

string

Name of the guest configuration assignment.

resourceGroupName
path True

string

The resource group name.

Regex pattern: ^[-\w\._]+$

subscriptionId
path True

string

Subscription ID which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

vmName
path True

string

The name of the virtual machine.

Regex pattern: ^[a-zA-Z0-9][-a-zA-Z0-9_.]*[a-zA-Z0-9]$

api-version
query True

string

Client Api Version.

Request Body

Name Type Description
location

string

Region where the VM is located.

name

string

Name of the guest configuration assignment.

properties

GuestConfigurationAssignmentProperties

Properties of the Guest configuration assignment.

Responses

Name Type Description
200 OK

GuestConfigurationAssignment

OK. The guest configuration assignment for the VM was updated successfully.

201 Created

GuestConfigurationAssignment

Created. The guest configuration assignment for the VM was created successfully.

Other Status Codes

ErrorResponse

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create or update guest configuration assignment

Sample request

PUT https://management.azure.com/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myVMName/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/NotInstalledApplicationForWindows?api-version=2024-04-05

{
  "location": "westcentralus",
  "name": "NotInstalledApplicationForWindows",
  "properties": {
    "context": "Azure policy",
    "guestConfiguration": {
      "name": "NotInstalledApplicationForWindows",
      "version": "1.0.0.3",
      "contentUri": "https://thisisfake/pacakge",
      "contentHash": "123contenthash",
      "assignmentType": "ApplyAndAutoCorrect",
      "contentManagedIdentity": "test_identity",
      "configurationParameter": [
        {
          "name": "[InstalledApplication]NotInstalledApplicationResource1;Name",
          "value": "NotePad,sql"
        }
      ]
    }
  }
}

Sample response

{
  "location": "westcentralus",
  "id": "/subscriptions/mysubscriptionid/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myvm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/NotInstalledApplicationForWindows",
  "name": "NotInstalledApplicationForWindows",
  "properties": {
    "complianceStatus": "Pending",
    "assignmentHash": null,
    "latestReportId": null,
    "lastComplianceStatusChecked": null,
    "context": "Azure policy",
    "resourceType": null,
    "vmssVMList": null,
    "guestConfiguration": {
      "kind": null,
      "name": "NotInstalledApplicationForWindows",
      "version": "1.0.0.3",
      "contentUri": null,
      "contentHash": null,
      "contentType": null,
      "contentManagedIdentity": null,
      "assignmentSource": "AzurePolicy",
      "configurationParameter": [
        {
          "name": "[InstalledApplication]NotInstalledApplicationResource1;Name",
          "value": "NotePad,sql"
        }
      ]
    },
    "provisioningState": "Succeeded"
  }
}
{
  "location": "westcentralus",
  "id": "/subscriptions/mysubscriptionid/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myvm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/NotInstalledApplicationForWindows",
  "name": "NotInstalledApplicationForWindows",
  "properties": {
    "complianceStatus": "Pending",
    "assignmentHash": null,
    "latestReportId": null,
    "lastComplianceStatusChecked": null,
    "context": "Azure policy",
    "resourceType": null,
    "vmssVMList": null,
    "guestConfiguration": {
      "kind": null,
      "name": "NotInstalledApplicationForWindows",
      "version": "1.0.0.3",
      "contentUri": null,
      "contentHash": null,
      "contentType": null,
      "contentManagedIdentity": null,
      "assignmentSource": "AzurePolicy",
      "configurationParameter": [
        {
          "name": "[InstalledApplication]NotInstalledApplicationResource1;Name",
          "value": "NotePad,sql"
        }
      ]
    },
    "provisioningState": "Succeeded"
  }
}

Definitions

Name Description
actionAfterReboot

Specifies what happens after a reboot during the application of a configuration. The possible values are ContinueConfiguration and StopConfiguration

AssignmentInfo

Information about the guest configuration assignment.

AssignmentReport
AssignmentReportResource

The guest configuration assignment resource.

AssignmentReportResourceComplianceReason

Reason and code for the compliance of the guest configuration assignment resource.

assignmentType

Specifies the assignment type and execution of the configuration. Possible values are Audit, DeployAndAutoCorrect, ApplyAndAutoCorrect and ApplyAndMonitor.

complianceStatus

A value indicating compliance status of the machine for the assigned guest configuration.

ConfigurationInfo

Information about the configuration.

configurationMode

Specifies how the LCM(Local Configuration Manager) actually applies the configuration to the target nodes. Possible values are ApplyOnly, ApplyAndMonitor, and ApplyAndAutoCorrect.

ConfigurationParameter

Represents a configuration parameter.

ConfigurationSetting

Configuration setting of LCM (Local Configuration Manager).

createdByType

The type of identity that created the resource.

Error
ErrorResponse

Error response of an operation failure

GuestConfigurationAssignment

Guest configuration assignment is an association between a machine and guest configuration.

GuestConfigurationAssignmentProperties

Guest configuration assignment properties.

GuestConfigurationNavigation

Guest configuration is an artifact that encapsulates DSC configuration and its dependencies. The artifact is a zip file containing DSC configuration (as MOF) and dependent resources and other dependencies like modules.

kind

Kind of the guest configuration. For example:DSC

provisioningState

The provisioning state, which only appears in the response.

systemData

Metadata pertaining to creation and last modification of the resource.

type

Type of report, Consistency or Initial

VMInfo

Information about the VM.

VMSSVMInfo

Information about VMSS VM

actionAfterReboot

Specifies what happens after a reboot during the application of a configuration. The possible values are ContinueConfiguration and StopConfiguration

Name Type Description
ContinueConfiguration

string

StopConfiguration

string

AssignmentInfo

Information about the guest configuration assignment.

Name Type Description
configuration

ConfigurationInfo

Information about the configuration.

name

string

Name of the guest configuration assignment.

AssignmentReport

Name Type Description
assignment

AssignmentInfo

Configuration details of the guest configuration assignment.

complianceStatus

complianceStatus

A value indicating compliance status of the machine for the assigned guest configuration.

endTime

string

End date and time of the guest configuration assignment compliance status check.

id

string

ARM resource id of the report for the guest configuration assignment.

operationType

type

Type of report, Consistency or Initial

reportId

string

GUID that identifies the guest configuration assignment report under a subscription, resource group.

resources

AssignmentReportResource[]

The list of resources for which guest configuration assignment compliance is checked.

startTime

string

Start date and time of the guest configuration assignment compliance status check.

vm

VMInfo

Information about the VM.

AssignmentReportResource

The guest configuration assignment resource.

Name Type Description
complianceStatus

complianceStatus

A value indicating compliance status of the machine for the assigned guest configuration.

properties

object

Properties of a guest configuration assignment resource.

reasons

AssignmentReportResourceComplianceReason[]

Compliance reason and reason code for a resource.

resourceId

string

Name of the guest configuration assignment resource setting.

AssignmentReportResourceComplianceReason

Reason and code for the compliance of the guest configuration assignment resource.

Name Type Description
code

string

Code for the compliance of the guest configuration assignment resource.

phrase

string

Reason for the compliance of the guest configuration assignment resource.

assignmentType

Specifies the assignment type and execution of the configuration. Possible values are Audit, DeployAndAutoCorrect, ApplyAndAutoCorrect and ApplyAndMonitor.

Name Type Description
ApplyAndAutoCorrect

string

ApplyAndMonitor

string

Audit

string

DeployAndAutoCorrect

string

complianceStatus

A value indicating compliance status of the machine for the assigned guest configuration.

Name Type Description
Compliant

string

NonCompliant

string

Pending

string

ConfigurationInfo

Information about the configuration.

Name Type Description
name

string

Name of the configuration.

version

string

Version of the configuration.

configurationMode

Specifies how the LCM(Local Configuration Manager) actually applies the configuration to the target nodes. Possible values are ApplyOnly, ApplyAndMonitor, and ApplyAndAutoCorrect.

Name Type Description
ApplyAndAutoCorrect

string

ApplyAndMonitor

string

ApplyOnly

string

ConfigurationParameter

Represents a configuration parameter.

Name Type Description
name

string

Name of the configuration parameter.

value

string

Value of the configuration parameter.

ConfigurationSetting

Configuration setting of LCM (Local Configuration Manager).

Name Type Default value Description
actionAfterReboot

actionAfterReboot

Specifies what happens after a reboot during the application of a configuration. The possible values are ContinueConfiguration and StopConfiguration

allowModuleOverwrite

boolean

If true - new configurations downloaded from the pull service are allowed to overwrite the old ones on the target node. Otherwise, false

configurationMode

configurationMode

Specifies how the LCM(Local Configuration Manager) actually applies the configuration to the target nodes. Possible values are ApplyOnly, ApplyAndMonitor, and ApplyAndAutoCorrect.

configurationModeFrequencyMins

number

15

How often, in minutes, the current configuration is checked and applied. This property is ignored if the ConfigurationMode property is set to ApplyOnly. The default value is 15.

rebootIfNeeded

boolean

Set this to true to automatically reboot the node after a configuration that requires reboot is applied. Otherwise, you will have to manually reboot the node for any configuration that requires it. The default value is false. To use this setting when a reboot condition is enacted by something other than DSC (such as Windows Installer), combine this setting with the xPendingReboot module.

refreshFrequencyMins

number

30

The time interval, in minutes, at which the LCM checks a pull service to get updated configurations. This value is ignored if the LCM is not configured in pull mode. The default value is 30.

createdByType

The type of identity that created the resource.

Name Type Description
Application

string

Key

string

ManagedIdentity

string

User

string

Error

Name Type Description
code

string

Error code.

message

string

Detail error message indicating why the operation failed.

ErrorResponse

Error response of an operation failure

Name Type Description
error

Error

GuestConfigurationAssignment

Guest configuration assignment is an association between a machine and guest configuration.

Name Type Description
id

string

ARM resource id of the guest configuration assignment.

location

string

Region where the VM is located.

name

string

Name of the guest configuration assignment.

properties

GuestConfigurationAssignmentProperties

Properties of the Guest configuration assignment.

systemData

systemData

Azure Resource Manager metadata containing createdBy and modifiedBy information.

type

string

The type of the resource.

GuestConfigurationAssignmentProperties

Guest configuration assignment properties.

Name Type Description
assignmentHash

string

Combined hash of the configuration package and parameters.

complianceStatus

complianceStatus

A value indicating compliance status of the machine for the assigned guest configuration.

context

string

The source which initiated the guest configuration assignment. Ex: Azure Policy

guestConfiguration

GuestConfigurationNavigation

The guest configuration to assign.

lastComplianceStatusChecked

string

Date and time when last compliance status was checked.

latestAssignmentReport

AssignmentReport

Last reported guest configuration assignment report.

latestReportId

string

Id of the latest report for the guest configuration assignment.

parameterHash

string

parameter hash for the guest configuration assignment.

provisioningState

provisioningState

The provisioning state, which only appears in the response.

resourceType

string

Type of the resource - VMSS / VM

targetResourceId

string

VM resource Id.

vmssVMList

VMSSVMInfo[]

The list of VM Compliance data for VMSS

GuestConfigurationNavigation

Guest configuration is an artifact that encapsulates DSC configuration and its dependencies. The artifact is a zip file containing DSC configuration (as MOF) and dependent resources and other dependencies like modules.

Name Type Description
assignmentSource

string

Specifies the origin of the configuration.

assignmentType

assignmentType

Specifies the assignment type and execution of the configuration. Possible values are Audit, DeployAndAutoCorrect, ApplyAndAutoCorrect and ApplyAndMonitor.

configurationParameter

ConfigurationParameter[]

The configuration parameters for the guest configuration.

configurationProtectedParameter

ConfigurationParameter[]

The protected configuration parameters for the guest configuration.

configurationSetting

ConfigurationSetting

The configuration setting for the guest configuration.

contentHash

string

Combined hash of the guest configuration package and configuration parameters.

contentManagedIdentity

string

Managed identity with storage access of the guest configuration package and configuration parameters.

contentType

string

Specifies the content type of the configuration. Possible values could be Builtin or Custom.

contentUri

string

Uri of the storage where guest configuration package is uploaded.

kind

kind

Kind of the guest configuration. For example:DSC

name

string

Name of the guest configuration.

version

string

Version of the guest configuration.

kind

Kind of the guest configuration. For example:DSC

Name Type Description
DSC

string

provisioningState

The provisioning state, which only appears in the response.

Name Type Description
Canceled

string

Created

string

Failed

string

Succeeded

string

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string

The timestamp of resource creation (UTC).

createdBy

string

The identity that created the resource.

createdByType

createdByType

The type of identity that created the resource.

lastModifiedAt

string

The timestamp of resource last modification (UTC)

lastModifiedBy

string

The identity that last modified the resource.

lastModifiedByType

createdByType

The type of identity that last modified the resource.

type

Type of report, Consistency or Initial

Name Type Description
Consistency

string

Initial

string

VMInfo

Information about the VM.

Name Type Description
id

string

Azure resource Id of the VM.

uuid

string

UUID(Universally Unique Identifier) of the VM.

VMSSVMInfo

Information about VMSS VM

Name Type Description
complianceStatus

complianceStatus

A value indicating compliance status of the machine for the assigned guest configuration.

lastComplianceChecked

string

Date and time when last compliance status was checked.

latestReportId

string

Id of the latest report for the guest configuration assignment.

vmId

string

UUID of the VM.

vmResourceId

string

Azure resource Id of the VM.