Condividi tramite

Come usare modelli di distribuzione Azure Resource Manager (ARM) con interfaccia della riga di comando di Azure

Questo articolo illustra come usare interfaccia della riga di comando di Azure con modelli arm (Azure Resource Manager) per distribuire le risorse in Azure. Se non si ha familiarità con i concetti relativi alla distribuzione e alla gestione delle soluzioni Azure, vedere panoramica della distribuzione template.

I comandi di distribuzione sono stati modificati in interfaccia della riga di comando di Azure versione 2.2.0. Gli esempi in questo articolo richiedono interfaccia della riga di comando di Azure versione 2.20.0 o successiva.

Per eseguire questo esempio, installare la versione più recente del interfaccia della riga di comando di Azure. Per iniziare, eseguire az login per creare una connessione con Azure.

Gli esempi per il interfaccia della riga di comando di Azure vengono scritti per la shell bash. Per eseguire questo esempio in Windows PowerShell o nel prompt dei comandi, potrebbe essere necessario modificare gli elementi dello script.

Se non è installato interfaccia della riga di comando di Azure, è possibile usare Azure Cloud Shell. Per ulteriori informazioni, vedere Distribuire i modelli ARM da Azure Cloud Shell.

Suggerimento

È consigliabile Bicep perché offre le stesse funzionalità dei modelli arm e la sintassi è più semplice da usare. Per altre informazioni, vedere Come distribuire le risorse con Bicep e interfaccia della riga di comando di Azure.

Prerequisiti

Autorizzazioni necessarie

Per distribuire un file Bicep o un modello di Azure Resource Manager (ARM), è necessario l'accesso in scrittura alle risorse distribuite e l'accesso a tutte le operazioni nel tipo di risorsa Microsoft.Resources/deployments. Ad esempio, per distribuire una macchina virtuale, sono necessarie autorizzazioni /Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. L'operazione di simulazione ha gli stessi requisiti di autorizzazione.

interfaccia della riga di comando di Azure versione 2.76.0 o successiva e Azure PowerShell versione 13.4.0 o successiva introducono il parametro ValidationLevel per determinare quanto accuratamente ARM convalida il modello di Bicep durante questo processo. Per altre informazioni, vedere Comandi di simulazione

Per un elenco di ruoli e autorizzazioni, vedere Azure ruoli predefiniti.

Ambito della distribuzione

È possibile impostare come destinazione il modello di distribuzione Azure a un gruppo di risorse, una sottoscrizione, un gruppo di gestione o un tenant. A seconda dell'ambito della distribuzione, vengono usati comandi diversi.

Per ogni ambito, l'utente che distribuisce il modello deve disporre delle autorizzazioni necessarie per creare risorse.

Distribuire un modello locale

È possibile distribuire un modello di ARM dal computer locale o da un modello archiviato esternamente. Questa sezione descrive la distribuzione di un modello locale.

Se si esegue la distribuzione in un gruppo di risorse che non esiste, creare il gruppo di risorse. Il nome del gruppo di risorse può contenere solo caratteri alfanumerici, punti, caratteri di sottolineatura, trattini e parentesi. Può contenere fino a 90 caratteri. Il nome non può terminare con un punto.

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

Per distribuire un modello locale, usare il parametro --template-file nel comando di distribuzione. Nell'esempio seguente viene illustrato anche come impostare un valore di parametro.

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

Il valore del parametro --template-file deve essere un file di Bicep o un file .json o .jsonc. L'estensione di file .jsonc indica che il file può contenere commenti di stile //. Il sistema ARM accetta commenti // in file .json, indipendentemente dall'estensione di file. Per altri dettagli sui commenti e i metadati, vedere Comprendere la struttura e la sintassi dei modelli di ARM.

Il completamento del modello di distribuzione Azure può richiedere alcuni minuti. Al termine, viene visualizzato un messaggio che include il risultato:

"provisioningState": "Succeeded",

Distribuire un modello remoto

Anziché archiviare i modelli di ARM nel computer locale, è consigliabile archiviarli in una posizione esterna, È possibile archiviare i modelli in un repository di controllo del codice sorgente, ad esempio GitHub. In alternativa, è possibile archiviarli in un account di archiviazione Azure per l'accesso condiviso nell'organizzazione.

Note

Per distribuire un modello o fare riferimento a un modello collegato archiviato in un repository privato GitHub, vedere una soluzione personalizzata documentata in Creating a Custom and Secure portale di Azure Offering. È possibile creare una funzione Azure che estrae il token di GitHub dalla Azure Key Vault.

Se si esegue la distribuzione in un gruppo di risorse che non esiste, creare il gruppo di risorse. Il nome del gruppo di risorse può contenere solo caratteri alfanumerici, punti, caratteri di sottolineatura, trattini e parentesi. Può contenere fino a 90 caratteri. Il nome non può terminare con un punto.

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

Per distribuire un modello esterno, usare il parametro 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

L'esempio precedente richiede l'utilizzo di un URI accessibile pubblicamente per il modello, che funziona per la maggior parte degli scenari. Il proprio modello non deve infatti includere dati sensibili. Se è necessario specificare dati riservati, ad esempio una password di amministratore, passare il valore come parametro protetto. Se, tuttavia, si vuole gestire l'accesso al modello, valutare la possibilità di usare specifiche del modello.

Per distribuire modelli collegati remoti con percorso relativo archiviati in un account di archiviazione, usare query-string per specificare il token di firma di accesso condiviso:

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

Per altre informazioni, vedere Usare il percorso relativo per i modelli collegati.

Nome del modello di distribuzione Azure

Quando si distribuisce un modello ARM, è possibile assegnare un nome al modello di distribuzione Azure. Questo nome consente di recuperare la distribuzione dalla cronologia di distribuzione. Se non si specifica un nome per la distribuzione, viene usato il nome del file modello. Ad esempio, se si distribuisce un modello denominato azuredeploy.json e non si specifica un nome di distribuzione, la distribuzione viene chiamata azuredeploy.

Ogni volta che si esegue una distribuzione, viene aggiunta una voce alla cronologia di distribuzione del gruppo di risorse con il nome della distribuzione. Se si esegue un'altra distribuzione e si assegna lo stesso nome, la voce precedente viene sostituita con la distribuzione corrente. Se si desidera mantenere voci univoche nella cronologia di distribuzione, assegnare a ogni distribuzione un nome univoco.

Per creare un nome univoco, è possibile assegnare un numero casuale.

deploymentName='ExampleDeployment'$RANDOM

In alternativa, aggiungere un valore di data.

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

Se si eseguono distribuzioni simultanee nello stesso gruppo di risorse con lo stesso nome di distribuzione, viene completata solo l'ultima distribuzione. Tutte le distribuzioni con lo stesso nome che non sono state completate vengono sostituite dall'ultima distribuzione. Ad esempio, se si esegue una distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage1 e allo stesso tempo si esegue un'altra distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage2, si distribuisce un solo account di archiviazione. L'account di archiviazione risultante è denominato storage2.

Tuttavia, se si esegue una distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage1 e subito dopo aver completato l'esecuzione di un'altra distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage2, si dispone di due account di archiviazione. Uno è denominato storage1 e l'altro è denominato storage2. Tuttavia, nella cronologia della distribuzione è presente una sola voce.

Quando si specifica un nome univoco per ogni distribuzione, è possibile eseguirli simultaneamente senza conflitti. Se si esegue una distribuzione denominata newStorage1 che distribuisce un account di archiviazione denominato storage1 e allo stesso tempo si esegue un'altra distribuzione denominata newStorage2 che distribuisce un account di archiviazione denominato storage2, sono presenti due account di archiviazione e due voci nella cronologia di distribuzione.

Per evitare conflitti con distribuzioni simultanee e per garantire voci univoche nella cronologia di distribuzione, assegnare a ogni distribuzione un nome univoco.

Distribuire la specifica di modello

Anziché distribuire un modello locale o remoto, è possibile creare una specifica template. La specifica di modello è una risorsa nella sottoscrizione Azure che contiene un modello di Resource Manager. Semplifica la condivisione sicura del modello con gli utenti dell'organizzazione. Usi il controllo degli accessi in base al ruolo di Azure (Azure RBAC) per concedere l'accesso alla specifica del modello. Questa funzionalità è attualmente in versione di anteprima.

Negli esempi seguenti viene illustrato come creare e distribuire una specifica di modello.

Prima di tutto, creare la specifica di modello specificando il modello di ARM.

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

Ottenere quindi l'ID per la specifica di modello e distribuirla.

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

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

Per altre informazioni, vedere specifiche del modello di Azure Resource Manager.

Anteprima modifiche

Prima di distribuire il modello di ARM, è possibile visualizzare in anteprima le modifiche che il modello apporterà all'ambiente. Usa l'operazione di simulazione per verificare che il modello apporti le modifiche previste. La simulazione convalida anche il modello per gli errori.

Parametri

Per passare i valori dei parametri, è possibile usare i parametri inline o un file di parametri. Il file dei parametri può essere un file di parametri Bicep o un file di parametri JSON.

Parametri inline

Per passare i parametri inline, specificare i valori in parameters. Ad esempio, per passare una stringa e una matrice a un modello in una shell Bash, usare:

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

Se stai usando interfaccia della riga di comando di Azure con il Prompt dei comandi di Windows (CMD) o PowerShell, passa la matrice nel formato exampleArray="['value1','value2']".

È anche possibile ottenere i contenuti del file e fornire il contenuto come un parametro inline.

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

Ottenere un valore di parametro da un file è utile quando è necessario fornire i valori di configurazione. Ad esempio, è possibile fornire i valori cloud-init per una macchina virtuale Linux.

Il formato arrayContent.json è:

[
  "value1",
  "value2"
]

Per passare un oggetto, ad esempio, per impostare i tag, usare JSON. Ad esempio, il modello potrebbe includere un parametro simile al seguente:

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

In questo caso, è possibile passare una stringa JSON per impostare il parametro come illustrato nello script Bash seguente:

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

Usare virgolette doppie intorno al codice JSON che si vuole passare all'oggetto.

È possibile usare una variabile per contenere i valori dei parametri. In Bash impostare la variabile su tutti i valori dei parametri e aggiungerla al comando di distribuzione.

params="prefix=start suffix=end"

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

Tuttavia, se si usa interfaccia della riga di comando di Azure con il prompt dei comandi di Windows (CMD) o PowerShell, impostare la variabile su una stringa JSON. Escape delle virgolette: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

File di parametri JSON

Invece di passare parametri come valori inline nello script, potrebbe risultare più semplice usare un file di parametri, un file .bicepparam o un file di parametri JSON, che contiene i valori dei parametri. Il file dei parametri deve essere un file locale. I file di parametri esterni non sono supportati con interfaccia della riga di comando di Azure.

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

Per altre informazioni sul file di parametri, vedere Creare Resource Manager file di parametri.

Bicep file di parametri

Con interfaccia della riga di comando di Azure versione 2.53.0 o successiva e Bicep CLI versione 0.22.6 o successiva, è possibile distribuire un file Bicep utilizzando un file di parametri Bicep. Con l'istruzione using all'interno del file dei parametri di Bicep, non è necessario fornire l'opzione --template-file quando si specifica un file di parametri Bicep per l'opzione --parameters. L'inclusione dell'opzione --template-file genera un errore, "Solo un file .bicep è consentito con un file .bicepparam".

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

Il file dei parametri deve essere un file locale. I file di parametri esterni non sono supportati con interfaccia della riga di comando di Azure. Per altre informazioni sul file dei parametri, vedere Creare Resource Manager file di parametri.

Commenti e formato JSON esteso

È possibile includere commenti di stile // nel file di parametri, ma è necessario assegnare al file un nome con estensione .jsonc.

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

Per altri dettagli sui commenti e i metadati, vedere Comprendere la struttura e la sintassi dei modelli di Azure Resource Manager.

Se si usa interfaccia della riga di comando di Azure con la versione 2.3.0 o precedente, è possibile distribuire un modello con stringhe o commenti su più righe usando l'opzione --handle-extended-json-format. Ad esempio:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2025-04-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'))]"
  ],

Passaggi successivi

  • Last updated on