Quickstart: Define and assign an Azure blueprint with the Azure CLI

Artikel
15/09/2023

Penting

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 you've not used Azure Blueprints before, register the resource provider through the Azure CLI with az provider register --namespace 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.

Add the blueprint extension

To enable the Azure CLI to manage blueprint definitions and assignments, you must add the extension. This extension works wherever you can use the Azure CLI. This includes bash on Windows 10, Cloud Shell (both the standalone version and the one inside the portal), the Azure CLI Docker image, or an extension that's locally installed.

Check that the latest Azure CLI is installed (at least 2.0.76). If it isn't yet installed, follow these instructions.
In your Azure CLI environment of choice, import the extension with the following command:

Azure CLI
```
# Add the Blueprint extension to the Azure CLI environment
az extension add --name blueprint
```

Validate that the extension has been installed and is the expected version (at least 0.1.0):

Azure CLI

# Check the extension list (note that you might have other extensions installed)
az extension list

# Run help for extension options
az blueprint -h

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.

Nota

When you're using the Azure CLI, 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 parameters parameter takes a JSON file that includes 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 - blueprintparms.json

JSON

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

Azure CLI command

Azure CLI

# Login first with az login if not using Cloud Shell

# Create the blueprint object
az blueprint create \
   --name 'MyBlueprint' \
   --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.' \
   --parameters blueprintparms.json

Nota

Use the filename blueprint.json when you import your blueprint definitions. This file name is used when you call az blueprint import.

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

Add the resource group for the storage artifacts to the definition.

Azure CLI

az blueprint resource-group add \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'storageRG' \
   --description 'Contains the resource template deployment and a role assignment.'

Add a role assignment at the subscription. 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.

Azure CLI
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleContributor' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c' \
   --principal-ids "[parameters('contributors')]"
```

Add a policy assignment at the subscription. 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

JSON

{
   "tagName": {
      "value": "[parameters('tagName')]"
   },
   "tagValue": {
      "value": "[parameters('tagValue')]"
   }
}

Azure CLI command

Azure CLI

az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply tag and its default value to resource groups' \
   --description 'Apply tag and its default value to resource groups' \
   --parameters artifacts\policyTags.json

Nota

When you use az blueprint on a Mac, replace \ with / for parameter values that include the path. In this case, the value for parameters becomes 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
  
  JSON
```
{
   "tagName": {
      "value": "StorageType"
   },
   "tagValue": {
      "value": "[parameters('storageAccountType')]"
   }
}
```
- Azure CLI command
  
  Azure CLI
```
az blueprint artifact policy create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'policyStorageTags' \
   --policy-definition-id '/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71' \
   --display-name 'Apply storage tag to resource group' \
   --description 'Apply storage tag and the parameter also used by the template to resource groups' \
   --parameters artifacts\policyStorageTags.json
```
  Nota
  
  When you use az blueprint on a Mac, replace \ with / for parameter values that include the path. In this case, the value for parameters becomes artifacts/policyStorageTags.json.

Add a template under resource group. The template parameter for an ARM template includes the normal JSON components 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 parameters, 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

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

JSON

{
   "storageAccountTypeFromBP": {
      "value": "[parameters('storageAccountType')]"
   },
   "tagNameFromBP": {
      "value": "[parameters('tagName')]"
   },
   "tagValueFromBP": {
      "value": "[parameters('tagValue')]"
   }
}

Azure CLI command

Azure CLI

az blueprint artifact template create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'templateStorage' \
   --template artifacts\templateStorage.json \
   --parameters artifacts\templateStorageParams.json \
   --resource-group-art 'storageRG'

Nota

When you use az blueprint on a Mac, replace \ with / for parameter values that include the path. In this case, the value for template becomes artifacts/templateStorage.json, and parameters becomes artifacts/templateStorageParams.json.

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.

Azure CLI
```
az blueprint artifact role create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'roleOwner' \
   --role-definition-id '/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635' \
   --principal-ids "[parameters('owners')]" \
   --resource-group-art 'storageRG'
```

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.

Azure CLI

az blueprint publish --blueprint-name 'MyBlueprint' --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 v20200605-135541.

Assign a blueprint

After you've published a blueprint by using the Azure CLI, 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-name parameter specifies the blueprint to assign. To provide the name, location, identity, lock, and blueprint parameters, use the matching Azure CLI parameters on the az blueprint assignment create command, or provide them in the parameters 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 parameters for your own users, groups, or service principals.

JSON file - blueprintAssignment.json

JSON

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

Azure CLI command

Azure CLI

az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json

User-assigned managed identity

A blueprint assignment can also use a user-assigned managed identity. In this case, the identity-type parameter is set to UserAssigned, and the user-assigned-identities parameter specifies the identity. Replace {userIdentity} with the name of your user-assigned managed identity.

Azure CLI
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --identity-type UserAssigned \
   --user-assigned-identities {userIdentity} \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
The user-assigned managed identity can be in any subscription and resource group to which the user assigning the blueprint has permissions.

Penting

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 az blueprint assignment delete command:

Azure CLI

az blueprint assignment delete --name 'assignMyBlueprint'

Next steps

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

Learn about the blueprint lifecycle

Sumber tambahan

Dokumentasi

Quickstart: Create a blueprint with PowerShell - Azure Blueprints

In this quickstart, you use Azure Blueprints to create, define, and deploy artifacts by using PowerShell.
Quickstart: Create a blueprint in the portal - Azure Blueprints

In this quickstart, you use Azure Blueprints to create, define, and deploy artifacts through the Azure portal.
Quickstart: Create a blueprint with REST API - Azure Blueprints

In this quickstart, you use Azure Blueprints to create, define, and deploy artifacts by using the REST API.
Microsoft.Blueprint/blueprints - Bicep, ARM template & Terraform AzAPI reference

Azure Microsoft.Blueprint/blueprints syntax and properties to use in Azure Resource Manager templates for deploying the resource. API version latest
Update an existing assignment from the portal - Azure Blueprints

Learn about the mechanism for updating an existing blueprint assignment from the portal in Azure Blueprints.
Tutorial: Blueprint sample to new environment - Azure Blueprints

In this tutorial, you use a blueprint sample to create a blueprint definition that sets up two resource groups and configures a role assignment for each.
Use parameters to creating dynamic blueprints - Azure Blueprints

Learn about static and dynamic parameters and how to use them to create secure and dynamic blueprints.
Azure Blueprints documentation

Simplify deployments by packaging artifacts, such as Azure Resource Manager templates, Azure role-based access control (Azure RBAC), and policies, in a single blueprint definition.

Latihan

Modul

Introduction to Azure Blueprints - Training

Introduction to Azure Blueprints and how to use to implement governance.

Pensijilan

Microsoft Certified: Azure Administrator Associate - Certifications

Demonstrate key skills to configure, manage, secure, and administer key professional functions in Microsoft Azure.

Kongsi melalui

Quickstart: Define and assign an Azure blueprint with the Azure CLI

Prerequisites

Azure Cloud Shell

Add the blueprint extension

Create a blueprint

Publish a blueprint

Assign a blueprint

Clean up resources

Next steps

Maklum balas

Sumber tambahan