Como gerenciar atribuições com o PowerShell

Uma atribuição de blueprint pode ser gerenciada usando o módulo Az.Blueprint do Azure PowerShell. O módulo dá suporte à busca, criação, atualização e remoção de atribuições. O módulo também pode buscar detalhes sobre as definições de blueprints existentes. Este artigo aborda como instalar o módulo e começar a usá-lo.

Adicionar o módulo Az.Blueprint

Para habilitar o Azure PowerShell para gerenciar as atribuições de blueprint, o módulo precisa ser adicionado. Esse módulo pode ser usado com o PowerShell instalado localmente, com o Azure Cloud Shell ou com a imagem do Docker do Azure PowerShell.

Requisitos base

O módulo do Azure Blueprints requer o seguinte software:

• Azure PowerShell 1.5.0 ou superior. Se ainda não estiver instalado, siga estas instruções.
• PowerShellGet 2.0.1 ou superior. Se ele não estiver instalado ou atualizado, siga estas instruções.

Instalar o módulo

O módulo do Azure Blueprints para PowerShell é Az.Blueprint.

1. De um prompt administrativo do PowerShell, execute o comando a seguir:

   # Install the Azure Blueprints module from PowerShell Gallery
   Install-Module -Name Az.Blueprint
   

   Observação

   Se o Az.Accounts já estiver instalado, pode ser necessário usar -AllowClobber para forçar a instalação.

2. Confirme se o módulo foi importado e é da versão correta (0.2.6):

   # Get a list of commands for the imported Az.Blueprint module
   Get-Command -Module 'Az.Blueprint' -CommandType 'Cmdlet'
   

Obter definições de blueprint

A primeira etapa para trabalhar com uma atribuição é geralmente obter uma referência a uma definição de blueprint. O cmdlet Get-AzBlueprint obtém uma ou mais definições de blueprint. O cmdlet pode obter definições de blueprint de um grupo de gerenciamento com -ManagementGroupId {mgId} ou uma assinatura com -SubscriptionId {subId}. O parâmetro Nome obtém uma definição de blueprint, mas deve ser usado com ManagementGroupId ou SubscriptionId. A Versão pode ser usada com o Nome para explicitar qual definição de blueprint é retornada. Em vez de Versão, a opção -LatestPublished captura a versão publicada mais recentemente.

O exemplo a seguir usa Get-AzBlueprint para obter todas as versões de uma definição de blueprint denominada '101-Blueprints-Definition-Subscription ' de uma assinatura específica representada como {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

A saída de exemplo para uma definição de blueprint com várias versões é semelhante a esta:

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

Os parâmetros de blueprint na definição de blueprint podem ser expandidos para fornecer mais informações.

$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

Obter atribuições de blueprint

Se a atribuição de blueprint já existir, você poderá obter uma referência a ela com o cmdlet Get-AzBlueprintAssignment. O cmdlet usa SubscriptionId e Nome como parâmetros opcionais. Se SubscriptionId não for especificado, o contexto de assinatura atual será usado.

O exemplo a seguir usa Get-AzBlueprintAssignment para obter uma única atribuição de blueprint chamada 'Assignment-Lock-Resource-Groups' de uma assinatura específica representada como {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

A saída de exemplo de uma atribuição de blueprint tem esta aparência:

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

Criar atribuições de blueprint

Se a atribuição de blueprint ainda não existir, você poderá criá-la com o cmdlet New-AzBlueprintAssignment. Esse cmdlet usa os seguintes parâmetros:

• Nome [obrigatório]

  • Especifica o nome da atribuição de blueprint
  • Deve ser exclusivo e ainda não existir no SubscriptionId

• Blueprint [obrigatório]

  • Especifica a definição de blueprint a ser atribuída
  • Use Get-AzBlueprint para obter o objeto de referência

• Local [obrigatório]

  • Especifique uma região na qual criar a identidade gerenciada atribuída pelo sistema e o objeto de implantação de assinatura

• Assinatura (opcional)

  • Especifica a assinatura na qual a atribuição é implantada
  • Se não for fornecido, o padrão será o contexto da assinatura atual

• Bloqueio (opcional)

  • Define o bloqueio de recursos do blueprint a ser usado para recursos implantados
  • Opções com suporte: Nenhum, AllResourcesReadOnly, AllResourcesDoNotDelete
  • Se não for fornecido, o padrão será Nenhum

• SystemAssignedIdentity (opcional)

  • Selecione para criar uma identidade gerenciada atribuída pelo sistema para a atribuição e para implantar os recursos
  • Padrão para o conjunto de parâmetros "Identity"
  • Não pode ser usado com UserAssignedIdentity

• UserAssignedIdentity (opcional)

  • Especifica a identidade gerenciada atribuída pelo usuário a ser usada para a atribuição e para implantar os recursos
  • Parte do conjunto de parâmetros "Identity"
  • Não pode ser usado com SystemAssignedIdentity

• Parâmetro (opcional)

  • Uma tabela de hash de pares chave/valor para definir parâmetros dinâmicos na atribuição de blueprint

  • O padrão para um parâmetro dinâmico é o defaultValue na definição

  • Se um parâmetro não for fornecido e não tiver defaultValue, o parâmetro não será opcional

    Observação

    O parâmetro não dá suporte a secureStrings.

• ResourceGroupParameter (optional)

  • Uma tabela de hash de artefatos do grupo de recursos
  • Cada espaço reservado do artefato do grupo de recursos tem pares de chave/valor para configurar dinamicamente o Nome e o Local nesse artefato do grupo de recursos
  • Se um parâmetro do grupo de recursos não for fornecido e não tiver defaultValue, o parâmetro de grupo de recursos não será opcional

• AssignmentFile (opcional)

  • O caminho para uma representação de arquivo JSON de uma atribuição de blueprint
  • Esse parâmetro faz parte de um conjunto de parâmetros do PowerShell que inclui apenas Nome, Blueprinte SubscriptionId, além dos parâmetros comuns.

Exemplo 1: Fornecer parâmetros

O exemplo a seguir cria uma nova atribuição da versão '1.1' da definição de blueprint 'my-blueprint' buscada com Get-AzBlueprint, define a identidade gerenciada e o local do objeto de atribuição como 'westus2', bloqueia os recursos com AllResourcesReadOnlye define as tabelas de hash para Parâmetro e ResourceGroupParameter na assinatura específica representada como {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

A saída de exemplo parar criar uma atribuição de blueprint tem esta aparência:

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

Exemplo 2: Usar um arquivo de definição de atribuição JSON

O exemplo a seguir cria quase a mesma atribuição que o Exemplo 1. Em vez de passar parâmetros para o cmdlet, o exemplo mostra o uso de um arquivo de definição de atribuição JSON e o parâmetro AssignmentFile. Além disso, a propriedade excludedPrincipals é configurada como parte dos bloqueios. Não há um parâmetro do PowerShell para excludedPrincipals e a propriedade só pode ser definida pela configuração por meio do arquivo de definição de atribuição JSON.

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

Para obter um exemplo do arquivo de definição de atribuição JSON para uma identidade gerenciada atribuída pelo usuário, consulte o corpo da solicitação em Exemplo: Atribuição com identidade gerenciada atribuída pelo usuário para a API REST.

Atualizar atribuições de blueprint

Às vezes, é necessário atualizar uma atribuição de blueprint que já foi criada. O cmdlet Set-AzBlueprintAssignment lida com essa ação. O cmdlet usa a maioria dos mesmos parâmetros que o cmdlet New-AzBlueprintAssignment, permitindo que qualquer coisa que tenha sido definida na atribuição seja atualizada. As exceções são o Nome, o Blueprinte a SubscriptionId. Somente os valores fornecidos são atualizados.

Para entender o que acontece ao atualizar uma atribuição de blueprint, consulte regras para atualizar atribuições.

• Nome [obrigatório]

  • Especifica o nome da atribuição de blueprint para atualizar
  • Usado para localizar a atribuição a ser atualizada, não para alterar a atribuição

• Blueprint [obrigatório]

  • Especifica a definição de blueprint da atribuição de blueprint
  • Use Get-AzBlueprint para obter o objeto de referência
  • Usado para localizar a atribuição a ser atualizada, não para alterar a atribuição

• Local(opcional)

  • Especifique uma região na qual criar a identidade gerenciada atribuída pelo sistema e o objeto de implantação de assinatura

• Assinatura (opcional)

  • Especifica a assinatura na qual a atribuição é implantada
  • Se não for fornecido, o padrão será o contexto da assinatura atual
  • Usado para localizar a atribuição a ser atualizada, não para alterar a atribuição

• Bloqueio (opcional)

  • Define o bloqueio de recursos do blueprint a ser usado para recursos implantados
  • Opções com suporte: Nenhum, AllResourcesReadOnly, AllResourcesDoNotDelete

• SystemAssignedIdentity (opcional)

  • Selecione para criar uma identidade gerenciada atribuída pelo sistema para a atribuição e para implantar os recursos
  • Padrão para o conjunto de parâmetros "Identity"
  • Não pode ser usado com UserAssignedIdentity

• UserAssignedIdentity (opcional)

  • Especifica a identidade gerenciada atribuída pelo usuário a ser usada para a atribuição e para implantar os recursos
  • Parte do conjunto de parâmetros "Identity"
  • Não pode ser usado com SystemAssignedIdentity

• Parâmetro (opcional)

  • Uma tabela de hash de pares chave/valor para definir parâmetros dinâmicos na atribuição de blueprint

  • O padrão para um parâmetro dinâmico é o defaultValue na definição

  • Se um parâmetro não for fornecido e não tiver defaultValue, o parâmetro não será opcional

    Observação

    O parâmetro não dá suporte a secureStrings.

• ResourceGroupParameter (optional)

  • Uma tabela de hash de artefatos do grupo de recursos
  • Cada espaço reservado do artefato do grupo de recursos tem pares de chave/valor para configurar dinamicamente o Nome e o Local nesse artefato do grupo de recursos
  • Se um parâmetro do grupo de recursos não for fornecido e não tiver defaultValue, o parâmetro de grupo de recursos não será opcional

O exemplo a seguir atualiza a atribuição da versão '1.1' da definição de blueprint 'my-blueprint ' buscada com Get-AzBlueprint alterando o modo de bloqueio:

# 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

A saída de exemplo parar criar uma atribuição de blueprint tem esta aparência:

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

Remover atribuições de blueprint

Quando é o momento de uma atribuição de blueprint ser removida, o cmdlet Remove-AzBlueprintAssignment lida com essa ação. O cmdlet usa Nome ou InputObject para especificar qual atribuição de blueprint deve ser removida. SubscriptionId é necessário e deve ser fornecido em todos os casos.

O exemplo a seguir busca uma atribuição de blueprint existente com Get-AzBlueprintAssignment e, em seguida, a remove da assinatura específica representada como {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}'

Exemplo de código

Reunindo todas as etapas, o exemplo a seguir obtém a definição de blueprint, depois cria, atualiza e remove uma atribuição de blueprint na assinatura específica representada como {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

Próximas etapas

• Saiba mais sobre o ciclo de vida do blueprint.
• Saiba como usar parâmetros estáticos e dinâmicos.
• Saiba como personalizar a ordem de sequenciamento de blueprint.
• Saiba como usar o bloqueio de recurso de blueprint.
• Resolver problemas durante a atribuição de blueprint com solução de problemas gerais.