Så här använder du ARM-distributionsmallar (Azure Resource Manager) med Azure CLI

  • Artikel

Den här artikeln beskriver hur du använder Azure CLI med Azure Resource Manager-mallar (ARM-mallar) för att distribuera dina resurser till Azure. Om du inte är bekant med begreppen för att distribuera och hantera dina Azure-lösningar kan du läsa översikt över malldistribution.

Distributionskommandona ändrades i Azure CLI version 2.2.0. Exemplen i den här artikeln kräver Azure CLI version 2.20.0 eller senare.

Om du vill köra det här exemplet installerar du den senaste versionen av Azure CLI. Börja genom att köra az login för att upprätta en anslutning med Azure.

Exempel för Azure CLI skrivs för bash gränssnittet. Om du vill köra det här exemplet i Windows PowerShell eller kommandotolken kan du behöva ändra element i skriptet.

Om du inte har Installerat Azure CLI kan du använda Azure Cloud Shell. Mer information finns i Distribuera ARM-mallar från Azure Cloud Shell.

Dricks

Vi rekommenderar Bicep eftersom det erbjuder samma funktioner som ARM-mallar och syntaxen är enklare att använda. Mer information finns i Distribuera resurser med Bicep och Azure CLI.

Behörigheter som krävs

Om du vill distribuera en Bicep-fil eller en ARM-mall måste du ha skrivåtkomst till de resurser som du distribuerar och åtkomst till alla åtgärder i resurstypen Microsoft.Resources/deployments. Om du till exempel vill distribuera en virtuell dator behöver Microsoft.Compute/virtualMachines/write du och Microsoft.Resources/deployments/* behörigheter. Konsekvensåtgärden har samma behörighetskrav.

Det finns en lista med roller och behörigheter i Inbyggda roller i Azure.

Distributionsomfång

Du kan rikta din Azure-distributionsmall mot en resursgrupp, prenumeration, hanteringsgrupp eller klientorganisation. Beroende på omfånget för distributionen använder du olika kommandon.

För varje omfång måste användaren som distribuerar mallen ha de behörigheter som krävs för att skapa resurser.

Distribuera en lokal mall

Du kan distribuera en ARM-mall från den lokala datorn eller en som lagras externt. I det här avsnittet beskrivs hur du distribuerar en lokal mall.

Om du distribuerar till en resursgrupp som inte finns skapar du resursgruppen. Namnet på resursgruppen kan bara innehålla alfanumeriska tecken, punkter, understreck, bindestreck och parenteser. Det kan vara upp till 90 tecken. Namnet kan inte sluta i en punkt.

az group create --name ExampleGroup --location "Central US"

Om du vill distribuera en lokal mall använder du parametern --template-file i distributionskommandot. I följande exempel visas också hur du anger ett parametervärde.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

Värdet för parametern --template-file måste vara en Bicep-fil eller en .json eller .jsonc -fil. Filnamnstillägget .jsonc anger att filen kan innehålla // formatkommentarer. ARM-systemet accepterar // kommentarer i .json filer. Det bryr sig inte om filnamnstillägget. Mer information om kommentarer och metadata finns i Förstå strukturen och syntaxen för ARM-mallar.

Det kan ta några minuter att slutföra Azure-distributionsmallen. När det är klart visas ett meddelande som innehåller resultatet:

"provisioningState": "Succeeded",

Distribuera fjärrmall

I stället för att lagra ARM-mallar på den lokala datorn kanske du föredrar att lagra dem på en extern plats. Du kan lagra mallar på en lagringsplats för versionskontroll (till exempel GitHub). Eller så kan du lagra dem i ett Azure Storage-konto för delad åtkomst i din organisation.

Kommentar

Om du vill distribuera en mall eller referera till en länkad mall som lagras i en privat GitHub-lagringsplats kan du läsa en anpassad lösning som beskrivs i Skapa ett anpassat och säkert Azure Portal-erbjudande. Du kan skapa en Azure-funktion som hämtar GitHub-token från Azure Key Vault.

Om du distribuerar till en resursgrupp som inte finns skapar du resursgruppen. Namnet på resursgruppen kan bara innehålla alfanumeriska tecken, punkter, understreck, bindestreck och parenteser. Det kan vara upp till 90 tecken. Namnet kan inte sluta i en punkt.

az group create --name ExampleGroup --location "Central US"

Om du vill distribuera en extern mall använder du parametern template-uri.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

Föregående exempel kräver en offentligt tillgänglig URI för mallen, som fungerar för de flesta scenarier eftersom mallen inte ska innehålla känsliga data. Om du behöver ange känsliga data (till exempel ett administratörslösenord) skickar du det värdet som en säker parameter. Men om du vill hantera åtkomsten till mallen bör du överväga att använda mallspecifikationer.

Om du vill distribuera fjärrlänkade mallar med relativ sökväg som lagras i ett lagringskonto använder du query-string för att ange SAS-token:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

Mer information finns i Använda relativ sökväg för länkade mallar.

Namn på Azure-distributionsmall

När du distribuerar en ARM-mall kan du ge Azure-distributionsmallen ett namn. Det här namnet kan hjälpa dig att hämta distributionen från distributionshistoriken. Om du inte anger något namn för distributionen används namnet på mallfilen. Om du till exempel distribuerar en mall med namnet azuredeploy.json och inte anger något distributionsnamn, heter azuredeploydistributionen .

Varje gång du kör en distribution läggs en post till i resursgruppens distributionshistorik med distributionsnamnet. Om du kör en annan distribution och ger den samma namn ersätts den tidigare posten med den aktuella distributionen. Om du vill behålla unika poster i distributionshistoriken ger du varje distribution ett unikt namn.

Om du vill skapa ett unikt namn kan du tilldela ett slumptal.

deploymentName='ExampleDeployment'$RANDOM

Eller lägg till ett datumvärde.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

Om du kör samtidiga distributioner till samma resursgrupp med samma distributionsnamn slutförs endast den senaste distributionen. Alla distributioner med samma namn som inte har slutförts ersätts av den senaste distributionen. Om du till exempel kör en distribution med namnet newStorage som distribuerar ett lagringskonto med namnet storage1och samtidigt kör en annan distribution med namnet newStorage som distribuerar ett lagringskonto med namnet storage2distribuerar du bara ett lagringskonto. Det resulterande lagringskontot heter storage2.

Men om du kör en distribution med namnet newStorage som distribuerar ett lagringskonto med namnet storage1och omedelbart efter att den har slutförts kör du en annan distribution med namnet newStorage som distribuerar ett lagringskonto med namnet storage2, så har du två lagringskonton. Den ena heter storage1och den andra heter storage2. Men du har bara en post i distributionshistoriken.

När du anger ett unikt namn för varje distribution kan du köra dem samtidigt utan konflikter. Om du kör en distribution med namnet newStorage1 som distribuerar ett lagringskonto med namnet storage1och samtidigt kör en annan distribution med namnet newStorage2 som distribuerar ett lagringskonto med namnet storage2, har du två lagringskonton och två poster i distributionshistoriken.

För att undvika konflikter med samtidiga distributioner och för att säkerställa unika poster i distributionshistoriken ger du varje distribution ett unikt namn.

Distribuera mallspecifikation

I stället för att distribuera en lokal mall eller fjärrmall kan du skapa en mallspecifikation. Mallspecifikationen är en resurs i din Azure-prenumeration som innehåller en ARM-mall. Det gör det enkelt att på ett säkert sätt dela mallen med användare i din organisation. Du använder rollbaserad åtkomstkontroll i Azure (Azure RBAC) för att ge åtkomst till mallspecifikationen. Den här funktionen är för närvarande i förhandsversion.

I följande exempel visas hur du skapar och distribuerar en mallspecifikation.

Skapa först mallspecifikationen genom att ange ARM-mallen.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

Hämta sedan ID:t för mallspecifikationen och distribuera det.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Mer information finns i Mallspecifikationer för Azure Resource Manager.

Förhandsgranska ändringar

Innan du distribuerar ARM-mallen kan du förhandsgranska de ändringar som mallen gör i din miljö. Använd konsekvensåtgärden för att kontrollera att mallen gör de ändringar som du förväntar dig. What-if validerar även mallen för fel.

Parametrar

Om du vill skicka parametervärden kan du använda antingen infogade parametrar eller en parameterfil. Parameterfilen kan vara antingen en Bicep-parameterfil eller en JSON-parameterfil.

Infogade parametrar

Om du vill skicka infogade parametrar anger du värdena i parameters. Om du till exempel vill skicka en sträng och matris till en mall i ett Bash-gränssnitt använder du:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

Om du använder Azure CLI med Windows-kommandotolken (CMD) eller PowerShell skickar du matrisen i formatet: exampleArray="['value1','value2']".

Du kan också hämta innehållet i filen och ange innehållet som en infogad parameter.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

Det är praktiskt att hämta ett parametervärde från en fil när du behöver ange konfigurationsvärden. Du kan till exempel ange cloud-init-värden för en virtuell Linux-dator.

Formatet arrayContent.json är:

[
  "value1",
  "value2"
]

Om du till exempel vill skicka in ett objekt för att ange taggar använder du JSON. Mallen kan till exempel innehålla en parameter som den här:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

I det här fallet kan du skicka in en JSON-sträng för att ange parametern enligt följande Bash-skript:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Använd dubbla citattecken runt den JSON som du vill skicka till objektet.

Du kan använda en variabel för att innehålla parametervärdena. I Bash anger du variabeln till alla parametervärden och lägger till den i distributionskommandot.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

Men om du använder Azure CLI med Windows Command Prompt (CMD) eller PowerShell anger du variabeln till en JSON-sträng. Undvik citattecknen: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

JSON-parameterfiler

I stället för att skicka parametrar som infogade värden i skriptet kan det vara enklare att använda en parameterfil, antingen en .bicepparam fil eller en JSON-parameterfil, som innehåller parametervärdena. Parameterfilen måste vara en lokal fil. Externa parameterfiler stöds inte med Azure CLI.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

Mer information om parameterfilen finns i Skapa en parameterfil för Resource Manager.

Bicep-parameterfiler

Med Azure CLI version 2.53.0 eller senare och Bicep CLI version 0.22.6 eller senare kan du distribuera en Bicep-fil genom att använda en Bicep-parameterfil. Med -instruktionen using i Bicep-parameterfilen behöver du inte ange växeln --template-file när du anger en Bicep-parameterfil för växeln --parameters . Om du inkluderar växeln --template-file resulterar det i felet "Endast en .bicep-mall tillåts med en .bicepparam-fil".

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Parameterfilen måste vara en lokal fil. Externa parameterfiler stöds inte med Azure CLI. Mer information om parameterfilen finns i Skapa Resource Manager-parameterfil.

Kommentarer och det utökade JSON-formatet

Du kan inkludera // formatkommentare i parameterfilen, men du måste namnge filen med ett .jsonc tillägg.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

Mer information om kommentarer och metadata finns i Förstå strukturen och syntaxen för ARM-mallar.

Om du använder Azure CLI med version 2.3.0 eller senare kan du distribuera en mall med flerradssträngar eller kommentarer med hjälp av växeln --handle-extended-json-format . Till exempel:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Nästa steg