How to manage assignments with PowerShell
Important
On July 11, 2026, Blueprints (Preview) will be deprecated. Migrate your existing blueprint definitions and assignments to Template Specs and Deployment Stacks. Blueprint artifacts are to be converted to ARM JSON templates or Bicep files used to define deployment stacks. To learn how to author an artifact as an ARM resource, see:
A blueprint assignment can be managed using the Az.Blueprint Azure PowerShell module. The module supports fetching, creating, updating, and removing assignments. The module can also fetch details on existing blueprint definitions. This article covers how to install the module and start using it.
Add the Az.Blueprint module
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.
Base requirements
The Azure Blueprints module requires the following software:
- Azure PowerShell 1.5.0 or higher. If it isn't yet installed, follow these instructions.
- PowerShellGet 2.0.1 or higher. If it isn't installed or updated, follow these instructions.
Install the module
The Azure Blueprints module for PowerShell is Az.Blueprint.
From an administrative PowerShell prompt, run the following command:
# Install the Azure Blueprints module from PowerShell Gallery Install-Module -Name Az.BlueprintNote
If Az.Accounts is already installed, it may be necessary to use
-AllowClobberto force the installation.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 definitions
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 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. 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.
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:
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.
$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 assignments
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. 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}:
# 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:
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 assignments
If the blueprint assignment doesn't exist yet, you can create it with the
New-AzBlueprintAssignment cmdlet. This cmdlet uses the following parameters:
Name [required]
- Specifies the name of the blueprint assignment
- Must be unique and not already exist in SubscriptionId
Blueprint [required]
- Specifies the blueprint definition to assign
- Use
Get-AzBlueprintto get the reference object
Location [required]
- Specifies the region for the system-assigned managed identity and subscription deployment object to be created in
Subscription (optional)
- Specifies the subscription the assignment is deployed to
- If not provided, defaults to the current subscription context
Lock (optional)
- Defines the blueprint resource locking to use for deployed resources
- Supported options: None, AllResourcesReadOnly, AllResourcesDoNotDelete
- If not provided, defaults to None
SystemAssignedIdentity (optional)
- Select to create a system-assigned managed identity for the assignment and to deploy the resources
- Default for the "identity" parameter set
- Can't be used with UserAssignedIdentity
UserAssignedIdentity (optional)
- Specifies the user-assigned managed identity to use for the assignment and to deploy the resources
- Part of the "identity" parameter set
- Can't be used with SystemAssignedIdentity
Parameter (optional)
A hash table of key/value pairs for setting dynamic parameters on the blueprint assignment
Default for a dynamic parameter is the defaultValue in the definition
If a parameter isn't provided and has no defaultValue, the parameter isn't optional
Note
Parameter doesn't support secureStrings.
ResourceGroupParameter (optional)
- A 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 artifact
- If a resource group parameter isn't provided and has no defaultValue, the resource group parameter isn't optional
AssignmentFile (optional)
- The 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.
Example 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}:
# 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:
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 file
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. 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.
{
"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'
For an example of the JSON assignment definition file for a user-assigned managed identity, see the request body in Example: Assignment with user-assigned managed identity for REST API.
Update blueprint assignments
Sometimes it's necessary to update a blueprint assignment that has already been created. 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 exceptions are the Name, Blueprint, and SubscriptionId. Only the values
provided are updated.
To understand what happens when updating a blueprint assignment, see rules for updating assignments.
Name [required]
- Specifies the name of the blueprint assignment to update
- Used to locate the assignment to update, not to change the assignment
Blueprint [required]
- Specifies the blueprint definition of the blueprint assignment
- Use
Get-AzBlueprintto get the reference object - Used to locate the assignment to update, not to change the assignment
Location (optional)
- Specifies the region for the system-assigned managed identity and subscription deployment object to be created in
Subscription (optional)
- Specifies the subscription the assignment is deployed to
- If not provided, defaults to the current subscription context
- Used to locate the assignment to update, not to change the assignment
Lock (optional)
- Defines the blueprint resource locking to use for deployed resources
- Supported options: None, AllResourcesReadOnly, AllResourcesDoNotDelete
SystemAssignedIdentity (optional)
- Select to create a system-assigned managed identity for the assignment and to deploy the resources
- Default for the "identity" parameter set
- Can't be used with UserAssignedIdentity
UserAssignedIdentity (optional)
- Specifies the user-assigned managed identity to use for the assignment and to deploy the resources
- Part of the "identity" parameter set
- Can't be used with SystemAssignedIdentity
Parameter (optional)
A hash table of key/value pairs for setting dynamic parameters on the blueprint assignment
Default for a dynamic parameter is the defaultValue in the definition
If a parameter isn't provided and has no defaultValue, the parameter isn't optional
Note
Parameter doesn't support secureStrings.
ResourceGroupParameter (optional)
- A 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 artifact
- If 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:
# 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:
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 assignments
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. 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}:
# 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}'
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}:
# 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
Next steps
- Learn about the blueprint lifecycle.
- Understand how to use static and dynamic parameters.
- Learn to customize the blueprint sequencing order.
- Find out how to make use of blueprint resource locking.
- Resolve issues during the assignment of a blueprint with general troubleshooting.