Guest Configuration Assignments - Create Or Update

Reference

Service:: Guest Configuration

API Version:: 2024-04-05

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

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"
        }
      ]
    }
  }
}

using Azure;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager.GuestConfiguration.Models;
using Azure.ResourceManager.GuestConfiguration;

// Generated from example definition: specification/guestconfiguration/resource-manager/Microsoft.GuestConfiguration/stable/2024-04-05/examples/createOrUpdateGuestConfigurationAssignment.json
// this example is just showing the usage of "GuestConfigurationAssignments_CreateOrUpdate" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://video2.skills-academy.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this ArmResource created on azure
// for more information of creating ArmResource, please refer to the document of ArmResource

// get the collection of this GuestConfigurationVmAssignmentResource
string subscriptionId = "mySubscriptionId";
string resourceGroupName = "myResourceGroupName";
string vmName = "myVMName";
ResourceIdentifier scopeId = new ResourceIdentifier(string.Format("/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Compute/virtualMachines/{2}", subscriptionId, resourceGroupName, vmName));
GuestConfigurationVmAssignmentCollection collection = client.GetGuestConfigurationVmAssignments(scopeId);

// invoke the operation
string guestConfigurationAssignmentName = "NotInstalledApplicationForWindows";
GuestConfigurationAssignmentData data = new GuestConfigurationAssignmentData()
{
    Properties = new GuestConfigurationAssignmentProperties()
    {
        GuestConfiguration = new GuestConfigurationNavigation()
        {
            Name = "NotInstalledApplicationForWindows",
            Version = "1.0.0.3",
            ContentUri = new Uri("https://thisisfake/pacakge"),
            ContentHash = "123contenthash",
            ContentManagedIdentity = "test_identity",
            AssignmentType = GuestConfigurationAssignmentType.ApplyAndAutoCorrect,
            ConfigurationParameters =
            {
            new GuestConfigurationParameter()
            {
            Name = "[InstalledApplication]NotInstalledApplicationResource1;Name",
            Value = "NotePad,sql",
            }
            },
        },
        Context = "Azure policy",
    },
    Name = "NotInstalledApplicationForWindows",
    Location = new AzureLocation("westcentralus"),
};
ArmOperation<GuestConfigurationVmAssignmentResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, guestConfigurationAssignmentName, data);
GuestConfigurationVmAssignmentResource result = lro.Value;

// the variable result is a resource, you could call other operations on this instance as well
// but just for demo, we get its data from this resource instance
GuestConfigurationAssignmentData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample response

Status code:: 201

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

Status code:: 200

{
  "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