Quickstart: Define and assign an Azure blueprint with PowerShell

Article
09/07/2023

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:

In this tutorial, you learn to use Azure Blueprints to do some of the common tasks related to creating, publishing, and assigning a blueprint within your organization. This skill helps you define common patterns to develop reusable and rapidly deployable configurations, based on Azure Resource Manager (ARM) templates, policy, and security.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.
If it isn't already installed, follow the instructions in Add the Az.Blueprint module to install and validate the Az.Blueprint module from the PowerShell Gallery.
If you've not used Azure Blueprints before, register the resource provider through Azure PowerShell with Register-AzResourceProvider -ProviderNamespace Microsoft.Blueprint.

Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option	Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To use Azure Cloud Shell:

Start Cloud Shell.
Select the Copy button on a code block (or command block) to copy the code or command.
Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code or command.

Create a blueprint

The first step in defining a standard pattern for compliance is to compose a blueprint from the available resources. Let's create a blueprint named MyBlueprint to configure role and policy assignments for the subscription. Then you add a resource group, an ARM template, and a role assignment on the resource group.

Note

When you're using PowerShell, the blueprint object is created first. For each artifact to be added that has parameters, you define the parameters in advance on the initial blueprint.

Create the initial blueprint object. The BlueprintFile parameter takes a JSON file that includes properties about the blueprint, any resource groups to create, and all of the blueprint-level parameters. You set the parameters during assignment, and they're used by the artifacts you add in later steps.

JSON file - blueprint.json

{
    "properties": {
        "description": "This blueprint sets tag policy and role assignment on the subscription, creates a ResourceGroup, and deploys a resource template and role assignment to that ResourceGroup.",
        "targetScope": "subscription",
        "parameters": {
            "storageAccountType": {
                "type": "string",
                "defaultValue": "Standard_LRS",
                "allowedValues": [
                    "Standard_LRS",
                    "Standard_GRS",
                    "Standard_ZRS",
                    "Premium_LRS"
                ],
                "metadata": {
                    "displayName": "storage account type.",
                    "description": null
                }
            },
            "tagName": {
                "type": "string",
                "metadata": {
                    "displayName": "The name of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "tagValue": {
                "type": "string",
                "metadata": {
                    "displayName": "The value of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "contributors": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Contributor role at the subscription",
                    "strongType": "PrincipalId"
                }
            },
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group",
                    "strongType": "PrincipalId"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

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

# Get a reference to the new blueprint object, we'll use it in subsequent steps
$blueprint = New-AzBlueprint -Name 'MyBlueprint' -BlueprintFile .\blueprint.json
```
Note

Use the filename blueprint.json when you create your blueprint definitions programmatically. This file name is used when you call Import-AzBlueprintWithArtifact.

The blueprint object is created in the default subscription by default. To specify the management group, use the parameter ManagementGroupId. To specify the subscription, use the parameter SubscriptionId.

Add a role assignment at the subscription. The ArtifactFile defines the kind of artifact, the properties align to the role definition identifier, and the principal identities are passed as an array of values. In the following example, the principal identities granted the specified role are configured to a parameter that is set during blueprint assignment. This example uses the Contributor built-in role, with a GUID of b24988ac-6180-42a0-ab88-20f7382dd24c.
- JSON file - \artifacts\roleContributor.json
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```
- PowerShell command
```
# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleContributor' -ArtifactFile .\artifacts\roleContributor.json
```

Add a policy assignment at the subscription. The ArtifactFile defines the kind of artifact, the properties align to a policy or initiative definition, and the policy assignment is configured to use the defined blueprint parameters during blueprint assignment. This example uses the Apply tag and its default value to resource groups built-in policy, with a GUID of 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

JSON file - \artifacts\policyTags.json

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply tag and its default value to resource groups",
        "description": "Apply tag and its default value to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "[parameters('tagName')]"
            },
            "tagValue": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

PowerShell command

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyTags' -ArtifactFile .\artifacts\policyTags.json

Add another policy assignment for the storage tag (by reusing storageAccountType_ parameter) at the subscription. This additional policy assignment artifact demonstrates that a parameter defined on the blueprint is usable by more than one artifact. In the example, you use the storageAccountType to set a tag on the resource group. This value provides information about the storage account that you create in the next step. This example uses the Apply tag and its default value to resource groups built-in policy, with a GUID of 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

JSON file - \artifacts\policyStorageTags.json

{
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply storage tag to resource group",
        "description": "Apply storage tag and the parameter also used by the template to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "StorageType"
            },
            "tagValue": {
                "value": "[parameters('storageAccountType')]"
            }
        }
    }
}

PowerShell command

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyStorageTags' -ArtifactFile .\artifacts\policyStorageTags.json

Add a template under the resource group. The TemplateFile for an ARM template includes the normal JSON component of the template. The template also reuses the storageAccountType, tagName, and tagValue blueprint parameters by passing each to the template. The blueprint parameters are available to the template by using the parameter TemplateParameterFile, and inside the template JSON that key-value pair is used to inject the value. The blueprint and template parameter names might be the same.

JSON ARM template file - \artifacts\templateStorage.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "type": "string",
            "metadata": {
                "description": "Storage Account type"
            }
        },
        "tagNameFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag name from blueprint"
            }
        },
        "tagValueFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag value from blueprint"
            }
        }
    },
    "variables": {
        "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
    },
    "resources": [{
        "type": "Microsoft.Storage/storageAccounts",
        "name": "[variables('storageAccountName')]",
        "apiVersion": "2016-01-01",
        "tags": {
            "[parameters('tagNameFromBP')]": "[parameters('tagValueFromBP')]"
        },
        "location": "[resourceGroup().location]",
        "sku": {
            "name": "[parameters('storageAccountTypeFromBP')]"
        },
        "kind": "Storage",
        "properties": {}
    }],
    "outputs": {
        "storageAccountSku": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
        }
    }
}

JSON ARM template parameter file - \artifacts\templateStorageParams.json

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "value": "[parameters('storageAccountType')]"
        },
        "tagNameFromBP": {
            "value": "[parameters('tagName')]"
        },
        "tagValueFromBP": {
            "value": "[parameters('tagValue')]"
        }
    }
}

PowerShell command

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Type TemplateArtifact -Name 'templateStorage' -TemplateFile .\artifacts\templateStorage.json -TemplateParameterFile .\artifacts\templateStorageParams.json -ResourceGroupName storageRG

Add a role assignment under the resource group. Similar to the previous role assignment entry, the following example uses the definition identifier for the Owner role, and provides it a different parameter from the blueprint. This example uses the Owner built-in role, with a GUID of 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

JSON file - \artifacts\roleOwner.json

{
    "kind": "roleAssignment",
    "properties": {
        "resourceGroup": "storageRG",
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('owners')]"
    }
}

PowerShell command

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleOwner' -ArtifactFile .\artifacts\roleOwner.json

Publish a blueprint

Now that you've added the artifacts to the blueprint, it's time to publish it. Publishing makes the blueprint available to assign to a subscription.

# Use the reference to the new blueprint object from the previous steps
Publish-AzBlueprint -Blueprint $blueprint -Version '{BlueprintVersion}'

The value for {BlueprintVersion} is a string of letters, numbers, and hyphens (with no spaces or other special characters). The maximum length is 20 characters. Use something unique and informational, such as v20180622-135541.

Assign a blueprint

After you've published a blueprint by using PowerShell, it's assignable to a subscription. Assign the blueprint that you created to one of the subscriptions under your management group hierarchy. If the blueprint is saved to a subscription, it can only be assigned to that subscription. The Blueprint parameter specifies the blueprint to assign. To provide the name, location, identity, lock, and blueprint parameters, use the matching PowerShell parameters on the New-AzBlueprintAssignment cmdlet, or provide them in the AssignmentFile parameter JSON file.

Run the blueprint deployment by assigning it to a subscription. Because the contributors and owners parameters require an array of objectIds of the principals to be granted the role assignment, use Azure Active Directory Graph API for gathering the objectIds for use in the AssignmentFile for your own users, groups, or service principals.

JSON file - blueprintAssignment.json

{
    "properties": {
        "blueprintId": "/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint",
        "resourceGroups": {
            "storageRG": {
                "name": "StorageAccount",
                "location": "eastus2"
            }
        },
        "parameters": {
            "storageAccountType": {
                "value": "Standard_GRS"
            },
            "tagName": {
                "value": "CostCenter"
            },
            "tagValue": {
                "value": "ContosoIT"
            },
            "contributors": {
                "value": [
                    "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
                    "38833b56-194d-420b-90ce-cff578296714"
                ]
            },
            "owners": {
                "value": [
                    "44254d2b-a0c7-405f-959c-f829ee31c2e7",
                    "316deb5f-7187-4512-9dd4-21e7798b0ef9"
                ]
            }
        }
    },
    "identity": {
        "type": "systemAssigned"
    },
    "location": "westus"
}

PowerShell command

# Use the reference to the new blueprint object from the previous steps
New-AzBlueprintAssignment -Blueprint $blueprint -Name 'assignMyBlueprint' -AssignmentFile .\blueprintAssignment.json

User-assigned managed identity

A blueprint assignment can also use a user-assigned managed identity. In this case, the identity portion of the JSON assignment file changes as follows. Replace {tenantId}, {subscriptionId}, {yourRG}, and {userIdentity} with your tenant ID, subscription ID, resource group name, and the name of your user-assigned managed identity, respectively.
```
"identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},
```
The user-assigned managed identity can be in any subscription and resource group to which the user assigning the blueprint has permissions.

Important

Azure Blueprints doesn't manage the user-assigned managed identity. Users are responsible for assigning sufficient roles and permissions, or the blueprint assignment will fail.

Clean up resources

You can remove a blueprint from a subscription. Removal is often done when the artifact resources are no longer needed. When a blueprint is removed, the artifacts assigned as part of that blueprint are left behind. To remove a blueprint assignment, use the Remove-AzBlueprintAssignment cmdlet:

assignMyBlueprint

Remove-AzBlueprintAssignment -Name 'assignMyBlueprint'

Next steps

In this quickstart, you created, assigned, and removed a blueprint with PowerShell. To learn more about Azure Blueprints, continue to the blueprint lifecycle article.

Learn about the blueprint lifecycle

Quickstart: Define and assign an Azure blueprint with PowerShell

Prerequisites

Azure Cloud Shell

Create a blueprint

Publish a blueprint

Assign a blueprint

Clean up resources

Next steps

Feedback

Additional resources