Guia de Início Rápido: Definir e atribuir um blueprint do Azure com a CLI do Azure

Artigo
09/07/2023

Importante

Em 11 de julho de 2026, o Blueprints (versão prévia) será preterido. Migre suas definições e atribuições de blueprint existentes para Especificações de Modelo e Pilhas de Implantação. Os artefatos de blueprint devem ser convertidos em modelos JSON do ARM ou arquivos Bicep usados para definir pilhas de implantação. Para saber como criar um artefato como um recurso do ARM, confira:

Neste tutorial, você aprenderá a usar o Azure Blueprints para executar algumas das tarefas comuns relacionadas à criação, publicação e atribuição de um blueprint dentro de sua organização. Essa habilidade ajuda você a definir padrões comuns para desenvolver configurações reutilizáveis e implantáveis rapidamente, com base em modelos do ARM (Azure Resource Manager), política e segurança.

Pré-requisitos

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Se você ainda não usou o Azure Blueprints, registre o provedor de recursos por meio da CLI do Azure com az provider register --namespace Microsoft.Blueprint.

Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo, sem precisar instalar nada no seu ambiente local.

Para iniciar o Azure Cloud Shell:

Opção	Exemplo/Link
Selecione Experimentar no canto superior direito de um bloco de código ou de comando. Selecionar Experimentar não copia automaticamente o código nem o comando para o Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.

Para usar o Azure Cloud Shell:

Inicie o Cloud Shell.
Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.
Cole o código ou comando na sessão do Cloud Shell selecionando Ctrl+Shift+V no Windows e no Linux, ou selecionando Cmd+Shift+V no macOS.
Selecione Enter para executar o código ou o comando.

Adicionar a extensão de blueprint

Para permitir que a CLI do Azure gerencie definições e atribuições de blueprint, você precisa adicionar a extensão. Essa extensão funcionará sempre que você poderá usar a CLI do Azure. Isso inclui o Bash no Windows 10, o Cloud Shell (a versão autônoma e a do portal), a imagem do Docker na CLI do Azure ou uma extensão instalada localmente.

Verifique se a CLI do Azure mais recente está instalada (pelo menos a versão 2.0.76). Se ainda não estiver instalado, siga estas instruções.

No seu ambiente da CLI do Azure preferido, importe a extensão com o seguinte comando:

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

Verifique se a extensão foi instalada e se é a versão esperada (0.1.0 ou posterior):

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

# Run help for extension options
az blueprint -h

Criar um plano gráfico

A primeira etapa na definição de um modelo padrão para conformidade é compor um blueprint a partir dos recursos disponíveis. Vamos criar um blueprint chamado MyBlueprint para configurar as atribuições de função e política para a assinatura. Em seguida, você adicionará um grupo de recursos, um modelo do ARM e uma atribuição de função no grupo de recursos.

Observação

Quando você usa a CLI do Azure, o objeto blueprint é criado primeiro. Para cada artefato com parâmetros a ser adicionado, defina os parâmetros com antecedência no blueprint inicial.

Crie o objeto blueprint original. O parâmetro parameters usa um arquivo JSON que inclui todos os parâmetros do blueprint. Defina os parâmetros durante a atribuição e eles serão usados pelos artefatos que você adicionar em etapas posteriores.

Arquivo JSON – blueprintparms.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"
       }
   }
}

Comando da CLI do Azure
```
# 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
```
Observação

Use o nome de arquivo blueprint.json ao importar as definições de blueprint. Esse nome de arquivo é usado quando você chama az blueprint import.

Por padrão, o objeto blueprint é criado na assinatura padrão. Para especificar o grupo de gerenciamento, use o parâmetro managementgroup. Para especificar a assinatura, use o parâmetro subscription.

Adicione o grupo de recursos dos artefatos de armazenamento à definição.

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

Adicione uma atribuição de função na assinatura. No exemplo a seguir, as identidades de entidade de segurança concedidas à função especificada são configuradas para um parâmetro que é definido durante a atribuição do blueprint. Este exemplo usa a função interna Contributor com o GUID b24988ac-6180-42a0-ab88-20f7382dd24c.
```
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')]"
```

Adicione uma atribuição de política na assinatura. Este exemplo usa a política interna Apply tag and its default value to resource groups com o GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

Arquivo JSON – artifacts\policyTags.json

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

Comando da CLI do Azure

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

Observação

Ao usar az blueprint em um Mac, substitua \ por / nos valores de parâmetro que incluem o caminho. Nesse caso, o valor de parameters passa a ser artifacts/policyTags.json.

Adicione outra atribuição de política para a marca de armazenamento (reutilizando storageAccountType_ parameter) na assinatura. Este artefato de atribuição de política adicional demonstra que um parâmetro definido no blueprint pode ser usado por mais de um artefato. No exemplo, você usará o storageAccountType para definir uma marca no grupo de recursos. Esse valor fornece informações sobre a conta de armazenamento que será criada na próxima etapa. Este exemplo usa a política interna Apply tag and its default value to resource groups com o GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.
- Arquivo JSON – artifacts\policyStorageTags.json
```
{
   "tagName": {
      "value": "StorageType"
   },
   "tagValue": {
      "value": "[parameters('storageAccountType')]"
   }
}
```
- Comando da CLI do Azure
```
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
```
  Observação
  
  Ao usar az blueprint em um Mac, substitua \ por / nos valores de parâmetro que incluem o caminho. Nesse caso, o valor de parameters passa a ser artifacts/policyStorageTags.json.

Adicione um modelo no grupo de recursos. O parâmetro template de um modelo do ARM inclui os componentes normais JSON do modelo. O modelo também reutiliza os parâmetros storageAccountType, tagName e tagValue do blueprint transmitindo cada um para o modelo. Os parâmetros do blueprint são disponibilizados ao modelo usando o parâmetro parameters e, dentro do JSON do modelo, o par chave-valor é usado para injetar o valor. Os nomes dos parâmetros de blueprint e de modelo podem ser iguais.

Arquivo de modelo do ARM JSON – 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')]"
        }
    }
}

Arquivo de parâmetro de modelo do ARM JSON – artifacts\templateStorageParams.json

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

Comando da CLI do Azure
```
az blueprint artifact template create \
   --blueprint-name 'MyBlueprint' \
   --artifact-name 'templateStorage' \
   --template artifacts\templateStorage.json \
   --parameters artifacts\templateStorageParams.json \
   --resource-group-art 'storageRG'
```
Observação

Ao usar az blueprint em um Mac, substitua \ por / nos valores de parâmetro que incluem o caminho. Nesse caso, o valor de template passa a ser artifacts/templateStorage.json, e parameters passa a ser artifacts/templateStorageParams.json.

Adicione uma atribuição de função no grupo de recursos. De modo semelhante à entrada de atribuição de função anterior, o exemplo a seguir usa o identificador de definição da função Owner e fornece a ela um parâmetro diferente do blueprint. Este exemplo usa a função interna Owner com o GUID 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.
```
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'
```

Publicar um modelo

Agora que você adicionou os artefatos ao blueprint, é hora de publicá-lo. A publicação disponibiliza o blueprint para atribuição a uma assinatura.

az blueprint publish --blueprint-name 'MyBlueprint' --version '{BlueprintVersion}'

O valor de {BlueprintVersion} é uma cadeia de caracteres de letras, números e hifens (sem espaços nem outros caracteres especiais). O tamanho máximo é de 20 caracteres. Use algo exclusivo e informativo, como v20200605-135541.

Atribuir um modelo

Depois que um blueprint é publicado por meio da CLI do Azure, ele pode ser atribuído a uma assinatura. Atribua o blueprint que você criou a uma das assinaturas em sua hierarquia do grupo de gerenciamento. Se o blueprint for salvo em uma assinatura, ele só poderá ser atribuído a essa assinatura. O parâmetro blueprint-name especifica o blueprint a ser atribuído. Para fornecer parâmetros name, location, identity, lock e blueprint, use os parâmetros correspondentes da CLI do Azure no comando az blueprint assignment create ou forneça-os no arquivo JSON parameters.

Execute a implantação do blueprint atribuindo-o uma assinatura. Como os parâmetros contributors e owners exigem que uma matriz de objectIds das entidades de segurança seja concedida à atribuição de função, use a API do Graph do Azure Active Directory para coletar as objectIds a serem usadas nos parameters de seus usuários, grupos ou entidades de serviço.
- Arquivo JSON – blueprintAssignment.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"
       ]
   }
}
```
- Comando da CLI do Azure
```
az blueprint assignment create \
   --name 'assignMyBlueprint' \
   --location 'westus' \
   --resource-group-value artifact_name=storageRG name=StorageAccount location=eastus \
   --parameters blueprintAssignment.json
```
- Identidade gerenciada atribuída pelo usuário
  
  Uma atribuição de blueprint também pode usar uma identidade gerenciada atribuída por usuário. Nesse caso, o parâmetro identity-type é definido como UserAssigned, e o parâmetro user-assigned-identities especifica a identidade. Substitua {userIdentity} pelo nome da identidade gerenciada atribuída por usuário.
```
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
```
  A identidade gerenciada atribuída pelo usuário pode estar em qualquer assinatura e grupo de recursos nos quais o usuário que atribui o blueprint tem permissões.
  
  Importante
  
  O Azure Blueprints não gerencia a identidade gerenciada atribuída por usuário. Os usuários são responsáveis por atribuir funções e permissões suficientes, ou a atribuição de blueprint falhará.

Limpar os recursos

Você pode remover um blueprint de uma assinatura. A remoção geralmente é feita quando os recursos de artefato não são mais necessários. Quando um blueprint é removido, os artefatos atribuídos como parte desse blueprint são deixados para trás. Para remover uma atribuição de blueprint, use o comando az blueprint assignment delete:

az blueprint assignment delete --name 'assignMyBlueprint'

Próximas etapas

Neste guia de início rápido, você criou, atribuiu e removeu um blueprint com a CLI do Azure. Para saber mais sobre o Azure Blueprints, prossiga para o artigo de ciclo de vida do blueprint.

Saiba mais sobre o ciclo de vida do blueprint