Toewijzingen beheren met PowerShell

  • Artikel
  • 10 minuten om te lezen

Een blauwdruktoewijzing kan worden beheerd met behulp van de Az.Blueprint Azure PowerShell module. De module ondersteunt het ophalen, maken, bijwerken en verwijderen van toewijzingen. De module kan ook details ophalen over bestaande blauwdrukdefinities. In dit artikel wordt beschreven hoe u de module installeert en deze gaat gebruiken.

De Az.Blueprint-module toevoegen

Als u Azure PowerShell blauwdruktoewijzingen wilt beheren, moet de module worden toegevoegd. Deze module kan worden gebruikt met lokaal geïnstalleerde PowerShell, met Azure Cloud Shell of met de Azure PowerShell Docker-installatiekopie.

Basisvereisten

Voor Azure Blueprints module is de volgende software vereist:

  • Azure PowerShell 1.5.0 of hoger. Als deze nog niet is geïnstalleerd, volgt u deze instructies op.
  • PowerShellGet 2.0.1 of hoger. Als deze nog niet is geïnstalleerd of bijgewerkt, volgt u deze instructies op.

Installeer de module

De Azure Blueprints-module voor PowerShell is Az.Blueprint.

  1. Voer vanuit een PowerShell-prompt met beheerdersrechten de volgende opdracht uit:

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

    Notitie

    Als Az.Accounts al is geïnstalleerd, kan het nodig zijn om de -AllowClobber installatie af te dwingen.

  2. Controleer of de module is geïmporteerd en de juiste versie (0.2.6) heeft:

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

Blauwdrukdefinities op halen

De eerste stap bij het werken met een toewijzing is vaak het verkrijgen van een verwijzing naar een blauwdrukdefinitie. De Get-AzBlueprint cmdlet haalt een of meer blauwdrukdefinities op. De cmdlet kan blauwdrukdefinities op halen uit een beheergroep met -ManagementGroupId {mgId} of een abonnement met -SubscriptionId {subId} . De parameter Name haalt een blauwdrukdefinitie op, maar moet worden gebruikt met ManagementGroupId of SubscriptionId. Versie kan worden gebruikt met Name om explicieter te zijn over welke blauwdrukdefinitie wordt geretourneerd. In plaats van Versie wordt de meest recent gepubliceerde versie van de switch -LatestPublished gebruikt.

In het volgende voorbeeld wordt gebruikt om alle versies van een blauwdrukdefinitie met de naam Get-AzBlueprint '101-blueprints-definition-subscription' op te halen uit een specifiek abonnement dat wordt weergegeven als {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

De voorbeelduitvoer voor een blauwdrukdefinitie met meerdere versies ziet er als volgende uit:

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

De blauwdrukparameters in de blauwdrukdefinitie kunnen worden uitgebreid voor meer informatie.

$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

Blauwdruktoewijzingen krijgen

Als de blauwdruktoewijzing al bestaat, kunt u er een verwijzing naar krijgen met de Get-AzBlueprintAssignment cmdlet . De cmdlet gebruikt SubscriptionId en Name als optionele parameters. Als SubscriptionId niet is opgegeven, wordt de huidige abonnementscontext gebruikt.

In het volgende voorbeeld wordt gebruikt om één blauwdruktoewijzing met de Get-AzBlueprintAssignment naam 'Assignment-lock-resource-groups' op te halen uit een specifiek abonnement dat wordt weergegeven als {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

De voorbeelduitvoer voor een blauwdruktoewijzing ziet er als volgende uit:

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

Blauwdruktoewijzingen maken

Als de blauwdruktoewijzing nog niet bestaat, kunt u deze maken met de New-AzBlueprintAssignment cmdlet . Deze cmdlet maakt gebruik van de volgende parameters:

  • Naam [vereist]

    • Hiermee geeft u de naam van de blauwdruktoewijzing op
    • Moet uniek zijn en niet al bestaan in SubscriptionId

  • Blauwdruk [vereist]

    • Hiermee geeft u de blauwdrukdefinitie op die moet worden toegewezen
    • Gebruik Get-AzBlueprint om het referentieobject op te halen

  • Locatie [vereist]

    • Hiermee geeft u de regio op voor de door het systeem toegewezen beheerde identiteit en het implementatieobject voor het abonnement dat moet worden gemaakt in

  • Abonnement (optioneel)

    • Hiermee geeft u het abonnement op waar de toewijzing op is geïmplementeerd
    • Als dit niet is opgegeven, wordt standaard de huidige abonnementscontext gebruikt

  • Vergrendelen (optioneel)

    • Definieert de vergrendeling van blauwdrukresources die moeten worden gebruikt voor geïmplementeerde resources
    • Ondersteunde opties: Geen, AllResourcesReadOnly, AllResourcesDoNotDelete
    • Als dit niet is opgegeven, wordt standaard Ingesteld op Geen

  • SystemAssignedIdentity (optioneel)

    • Selecteer om een door het systeem toegewezen beheerde identiteit voor de toewijzing te maken en de resources te implementeren
    • Standaardinstelling voor de parameterset 'identiteit'
    • Kan niet worden gebruikt met UserAssignedIdentity

  • UserAssignedIdentity (optioneel)

    • Hiermee geeft u de door de gebruiker toegewezen beheerde identiteit op die moet worden gebruikt voor de toewijzing en om de resources te implementeren
    • Onderdeel van de parameterset 'identiteit'
    • Kan niet worden gebruikt met SystemAssignedIdentity

  • Parameter (optioneel)

    • Een hashtabel met sleutel-waardeparen voor het instellen van dynamische parameters voor de blauwdruktoewijzing

    • De standaardwaarde voor een dynamische parameter is de defaultValue in de definitie

    • Als er geen parameter is opgegeven en geen defaultValue heeft, is de parameter niet optioneel

      Notitie

      Parameter biedt geen ondersteuning voor secureStrings.

  • ResourceGroupParameter (optioneel)

    • Een hashtabel met resourcegroepartefacten
    • Elke tijdelijke aanduiding voor het artefact van de resourcegroep heeft sleutel-waardeparen voor het dynamisch instellen van naam en locatie voor dat resourcegroepartefact
    • Als er geen resourcegroepparameter is opgegeven en geen defaultValue heeft, is de parameter van de resourcegroep niet optioneel

  • AssignmentFile (optioneel)

    • Het pad naar een JSON-bestandsweergave van een blauwdruktoewijzing
    • Deze parameter maakt deel uit van een PowerShell-parameterset die alleen Naam, Blauwdruk en SubscriptionId bevat, plus de algemene parameters.

Voorbeeld 1: Parameters opgeven

In het volgende voorbeeld wordt een nieuwe toewijzing gemaakt van versie 1.1 van de blauwdrukdefinitie 'mijn blauwdruk' die is opgehaald met , stelt u de locatie van de beheerde identiteit en het toewijzingsobject in op 'westus2', vergrendelt u de resources met Get-AzBlueprint AllResourcesReadOnly en stelt u de hashtabellen in voor parameter en ResourceGroupParameter voor een specifiek abonnement dat wordt weergegeven als {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

De voorbeelduitvoer voor het maken van een blauwdruktoewijzing ziet er als volgende uit:

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

Voorbeeld 2: Een JSON-toewijzingsdefinitiebestand gebruiken

In het volgende voorbeeld wordt bijna dezelfde toewijzing gemaakt als in voorbeeld 1. In plaats van parameters door te geven aan de cmdlet, toont het voorbeeld het gebruik van een JSON-toewijzingsdefinitiebestand en de parameter AssignmentFile. Daarnaast wordt de eigenschap excludedPrincipals geconfigureerd als onderdeel van vergrendelingen. Er is geen PowerShell-parameter voor excludedPrincipals en de eigenschap kan alleen worden geconfigureerd door deze in te stellen via het definitiebestand van de JSON-toewijzing.

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

Voor een voorbeeld van het JSON-toewijzingsdefinitiebestand voor een door de gebruiker toegewezen beheerde identiteit, zie de aanvraag body in Voorbeeld: Toewijzing met door de gebruiker toegewezen beheerde identiteit voor REST API.

Blauwdruktoewijzingen bijwerken

Soms is het nodig om een blauwdruktoewijzing bij te werken die al is gemaakt. De Set-AzBlueprintAssignment cmdlet verwerkt deze actie. De cmdlet gebruikt de meeste dezelfde parameters als de cmdlet, zodat alles wat is ingesteld voor de toewijzing New-AzBlueprintAssignment kan worden bijgewerkt. De uitzonderingen zijn naam, blauwdruk en SubscriptionId. Alleen de opgegeven waarden worden bijgewerkt.

Zie Regels voor het bijwerken van toewijzingen voor meer informatie over wat er gebeurt bij het bijwerken van een blauwdruktoewijzing.

  • Naam [vereist]

    • Hiermee geeft u de naam op van de blauwdruktoewijzing die moet worden bijgewerkt
    • Wordt gebruikt om de toewijzing te vinden die moet worden bijgewerkt, niet om de toewijzing te wijzigen

  • Blauwdruk [vereist]

    • Hiermee geeft u de blauwdrukdefinitie van de blauwdruktoewijzing op
    • Gebruik Get-AzBlueprint om het referentieobject op te halen
    • Wordt gebruikt om de toewijzing te vinden die moet worden bijgewerkt, niet om de toewijzing te wijzigen

  • Locatie (optioneel)

    • Hiermee geeft u de regio op voor de door het systeem toegewezen beheerde identiteit en het implementatieobject voor het abonnement dat moet worden gemaakt in

  • Abonnement (optioneel)

    • Hiermee geeft u het abonnement op waar de toewijzing op is geïmplementeerd
    • Als dit niet is opgegeven, wordt standaard de huidige abonnementscontext gebruikt
    • Wordt gebruikt om de toewijzing te vinden die moet worden bijgewerkt, niet om de toewijzing te wijzigen

  • Vergrendelen (optioneel)

    • Definieert de vergrendeling van blauwdrukresources die moeten worden gebruikt voor geïmplementeerde resources
    • Ondersteunde opties: Geen, AllResourcesReadOnly, AllResourcesDoNotDelete

  • SystemAssignedIdentity (optioneel)

    • Selecteer om een door het systeem toegewezen beheerde identiteit voor de toewijzing te maken en de resources te implementeren
    • Standaardinstelling voor de parameterset 'identiteit'
    • Kan niet worden gebruikt met UserAssignedIdentity

  • UserAssignedIdentity (optioneel)

    • Hiermee geeft u de door de gebruiker toegewezen beheerde identiteit op die moet worden gebruikt voor de toewijzing en om de resources te implementeren
    • Onderdeel van de parameterset 'identiteit'
    • Kan niet worden gebruikt met SystemAssignedIdentity

  • Parameter (optioneel)

    • Een hashtabel met sleutel-waardeparen voor het instellen van dynamische parameters voor de blauwdruktoewijzing

    • De standaardwaarde voor een dynamische parameter is de defaultValue in de definitie

    • Als er geen parameter is opgegeven en geen defaultValue heeft, is de parameter niet optioneel

      Notitie

      Parameter biedt geen ondersteuning voor secureStrings.

  • ResourceGroupParameter (optioneel)

    • Een hashtabel met resourcegroepartefacten
    • Elke tijdelijke aanduiding voor het artefact van de resourcegroep heeft sleutel-waardeparen voor het dynamisch instellen van naam en locatie voor dat resourcegroepartefact
    • Als er geen resourcegroepparameter is opgegeven en geen defaultValue heeft, is de parameter van de resourcegroep niet optioneel

In het volgende voorbeeld wordt de toewijzing van versie 1.1 van de blauwdrukdefinitie 'mijn blauwdruk' bijgewerkt met door Get-AzBlueprint de vergrendelingsmodus te wijzigen:

# 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

De voorbeelduitvoer voor het maken van een blauwdruktoewijzing ziet er als volgende uit:

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

Blauwdruktoewijzingen verwijderen

Wanneer het tijd is om een blauwdruktoewijzing te verwijderen, wordt deze actie door de Remove-AzBlueprintAssignment cmdlet verwerkt. De cmdlet gebruikt Name of InputObject om op te geven welke blauwdruktoewijzing moet worden verwijderd. SubscriptionId is vereist en moet in alle gevallen worden opgegeven.

In het volgende voorbeeld wordt een bestaande blauwdruktoewijzing opgehaald met en vervolgens verwijderd uit het Get-AzBlueprintAssignment specifieke abonnement dat wordt weergegeven als {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}'

Voorbeeld van code

Door alle stappen samen te brengen, haalt het volgende voorbeeld de blauwdrukdefinitie op, maakt, werkt en verwijdert u een blauwdruktoewijzing in het specifieke abonnement dat wordt weergegeven als {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

Volgende stappen