Guest Configuration Assignments - List

Service:

Guest Configuration

API Version:

2022-01-25

List all guest configuration assignments for a virtual machine.

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments?api-version=2022-01-25

URI Parameters

Name	In	Required	Type	Description
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.

Responses

Name	Type	Description
200 OK	GuestConfigurationAssignmentList	OK
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

List all guest configuration assignments for a virtual machine

Sample request

HTTP

GET https://management.azure.com/subscriptions/mySubscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myVMName/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments?api-version=2022-01-25

Python

from azure.identity import DefaultAzureCredential
from azure.mgmt.guestconfig import GuestConfigurationClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-guestconfig
# USAGE
    python list_all_guest_configuration_assignments_for_a_virtual_machine.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = GuestConfigurationClient(
        credential=DefaultAzureCredential(),
        subscription_id="mySubscriptionId",
    )

    response = client.guest_configuration_assignments.list(
        resource_group_name="myResourceGroupName",
        vm_name="myVMName",
    )
    for item in response:
        print(item)


# x-ms-original-file: specification/guestconfiguration/resource-manager/Microsoft.GuestConfiguration/stable/2022-01-25/examples/listGuestConfigurationAssignments.json
if __name__ == "__main__":
    main()

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

Go

package armguestconfiguration_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/guestconfiguration/armguestconfiguration"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/7a2ac91de424f271cf91cc8009f3fe9ee8249086/specification/guestconfiguration/resource-manager/Microsoft.GuestConfiguration/stable/2022-01-25/examples/listGuestConfigurationAssignments.json
func ExampleAssignmentsClient_NewListPager() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armguestconfiguration.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	pager := clientFactory.NewAssignmentsClient().NewListPager("myResourceGroupName", "myVMName", nil)
	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			log.Fatalf("failed to advance page: %v", err)
		}
		for _, v := range page.Value {
			// You could use page here. We use blank identifier for just demo purposes.
			_ = v
		}
		// If the HTTP response code is 200 as defined in example definition, your page structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
		// page.AssignmentList = armguestconfiguration.AssignmentList{
		// }
	}
}

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

JavaScript

const { GuestConfigurationClient } = require("@azure/arm-guestconfiguration");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to List all guest configuration assignments for a virtual machine.
 *
 * @summary List all guest configuration assignments for a virtual machine.
 * x-ms-original-file: specification/guestconfiguration/resource-manager/Microsoft.GuestConfiguration/stable/2022-01-25/examples/listGuestConfigurationAssignments.json
 */
async function listAllGuestConfigurationAssignmentsForAVirtualMachine() {
  const subscriptionId = process.env["GUESTCONFIGURATION_SUBSCRIPTION_ID"] || "mySubscriptionId";
  const resourceGroupName =
    process.env["GUESTCONFIGURATION_RESOURCE_GROUP"] || "myResourceGroupName";
  const vmName = "myVMName";
  const credential = new DefaultAzureCredential();
  const client = new GuestConfigurationClient(credential, subscriptionId);
  const resArray = new Array();
  for await (let item of client.guestConfigurationAssignments.list(resourceGroupName, vmName)) {
    resArray.push(item);
  }
  console.log(resArray);
}

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

dotnet

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

// Generated from example definition: specification/guestconfiguration/resource-manager/Microsoft.GuestConfiguration/stable/2022-01-25/examples/listGuestConfigurationAssignments.json
// this example is just showing the usage of "GuestConfigurationAssignments_List" 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://learn.microsoft.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 and iterate over the result
await foreach (GuestConfigurationVmAssignmentResource item in collection.GetAllAsync())
{
    // the variable item 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 = item.Data;
    // for demo we just print out the id
    Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

Console.WriteLine($"Succeeded");

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:

200

[
  {
    "location": "centraluseuap",
    "id": "/subscriptions/subscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myvm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/AuditSecureProtocol2",
    "name": "AuditSecureProtocol2",
    "properties": {
      "complianceStatus": "Compliant",
      "assignmentHash": "content hash",
      "latestReportId": "/subscriptions/subscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myvm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/AuditSecureProtocol2/reports/7367cbb8-ae99-47d0-a33b-a283564d2cb1",
      "lastComplianceStatusChecked": "2018-08-29T22:14:13Z",
      "context": null,
      "guestConfiguration": {
        "kind": null,
        "name": "AuditSecureProtocol2",
        "version": "1.0.0.3",
        "contentUri": "https://mystorageaccount.blob.core.windows.net/builtinconfig/AuditSecureProtocol2/AuditSecureProtocol2_1.0.0.3.zip",
        "contentHash": "content hash",
        "configurationParameter": [],
        "configurationSetting": null
      },
      "provisioningState": null
    }
  },
  {
    "location": "centraluseuap",
    "id": "/subscriptions/subscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myvm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/myAssignment",
    "name": "myAssignment",
    "properties": {
      "complianceStatus": "Compliant",
      "assignmentHash": "content hash",
      "latestReportId": "/subscriptions/subscriptionId/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myvm/providers/Microsoft.GuestConfiguration/guestConfigurationAssignments/myAssignment/reports/7367cbb8-ae99-47d0-a33b-a283564d2cb1",
      "lastComplianceStatusChecked": "2018-08-29T22:14:13Z",
      "context": null,
      "guestConfiguration": {
        "kind": null,
        "name": "myAssignment",
        "version": "1.0.0.3",
        "contentUri": "https://mystorageaccount.blob.core.windows.net/builtinconfig/myAssignment/myAssignment.0.0.3.zip",
        "contentHash": "content hash",
        "configurationParameter": [],
        "configurationSetting": null
      },
      "provisioningState": null
    }
  }
]

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.
GuestConfigurationAssignmentList	The response of the list guest configuration assignment operation.
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.

GuestConfigurationAssignmentList

The response of the list guest configuration assignment operation.

Name	Type	Description
value	GuestConfigurationAssignment[]	Result of the list guest configuration assignment operation.

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.
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.