Condividi tramite

Distribuire file Bicep con Azure PowerShell

  • Articolo

Questo articolo illustra come usare Azure PowerShell con i file Bicep per distribuire le risorse in Azure. Se non si ha familiarità con la distribuzione e la gestione delle soluzioni di Azure, vedere Che cos'è Bicep?.

Prerequisiti

È necessario un file Bicep da distribuire e il file deve essere locale. È anche necessario Azure PowerShell e per essere connessi ad Azure:

  • Installare i cmdlet di Azure PowerShell nel computer locale. Per distribuire i file Bicep, è necessario Azure PowerShell versione 5.6.0 o successiva. Per altre informazioni, vedere Get started with Azure PowerShell (Introduzione ad Azure PowerShell).
  • Installare l'interfaccia della riga di comando di Bicep. È necessario installare manualmente l'interfaccia della riga di comando di Bicep perché Azure PowerShell non lo installa automaticamente.
  • Usare Connect-AzAccount per connettersi ad Azure. Se si dispone di più sottoscrizioni di Azure, potrebbe essere necessario eseguire Set-AzContextanche . Per altre informazioni, vedere Use multiple Azure subscriptions (Usare più sottoscrizioni di Azure).

Se PowerShell non è installato, è possibile usare Azure Cloud Shell. Per altre informazioni, vedere Distribuire file Bicep con 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, si usano comandi diversi e l'utente che distribuisce il file Bicep deve avere le autorizzazioni necessarie per creare risorse per ogni ambito.

Distribuire il file Bicep locale

Questa sezione descrive come distribuire un file Bicep locale. È possibile distribuire un file Bicep dal computer locale o da uno esterno.

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 e non può terminare in un punto.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Per distribuire un file Bicep locale, usare l'opzione -TemplateFile nel comando di distribuzione:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile <path-to-bicep>

Il completamento della distribuzione può richiedere alcuni minuti.

Distribuire un file Bicep remoto

Azure PowerShell attualmente 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 in un percorso remoto. Per altre informazioni, vedere Distribuire un modello remoto.

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 nomi del parametro con il comando New-AzResourceGroupDeployment. Ad esempio, per passare una stringa e una matrice a un file Bicep, usare:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -exampleString "inline string" `
  -exampleArray $arrayParam

È possibile usare il TemplateParameterObject parametro per passare attraverso una tabella hash contenente i parametri per il modello:

$params = @{
  exampleString = "inline string"
  exampleArray = "value1", "value2"
}

New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -TemplateParameterObject $params

È anche possibile ottenere il contenuto del file e fornire tale contenuto come parametro inline:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

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.

Se è necessario passare una matrice di oggetti, creare tabelle hash in Azure PowerShell e aggiungerle a una matrice. Passare tale matrice come parametro durante la distribuzione:

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -exampleArray $subnetArray

File di parametri Bicep

Anziché passare parametri come valori inline nello script, potrebbe risultare più semplice usare un file di parametri Bicep o un file di parametri JSON che contiene i valori dei parametri. Il file dei parametri Bicep deve essere un file locale, mentre il file modello JSON può trovarsi in un punto qualsiasi online. Per altre informazioni sui file di parametri, vedere Creare file di parametri per la distribuzione Bicep.

È possibile usare un file di parametri Bicep per distribuire un file Bicep con Azure PowerShell versione 10.4.0 o successiva e Bicep cli versione 0.22.X o successiva. Con l'istruzione using all'interno del file di parametri Bicep, non è necessario fornire l'opzione -TemplateFile quando si specifica un file di parametri Bicep per l'opzione -TemplateParameterFile .

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

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateParameterFile storage.bicepparam

File di parametri JSON

Il file di parametri JSON può essere locale o esterno con un URI accessibile.

Per passare un file di parametri locali, usare l'opzione TemplateParameterFile con un file di parametri JSON:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\BicepFiles\storage.bicep `
  -TemplateParameterFile c:\BicepFiles\storage.parameters.json

Per passare un file di parametri esterni, usare il parametro TemplateParameterUri:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\BicepFiles\storage.bicep `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json

Poiché il TemplateParameterUri parametro supporta solo i file di parametri JSON, non supporta i .bicepparam file.

È 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

Azure PowerShell attualmente non fornisce file Bicep per creare specifiche di modello. È tuttavia possibile creare un file Bicep con la risorsa Microsoft.Resources/templateSpecs per distribuire una specifica di modello. L'esempio create template spec illustra 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 un modello JSON per creare una specifica di modello.

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, il nome diventa 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 univoche nella cronologia di distribuzione, assegnare a ogni distribuzione un nome univoco.

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

$suffix = Get-Random -Maximum 1000
$deploymentName = "ExampleDeployment" + $suffix

In alternativa, aggiungere un valore di data:

$today=Get-Date -Format "MM-dd-yyyy"
$deploymentName="ExampleDeployment"+"$today"

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 ed esegue un'altra distribuzione denominata newStorage che distribuisce un account di archiviazione denominato storage2 contemporaneamente, 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 ed esegue immediatamente un'altra distribuzione denominata che distribuisce un account di archiviazione denominato newStorage storage2 dopo il completamento della prima distribuzione, sono disponibili 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 ed esegue un'altra distribuzione denominata newStorage2 che distribuisce un account di archiviazione denominato storage2 contemporaneamente, 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

Per informazioni su come definire i parametri nel file, vedere Comprendere la struttura e la sintassi dei file Bicep.