How to manage assignments with PowerShellHow to manage assignments with PowerShell

A blueprint assignment can be managed using the Az.Blueprint Azure PowerShell module.A blueprint assignment can be managed using the Az.Blueprint Azure PowerShell module. The module supports fetching, creating, updating, and removing assignments.The module supports fetching, creating, updating, and removing assignments. The module can also fetch details on existing blueprint definitions.The module can also fetch details on existing blueprint definitions. This article covers how to install the module and start using it.This article covers how to install the module and start using it.

Add the Az.Blueprint moduleAdd the Az.Blueprint module

To enable Azure PowerShell to manage blueprint assignments, the module must be added.To enable Azure PowerShell to manage blueprint assignments, the module must be added. This module can be used with locally installed PowerShell, with Azure Cloud Shell, or with the Azure PowerShell Docker image.This module can be used with locally installed PowerShell, with Azure Cloud Shell, or with the Azure PowerShell Docker image.

Temel gereksinimlerBase requirements

The Azure Blueprints module requires the following software:The Azure Blueprints module requires the following software:

  • Azure PowerShell 1.5.0 or higher.Azure PowerShell 1.5.0 or higher. Henüz yüklenmiş değilse, bu yönergeleri izleyin.If it isn't yet installed, follow these instructions.
  • PowerShellGet 2.0.1 veya üzeri.PowerShellGet 2.0.1 or higher. Henüz yüklenmiş ve güncellenmiş değilse, bu yönergeleri izleyin.If it isn't installed or updated, follow these instructions.

Install the moduleInstall the module

The Blueprints module for PowerShell is Az.Blueprint.The Blueprints module for PowerShell is Az.Blueprint.

  1. From an administrative PowerShell prompt, run the following command:From an administrative PowerShell prompt, run the following command:

    # Install the Blueprints module from PowerShell Gallery
    Install-Module -Name Az.Blueprint
    

    Not

    If Az.Accounts is already installed, it may be necessary to use -AllowClobber to force the installation.If Az.Accounts is already installed, it may be necessary to use -AllowClobber to force the installation.

  2. Validate that the module has been imported and is the correct version (0.2.6):Validate that the module has been imported and is the correct version (0.2.6):

    # Get a list of commands for the imported Az.Blueprint module
    Get-Command -Module 'Az.Blueprint' -CommandType 'Cmdlet'
    

Get blueprint definitionsGet blueprint definitions

The first step to working with an assignment is often getting a reference to a blueprint definition.The first step to working with an assignment is often getting a reference to a blueprint definition. The Get-AzBlueprint cmdlet gets one or more blueprint definitions.The Get-AzBlueprint cmdlet gets one or more blueprint definitions. The cmdlet can get blueprint definitions from a management group with -ManagementGroupId {mgId} or a subscription with -SubscriptionId {subId}.The cmdlet can get blueprint definitions from a management group with -ManagementGroupId {mgId} or a subscription with -SubscriptionId {subId}. The Name parameter gets a blueprint definition, but must be used with ManagementGroupId or SubscriptionId.The Name parameter gets a blueprint definition, but must be used with ManagementGroupId or SubscriptionId. Version can be used with Name to be more explicit about which blueprint definition is returned.Version can be used with Name to be more explicit about which blueprint definition is returned. Instead of Version, the switch -LatestPublished grabs the most recently published version.Instead of Version, the switch -LatestPublished grabs the most recently published version.

The following example uses Get-AzBlueprint to get all versions of a blueprint definition named '101-blueprints-definition-subscription' from a specific subscription represented as {subId}:The following example uses Get-AzBlueprint to get all versions of a blueprint definition named '101-blueprints-definition-subscription' from a specific subscription represented as {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get all versions of the blueprint definition in the specified subscription
$blueprints = Get-AzBlueprint -SubscriptionId '{subId}' -Name '101-blueprints-definition-subscription'

# Display the blueprint definition object
$blueprints

The example output for a blueprint definition with multiple versions looks like this:The example output for a blueprint definition with multiple versions looks like this:

Name                 : 101-blueprints-definition-subscription
Id                   : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101
                       -blueprints-definition-subscription
DefinitionLocationId : {subId}
Versions             : {1.0, 1.1}
TimeCreated          : 2019-02-25
TargetScope          : Subscription
Parameters           : {storageAccount_storageAccountType, storageAccount_location,
                       allowedlocations_listOfAllowedLocations, [Usergrouporapplicationname]:Reader_RoleAssignmentName}
ResourceGroups       : ResourceGroup

The blueprint parameters on the blueprint definition can be expanded to provide more information.The blueprint parameters on the blueprint definition can be expanded to provide more information.

$blueprints.Parameters
Key                                                    Value
---                                                    -----
storageAccount_storageAccountType                      Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
storageAccount_location                                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
allowedlocations_listOfAllowedLocations                Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition
[Usergrouporapplicationname]:Reader_RoleAssignmentName Microsoft.Azure.Commands.Blueprint.Models.PSParameterDefinition

Get blueprint assignmentsGet blueprint assignments

If the blueprint assignment already exists, you can get a reference to it with the Get-AzBlueprintAssignment cmdlet.If the blueprint assignment already exists, you can get a reference to it with the Get-AzBlueprintAssignment cmdlet. The cmdlet takes SubscriptionId and Name as optional parameters.The cmdlet takes SubscriptionId and Name as optional parameters. If SubscriptionId isn't specified, the current subscription context is used.If SubscriptionId isn't specified, the current subscription context is used.

The following example uses Get-AzBlueprintAssignment to get a single blueprint assignment named 'Assignment-lock-resource-groups' from a specific subscription represented as {subId}:The following example uses Get-AzBlueprintAssignment to get a single blueprint assignment named 'Assignment-lock-resource-groups' from a specific subscription represented as {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -SubscriptionId '{subId}' -Name 'Assignment-lock-resource-groups'

# Display the blueprint assignment object
$blueprintAssignment

The example output for a blueprint assignment looks like this:The example output for a blueprint assignment looks like this:

Name              : Assignment-lock-resource-groups
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssignme
                    nts/Assignment-lock-resource-groups
Scope             : /subscriptions/{subId}
LastModified      : 2019-02-19
LockMode          : AllResourcesReadOnly
ProvisioningState : Succeeded
Parameters        :
ResourceGroups    : ResourceGroup

Create blueprint assignmentsCreate blueprint assignments

If the blueprint assignment doesn't exist yet, you can create it with the New-AzBlueprintAssignment cmdlet.If the blueprint assignment doesn't exist yet, you can create it with the New-AzBlueprintAssignment cmdlet. This cmdlet uses the following parameters:This cmdlet uses the following parameters:

  • Name [required]Name [required]

    • Specifies the name of the blueprint assignmentSpecifies the name of the blueprint assignment
    • Must be unique and not already exist in SubscriptionIdMust be unique and not already exist in SubscriptionId
  • Blueprint [required]Blueprint [required]

    • Specifies the blueprint definition to assignSpecifies the blueprint definition to assign
    • Use Get-AzBlueprint to get the reference objectUse Get-AzBlueprint to get the reference object
  • Location [required]Location [required]

    • Specifies the region for the system-assigned managed identity and subscription deployment object to be created inSpecifies the region for the system-assigned managed identity and subscription deployment object to be created in
  • Subscription (optional)Subscription (optional)

    • Specifies the subscription the assignment is deployed toSpecifies the subscription the assignment is deployed to
    • If not provided, defaults to the current subscription contextIf not provided, defaults to the current subscription context
  • Lock (optional)Lock (optional)

    • Defines the blueprint resource locking to use for deployed resourcesDefines the blueprint resource locking to use for deployed resources
    • Supported options: None, AllResourcesReadOnly, AllResourcesDoNotDeleteSupported options: None, AllResourcesReadOnly, AllResourcesDoNotDelete
    • If not provided, defaults to NoneIf not provided, defaults to None
  • SystemAssignedIdentity (optional)SystemAssignedIdentity (optional)

    • Select to create a system-assigned managed identity for the assignment and to deploy the resourcesSelect to create a system-assigned managed identity for the assignment and to deploy the resources
    • Default for the "identity" parameter setDefault for the "identity" parameter set
    • Can't be used with UserAssignedIdentityCan't be used with UserAssignedIdentity
  • UserAssignedIdentity (optional)UserAssignedIdentity (optional)

    • Specifies the user-assigned managed identity to use for the assignment and to deploy the resourcesSpecifies the user-assigned managed identity to use for the assignment and to deploy the resources
    • Part of the "identity" parameter setPart of the "identity" parameter set
    • Can't be used with SystemAssignedIdentityCan't be used with SystemAssignedIdentity
  • Parameter (optional)Parameter (optional)

    • A hash table of key/value pairs for setting dynamic parameters on the blueprint assignmentA hash table of key/value pairs for setting dynamic parameters on the blueprint assignment

    • Default for a dynamic parameter is the defaultValue in the definitionDefault for a dynamic parameter is the defaultValue in the definition

    • If a parameter isn't provided and has no defaultValue, the parameter isn't optionalIf a parameter isn't provided and has no defaultValue, the parameter isn't optional

      Not

      Parameter doesn't support secureStrings.Parameter doesn't support secureStrings.

  • ResourceGroupParameter (optional)ResourceGroupParameter (optional)

    • A hash table of resource group artifactsA hash table of resource group artifacts
    • Each resource group artifact placeholder has key/value pairs for dynamically setting Name and Location on that resource group artifactEach resource group artifact placeholder has key/value pairs for dynamically setting Name and Location on that resource group artifact
    • If a resource group parameter isn't provided and has no defaultValue, the resource group parameter isn't optionalIf a resource group parameter isn't provided and has no defaultValue, the resource group parameter isn't optional
  • AssignmentFile (optional)AssignmentFile (optional)

    • The path to a JSON file representation of a blueprint assignmentThe path to a JSON file representation of a blueprint assignment
    • This parameter is part of a PowerShell parameter set that only includes Name, Blueprint, and SubscriptionId, plus the common parameters.This parameter is part of a PowerShell parameter set that only includes Name, Blueprint, and SubscriptionId, plus the common parameters.

Example 1: Provide parametersExample 1: Provide parameters

The following example creates a new assignment of version '1.1' of the 'my-blueprint' blueprint definition fetched with Get-AzBlueprint, sets the managed identity and assignment object location to 'westus2', locks the resources with AllResourcesReadOnly, and sets the hash tables for both Parameter and ResourceGroupParameter on specific subscription represented as {subId}:The following example creates a new assignment of version '1.1' of the 'my-blueprint' blueprint definition fetched with Get-AzBlueprint, sets the managed identity and assignment object location to 'westus2', locks the resources with AllResourcesReadOnly, and sets the hash tables for both Parameter and ResourceGroupParameter on specific subscription represented as {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters

The example output for creating a blueprint assignment looks like this:The example output for creating a blueprint assignment looks like this:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesReadOnly
ProvisioningState : Creating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

Example 2: Use a JSON assignment definition fileExample 2: Use a JSON assignment definition file

The following example creates nearly the same assignment as Example 1.The following example creates nearly the same assignment as Example 1. Instead of passing parameters to the cmdlet, the example shows use of a JSON assignment definition file and the AssignmentFile parameter.Instead of passing parameters to the cmdlet, the example shows use of a JSON assignment definition file and the AssignmentFile parameter. Additionally, the excludedPrincipals property is configured as part of locks.Additionally, the excludedPrincipals property is configured as part of locks. There isn't a PowerShell parameter for excludedPrincipals and the property can only be configured by setting it through the JSON assignment definition file.There isn't a PowerShell parameter for excludedPrincipals and the property can only be configured by setting it through the JSON assignment definition file.

{
  "identity": {
    "type": "SystemAssigned"
  },
  "location": "westus2",
  "properties": {
    "description": "Assignment of the 101-blueprint-definition-subscription",
    "blueprintId": "/subscriptions/{subId}/providers/Microsoft.Blueprint/blueprints/101-blueprints-definition-subscription",
    "locks": {
      "mode": "AllResourcesReadOnly",
      "excludedPrincipals": [
          "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
          "38833b56-194d-420b-90ce-cff578296714"
      ]
    },
    "parameters": {
      "storageAccount_storageAccountType": {
        "value": "Standard_GRS"
      }
    },
    "resourceGroups": {
      "ResourceGroup": {
        "name": "storage_rg",
        "location": "westus2"
      }
    }
  }
}
# Login first with Connect-AzAccount if not using Cloud Shell

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -SubscriptionId '{subId}' `
    -AssignmentFile '.\assignment.json'

Update blueprint assignmentsUpdate blueprint assignments

Sometimes it's necessary to update a blueprint assignment that has already been created.Sometimes it's necessary to update a blueprint assignment that has already been created. The Set-AzBlueprintAssignment cmdlet handles this action.The Set-AzBlueprintAssignment cmdlet handles this action. The cmdlet takes most of the same parameters that the New-AzBlueprintAssignment cmdlet does, allowing anything that was set on the assignment to be updated.The cmdlet takes most of the same parameters that the New-AzBlueprintAssignment cmdlet does, allowing anything that was set on the assignment to be updated. The exceptions are the Name, Blueprint, and SubscriptionId.The exceptions are the Name, Blueprint, and SubscriptionId. Only the values provided are updated.Only the values provided are updated.

To understand what happens when updating a blueprint assignment, see rules for updating assignments.To understand what happens when updating a blueprint assignment, see rules for updating assignments.

  • Name [required]Name [required]

    • Specifies the name of the blueprint assignment to updateSpecifies the name of the blueprint assignment to update
    • Used to locate the assignment to update, not to change the assignmentUsed to locate the assignment to update, not to change the assignment
  • Blueprint [required]Blueprint [required]

    • Specifies the blueprint definition of the blueprint assignmentSpecifies the blueprint definition of the blueprint assignment
    • Use Get-AzBlueprint to get the reference objectUse Get-AzBlueprint to get the reference object
    • Used to locate the assignment to update, not to change the assignmentUsed to locate the assignment to update, not to change the assignment
  • Location (optional)Location (optional)

    • Specifies the region for the system-assigned managed identity and subscription deployment object to be created inSpecifies the region for the system-assigned managed identity and subscription deployment object to be created in
  • Subscription (optional)Subscription (optional)

    • Specifies the subscription the assignment is deployed toSpecifies the subscription the assignment is deployed to
    • If not provided, defaults to the current subscription contextIf not provided, defaults to the current subscription context
    • Used to locate the assignment to update, not to change the assignmentUsed to locate the assignment to update, not to change the assignment
  • Lock (optional)Lock (optional)

    • Defines the blueprint resource locking to use for deployed resourcesDefines the blueprint resource locking to use for deployed resources
    • Supported options: None, AllResourcesReadOnly, AllResourcesDoNotDeleteSupported options: None, AllResourcesReadOnly, AllResourcesDoNotDelete
  • SystemAssignedIdentity (optional)SystemAssignedIdentity (optional)

    • Select to create a system-assigned managed identity for the assignment and to deploy the resourcesSelect to create a system-assigned managed identity for the assignment and to deploy the resources
    • Default for the "identity" parameter setDefault for the "identity" parameter set
    • Can't be used with UserAssignedIdentityCan't be used with UserAssignedIdentity
  • UserAssignedIdentity (optional)UserAssignedIdentity (optional)

    • Specifies the user-assigned managed identity to use for the assignment and to deploy the resourcesSpecifies the user-assigned managed identity to use for the assignment and to deploy the resources
    • Part of the "identity" parameter setPart of the "identity" parameter set
    • Can't be used with SystemAssignedIdentityCan't be used with SystemAssignedIdentity
  • Parameter (optional)Parameter (optional)

    • A hash table of key/value pairs for setting dynamic parameters on the blueprint assignmentA hash table of key/value pairs for setting dynamic parameters on the blueprint assignment

    • Default for a dynamic parameter is the defaultValue in the definitionDefault for a dynamic parameter is the defaultValue in the definition

    • If a parameter isn't provided and has no defaultValue, the parameter isn't optionalIf a parameter isn't provided and has no defaultValue, the parameter isn't optional

      Not

      Parameter doesn't support secureStrings.Parameter doesn't support secureStrings.

  • ResourceGroupParameter (optional)ResourceGroupParameter (optional)

    • A hash table of resource group artifactsA hash table of resource group artifacts
    • Each resource group artifact placeholder has key/value pairs for dynamically setting Name and Location on that resource group artifactEach resource group artifact placeholder has key/value pairs for dynamically setting Name and Location on that resource group artifact
    • If a resource group parameter isn't provided and has no defaultValue, the resource group parameter isn't optionalIf a resource group parameter isn't provided and has no defaultValue, the resource group parameter isn't optional

The following example updates the assignment of version '1.1' of the 'my-blueprint' blueprint definition fetched with Get-AzBlueprint by changing the lock mode:The following example updates the assignment of version '1.1' of the 'my-blueprint' blueprint definition fetched with Get-AzBlueprint by changing the lock mode:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'

# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete

The example output for creating a blueprint assignment looks like this:The example output for creating a blueprint assignment looks like this:

Name              : my-blueprint-assignment
Id                : /subscriptions/{subId}/providers/Microsoft.Blueprint/blueprintAssi
                    gnments/my-blueprint-assignment
Scope             : /subscriptions/{subId}
LastModified      : 2019-03-13
LockMode          : AllResourcesDoNotDelete
ProvisioningState : Updating
Parameters        : {storageAccount_storageAccountType}
ResourceGroups    : ResourceGroup

Remove blueprint assignmentsRemove blueprint assignments

When it's time for a blueprint assignment to be removed, the Remove-AzBlueprintAssignment cmdlet handles this action.When it's time for a blueprint assignment to be removed, the Remove-AzBlueprintAssignment cmdlet handles this action. The cmdlet takes either Name or InputObject to specify which blueprint assignment to remove.The cmdlet takes either Name or InputObject to specify which blueprint assignment to remove. SubscriptionId is required and must be provided in all cases.SubscriptionId is required and must be provided in all cases.

The following example fetches an existing blueprint assignment with Get-AzBlueprintAssignment and then removes it from the specific subscription represented as {subId}:The following example fetches an existing blueprint assignment with Get-AzBlueprintAssignment and then removes it from the specific subscription represented as {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

# Get the blueprint assignment in the specified subscription
$blueprintAssignment = Get-AzBlueprintAssignment -Name 'Assignment-lock-resource-groups'

# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $blueprintAssignment -SubscriptionId '{subId}'

End-to-end code exampleEnd-to-end code example

Bringing all the steps together, the following example gets the blueprint definition, then creates, updates, and removes a blueprint assignment in the specific subscription represented as {subId}:Bringing all the steps together, the following example gets the blueprint definition, then creates, updates, and removes a blueprint assignment in the specific subscription represented as {subId}:

# Login first with Connect-AzAccount if not using Cloud Shell

#region GetBlueprint
# Get version '1.1' of the blueprint definition in the specified subscription
$bpDefinition = Get-AzBlueprint -SubscriptionId '{subId}' -Name 'my-blueprint' -Version '1.1'
#endregion

#region CreateAssignment
# Create the hash table for Parameters
$bpParameters = @{storageAccount_storageAccountType='Standard_GRS'}

# Create the hash table for ResourceGroupParameters
# ResourceGroup is the resource group artifact placeholder name
$bpRGParameters = @{ResourceGroup=@{name='storage_rg';location='westus2'}}

# Create the new blueprint assignment
$bpAssignment = New-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Location 'westus2' -Lock AllResourcesReadOnly `
    -Parameter $bpParameters -ResourceGroupParameter $bpRGParameters
#endregion CreateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region UpdateAssignment
# Update the existing blueprint assignment
$bpAssignment = Set-AzBlueprintAssignment -Name 'my-blueprint-assignment' -Blueprint $bpDefinition `
    -SubscriptionId '{subId}' -Lock AllResourcesDoNotDelete
#endregion UpdateAssignment

# Wait for the blueprint assignment to finish deployment prior to the next steps

#region RemoveAssignment
# Remove the existing blueprint assignment
Remove-AzBlueprintAssignment -InputObject $bpAssignment -SubscriptionId '{subId}'
#endregion

Sonraki adımlarNext steps