Início Rápido: Definir e atribuir um blueprint do Azure com o PowerShell

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 ainda não estiver instalado, siga as instruções em Adicionar o módulo Az.Blueprint para instalar e validar o módulo Az.Blueprint na Galeria do PowerShell.
  • Se você ainda não usou o Azure Blueprints, registre o provedor de recursos por meio do Azure PowerShell com Register-AzResourceProvider -ProviderNamespace 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 ou o comando para o Cloud Shell. Captura de tela que mostra um exemplo de Experimente para o Azure Cloud Shell.
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador. Captura de tela que mostra como iniciar o Cloud Shell em uma nova janela.
Selecione o botão Cloud Shell na barra de menus no canto superior direito do portal do Azure. Captura de tela que mostra o botão Cloud Shell no portal do Azure

Para usar o Azure Cloud Shell:

  1. Inicie o Cloud Shell.

  2. Selecione o botão Copiar em um bloco de código (ou bloco de comando) para copiar o código ou o comando.

  3. 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.

  4. Selecione Enter para executar o código ou o comando.

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 estiver usando o PowerShell, o objeto blueprint é criado primeiro. Para cada artefato com parâmetros a ser adicionado, defina os parâmetros com antecedência no blueprint inicial.

  1. Crie o objeto blueprint original. O parâmetro BlueprintFile usa um arquivo JSON que inclui propriedades sobre o blueprint, grupos de recursos que devem ser criados e todos os parâmetros no nível 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 – 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."
                  }
              }
          }
      }
      
    • Comando do PowerShell

      # 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
      

      Observação

      Use o nome de arquivo blueprint.json ao criar suas definições de blueprint programaticamente. Esse nome de arquivo é usado quando você chama Import-AzBlueprintWithArtifact.

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

  2. Adicione uma atribuição de função na assinatura. O ArtifactFile define o tipo de artefato, as propriedades se alinham com o identificador da definição de função e as identidades de entidade de segurança são passadas como uma matriz de valores. 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.

    • Arquivo JSON – \artifacts\roleContributor.json

      {
          "kind": "roleAssignment",
          "properties": {
              "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
              "principalIds": "[parameters('contributors')]"
          }
      }
      
    • Comando do PowerShell

      # Use the reference to the new blueprint object from the previous steps
      New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleContributor' -ArtifactFile .\artifacts\roleContributor.json
      
  3. Adicione uma atribuição de política na assinatura. O ArtifactFile define o tipo de artefato, as propriedades se alinham com uma definição de iniciativa ou política e a atribuição de política é configurada para usar os parâmetros de blueprint definidos durante a atribuição do blueprint. 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

      {
          "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')]"
                  }
              }
          }
      }
      
    • Comando do PowerShell

      # Use the reference to the new blueprint object from the previous steps
      New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyTags' -ArtifactFile .\artifacts\policyTags.json
      
  4. 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

      {
          "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')]"
                  }
              }
          }
      }
      
    • Comando do PowerShell

      # Use the reference to the new blueprint object from the previous steps
      New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyStorageTags' -ArtifactFile .\artifacts\policyStorageTags.json
      
  5. Adicione um modelo sob o grupo de recursos. O TemplateFile de um modelo do ARM inclui o componente JSON normal 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 TemplateParameterFile 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 de ARM JSON – 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')]"
              }
          }
      }
      
    • Comando do PowerShell

      # 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
      
  6. Adicione atribuição de função sob o 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.

    • Arquivo JSON – \artifacts\roleOwner.json

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

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

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.

# Use the reference to the new blueprint object from the previous steps
Publish-AzBlueprint -Blueprint $blueprint -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 v20180622-135541.

Atribuir um modelo

Após publicar um blueprint usando o PowerShell, 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 especifica o blueprint a ser atribuído. Para fornecer parâmetros de name, location, identity, lock e blueprint, use os parâmetros correspondentes do PowerShell no cmdlet New-AzBlueprintAssignment ou forneça-os no arquivo JSON do parâmetro AssignmentFile.

  1. 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 AssignmentFile de seus usuários, grupos ou entidades de serviço.

    • Arquivo JSON – 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"
      }
      
    • Comando do PowerShell

      # Use the reference to the new blueprint object from the previous steps
      New-AzBlueprintAssignment -Blueprint $blueprint -Name 'assignMyBlueprint' -AssignmentFile .\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, a parte identity do arquivo da atribuição JSON é alterada da seguinte maneira. Substitua {tenantId}, {subscriptionId}, {yourRG} e {userIdentity} pela ID do locatário, ID da assinatura, nome do grupo de recursos e nome da identidade gerenciada atribuída por usuário, respectivamente.

      "identity": {
          "type": "userAssigned",
          "tenantId": "{tenantId}",
          "userAssignedIdentities": {
              "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
          }
      },
      

      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 cmdlet Remove-AzBlueprintAssignment:

assignMyBlueprint

Remove-AzBlueprintAssignment -Name 'assignMyBlueprint'

Próximas etapas

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