Come distribuire le risorse con Bicep e l'interfaccia della riga di comando di Azure

  • Articolo

Questo articolo illustra come usare l'interfaccia della riga di comando di Azure con i file Bicep per distribuire le risorse in Azure. Per comprendere i concetti di distribuzione e gestione delle soluzioni di Azure, vedere Panoramica di Bicep.

Prerequisiti

È necessario un file Bicep da distribuire. Il file deve essere locale.

È necessaria l'interfaccia della riga di comando di Azure e per la connessione ad Azure:

  • Installare i comandi dell'interfaccia della riga di comando di Azure nel computer locale. Per distribuire i file Bicep, è necessaria l'interfaccia della riga di comando di Azure versione 2.20.0 o successiva.
  • Connessione ad Azure usando az login. Se si hanno più sottoscrizioni di Azure, potrebbe anche essere necessario eseguire az account set.

Gli esempi per l'interfaccia della riga di comando di Azure sono 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 è installata l'interfaccia della riga di comando di Azure, è possibile usare Azure Cloud Shell. Per altre informazioni, vedere Distribuire file Bicep da Azure Cloud Shell.

Autorizzazioni necessarie

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

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

Ambito di distribuzione

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

Per ogni ambito, l'utente che distribuisce il file Bicep deve avere le autorizzazioni necessarie per creare risorse.

Distribuire il file Bicep locale

È possibile distribuire un file Bicep dal computer locale o da uno archiviato esternamente. Questa sezione descrive la distribuzione di un file Bicep 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 file Bicep locale, usare l'opzione --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-bicep> \
  --parameters storageAccountType=Standard_GRS

Per il completamento della distribuzione sarà necessario attendere alcuni minuti. Al termine, viene visualizzato un messaggio che include il risultato:

"provisioningState": "Succeeded",

Distribuire un file Bicep remoto

Attualmente l'interfaccia della riga di comando di Azure non supporta la distribuzione di file Bicep remoti. È possibile usare l'interfaccia della riga di comando di Bicep per compilare il file Bicep in un modello JSON e quindi caricare il file JSON nel percorso remoto. Per altre informazioni, vedere Distribuire modelli JSON arm remoti.

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 file Bicep in una shell Bash, usare:

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

Se si usa l'interfaccia della riga di comando di Azure con il prompt dei comandi di Windows (CMD) o PowerShell, passare la matrice nel formato : exampleArray="['value1','value2']".

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

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --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 file Bicep 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 $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

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

Se si usa l'interfaccia della riga di comando di Azure con il prompt dei comandi di Windows o PowerShell, passare l'oggetto nel formato seguente:

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

È 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-bicep> \
  --parameters $params

Tuttavia, se si usa l'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\"} }'.

La valutazione dei parametri segue un ordine sequenziale, ovvero se un valore viene assegnato più volte, viene usato solo l'ultimo valore assegnato. Per garantire l'assegnazione corretta dei parametri, è consigliabile specificare inizialmente il file dei parametri ed eseguire l'override selettivo di parametri specifici usando la sintassi KEY=VALUE . È importante ricordare che se si specifica un bicepparam file di parametri, è possibile usare questo argomento una sola volta.

File di parametri Bicep

Invece di passare parametri come valori inline nello script, potrebbe risultare più semplice usare un file di parametri, un file di parametri Bicep 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 l'interfaccia della riga di comando di Azure. Per altre informazioni sul file dei parametri, vedere Creare un file di parametri di Resource Manager.

Con l'interfaccia della riga di comando di Azure versione 2.53.0 o successiva e l'interfaccia della riga di comando di Bicep versione 0.22.X o successiva, è possibile distribuire un file Bicep usando un file di parametri Bicep. Con l'istruzione using all'interno del file di parametri 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 genererà un errore "È consentito solo un modello con estensione bicep con un file con estensione bicepparam".

L'esempio seguente mostra un file di parametri denominato storage.bicepparam. Il file si trova nella stessa directory in cui viene eseguito il comando.

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

File di parametri JSON

Nell'esempio seguente viene illustrato un file di parametri denominato storage.parameters.json. Il file si trova nella stessa directory in cui viene eseguito il comando.

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

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

È possibile usare parametri inline e un file di parametri di posizione nella stessa operazione di distribuzione. Per altre informazioni, vedere Precedenza dei parametri.

Anteprima modifiche

Prima di distribuire il file Bicep, è possibile visualizzare in anteprima le modifiche apportate al file Bicep nell'ambiente. Usare l'operazione di simulazione per verificare che il file Bicep apporti le modifiche previste. La simulazione convalida anche il file Bicep per gli errori.

Distribuire la specifica di modello

Attualmente, l'interfaccia della riga di comando di Azure non supporta la creazione di specifiche di modello fornendo file Bicep. È tuttavia possibile creare un file Bicep con la risorsa Microsoft.Resources/templateSpecs per distribuire una specifica di modello. L'esempio Crea campione specifica di modella mostra come creare una specifica di modello in un file Bicep. È anche possibile compilare il file Bicep in JSON usando l'interfaccia della riga di comando di Bicep e quindi creare una specifica di modello con il modello JSON.

Nome distribuzione

Quando si distribuisce un file Bicep, è possibile assegnare un nome alla distribuzione. 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 Bicep. Ad esempio, se si distribuisce un file Bicep denominato main.bicep e non si specifica un nome di distribuzione, la distribuzione è denominata main.

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 univoce 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 storage1e 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 storage1e 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 storage1e allo stesso tempo si esegue un'altra distribuzione denominata newStorage2che 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.

Passaggi successivi