Specifiche di modello di Azure Resource Manager in Bicep

Articolo
03/19/2024

Una specifica di modello è un tipo di risorsa per l'archiviazione di un modello di Azure Resource Manager (Modello di ARM) per la sua distribuzione in un secondo momento. Questo tipo di risorsa consente di condividere modelli di ARM con altri utenti della tua organizzazione. Proprio come ogni altra risorsa di Azure, è possibile usare il controllo degli accessi in base al ruolo di Azure per condividere la specifica di modello. È possibile utilizzare l'interfaccia della riga di comando di Azure o Azure PowerShell per creare specifiche di modello fornendo file Bicep. I file Bicep vengono sottoposti a transpile in modelli JSON ARM prima di essere archiviati. Attualmente non è possibile importare un file Bicep dal portale di Azure per creare una risorsa specifica di modello.

La specifica di modello è un tipo di risorsa denominato Microsoft.Resources/templateSpecs. È costituito da un modello principale e da un qualsiasi numero di modelli collegati. Azure archivia in modo sicuro le specifiche di modello nei gruppi di risorse. Sia il modello principale che i modelli collegati devono essere in JSON. Le specifiche di modello supportano il controllo delle versioni.

Per distribuire la specifica di modello, si usano strumenti di Azure standard come PowerShell, interfaccia della riga di comando di Azure, portale di Azure, REST e altri SDK e client supportati. Si utilizzano gli stessi comandi del modello o del file Bicep.

Nota

Per usare le specifiche di modello in Bicep con Azure PowerShell, è necessario installare la versione 6.3.0 o successiva. Per usarle con l'interfaccia della riga di comando di Azure, utilizzare la versione 2.27.0 o successiva.

Quando si pianifica la distribuzione, considerare sempre il ciclo di vita delle risorse e raggruppare le risorse che condividono un ciclo di vita simile in una singola specifica di modello. Ad esempio, le distribuzioni includono più istanze di Azure Cosmos DB, ognuna delle quali contiene i propri database e container. Dato che i database e i container non cambiano molto, si vuole creare una specifica di modello che includa un'istanza di Cosmo DB e i relativi database e container sottostanti. È quindi possibile usare istruzioni condizionali in Bicep insieme ai cicli di copia per creare più istanze di queste risorse.

Suggerimento

La scelta tra il modulo del registro di sistema e le specifiche di modello è principalmente una questione di preferenza. Quando si sceglie tra i due, è necessario considerare alcuni aspetti:

Il modulo del registro di sistema è supportato solo da Bicep. Se ancora non usi Bicep, usare le specifiche del modello.
Il contenuto del registro di sistema del modulo Bicep può essere distribuito solo da un altro file Bicep. Le specifiche dei modelli possono essere distribuite direttamente dall’API, da Azure PowerShell, dall'interfaccia della riga di comando di Azure e dal portale di Azure. È anche possibile usare UiFormDefinition per personalizzare l'esperienza di distribuzione del portale.
Bicep include alcune funzionalità limitate per incorporare altri artefatti del progetto (inclusi i file non Bicep e non modello ARM. Ad esempio, script di PowerShell, script dell'interfaccia della riga di comando e altri file binari) usando le funzioni loadTextContent e loadFileAsBase64. Le specifiche di modello non possono creare pacchetti di questi artefatti.

Risorse di formazione

Per ulteriori informazioni sulle specifiche di modello e per la guida pratica, vedere Pubblicare librerie di codice dell'infrastruttura riutilizzabile usando le specifiche di modello.

Autorizzazioni necessarie

Esistono due ruoli integrati di Azure definiti per la specifica di modello:

Inoltre, sono necessarie anche le autorizzazioni per distribuire un file Bicep. Vedere Distribuire - Interfaccia della riga di comando o Distribuire - PowerShell.

Perché usare le specifiche di modello?

Le specifiche di modello offrono i seguenti vantaggi:

Si usano modelli ARM standard o file Bicep per la specifica del modello.
È possibile gestire l'accesso tramite il controllo degli accessi in base al ruolo di Azure, anziché i token di firma di accesso condiviso.
Gli utenti possono distribuire la specifica di modello senza avere accesso in scrittura al file Bicep.
È possibile integrare la specifica di modello nel processo di distribuzione esistente, ad esempio script di PowerShell o pipeline DevOps.

Le specifiche di modello consentono di creare modelli canonici e condividerli con i team della tua organizzazione. Le specifiche del modello sono sicure perché sono disponibili per Azure Resource Manager per la distribuzione, ma non accessibili agli utenti senza l'autorizzazione corretta. Gli utenti devono solo accedere in lettura alla specifica di modello per distribuirne il modello, in modo da poterlo condividere senza consentire ad altri utenti di modificarlo.

Se attualmente i modelli sono disponibili in un repository GitHub o in un account di archiviazione, potresti avere diversi problemi quando provi a condividere ed usare i modelli. Per distribuire il modello, devi rendere il modello accessibile pubblicamente o gestire l'accesso con token di firma di accesso condiviso. Per aggirare questa limitazione, gli utenti potrebbero creare copie locali, che alla fine differiscono dal modello originale. Le specifiche dei modelli semplificano la condivisione dei modelli.

I modelli inclusi in una specifica di modello devono essere verificati dagli amministratori della tua organizzazione per rispettare i requisiti e le indicazioni dell'organizzazione.

Creare la specifica di modello

L'esempio seguente illustra un semplice file Bicep per la creazione di un account di archiviazione in Azure.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Creare una specifica di modello usando:

PowerShell
CLI

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

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

Puoi creare specifiche di modello usando i file Bicep. Tuttavia, il contenuto di mainTemplate deve essere in JSON. Il modello seguente crea una specifica di modello da distribuire in un account di archiviazione:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2021-05-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

Il modello JSON incorporato nel file Bicep deve apportare queste modifiche:

Rimuovere le virgole alla fine delle righe.
Sostituire le virgolette doppie con virgolette singole.
Eliminate le virgolette singole all'interno delle espressioni. Ad esempio, 'name': '[parameters(\'storageAccountType\')]'.
Per accedere ai parametri e alle variabili definiti nel file Bicep, è possibile usare direttamente i nomi dei parametri e i nomi delle variabili. Per accedere ai parametri e alle variabili definiti in mainTemplate, è comunque necessario usare la sintassi del modello JSON ARM. Ad esempio, 'name': '[parameters(\'storageAccountType\')]'.
Usare la sintassi Bicep per chiamare le funzioni Bicep. Ad esempio, 'location': resourceGroup().location.

Le dimensioni di una specifica di modello sono limitate a circa 2 MB. Se una dimensione della specifica di modello supera il limite, si otterrà il codice di errore TemplateSpecTooLarge . Il messaggio di errore indica:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Puoi visualizzare tutte le specifiche di modello nella sottoscrizione usando:

PowerShell
CLI

Get-AzTemplateSpec

az ts list

Puoi visualizzare i dettagli di una specifica di modello, incluse le relative versioni, con:

PowerShell
CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

Distribuire la specifica di modello

Dopo aver creato la specifica del modello, gli utenti con il ruolo lettore Specifiche modello possono distribuirlo. Inoltre, sono necessarie anche le autorizzazioni per la distribuzione di un modello di ARM. Vedere Distribuire - Interfaccia della riga di comando o Distribuire - PowerShell.

Le specifiche di modello possono essere distribuite tramite il portale, PowerShell, l'interfaccia della riga di comando di Azure o come modulo Bicep in una distribuzione di modelli più grande. Gli utenti di un'organizzazione possono distribuire una specifica di modello in qualsiasi ambito in Azure (gruppo di risorse, sottoscrizione, gruppo di gestione o tenant).

Anziché passare un percorso o un URI per un file Bicep, si distribuisce una specifica di modello specificandone l'ID risorsa. L'ID risorsa ha il seguente formato:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Si noti che l'ID risorsa include un nome di versione per la specifica di modello.

Ad esempio, si distribuisce una specifica di modello con il comando seguente.

PowerShell
CLI

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

In pratica, solitamente si eseguirà Get-AzTemplateSpec o az ts show per ottenere l'ID della specifica di modello che si vuole distribuire.

PowerShell
CLI

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

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

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

È anche possibile aprire un URL nel formato seguente per distribuire una specifica di modello:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Parametri

Il passaggio di parametri alla specifica di modello è simile al passaggio di parametri a un file Bicep. Aggiungere i valori dei parametri inline o in un file di parametri.

Parametri inline

Per passare un parametro inline, usare:

PowerShell
CLI

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

File dei parametri

Usare il file dei parametri Bicep

Per creare un file di parametri Bicep, è necessario specificare l'istruzione using . Ecco un esempio:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Per ulteriori informazioni, vedere File di parametri Bicep.

Per passare il file di parametri con:
- PowerShell
- CLI
Attualmente, non è possibile distribuire una specifica di modello con un file con estensione .bicepparam usando Azure PowerShell.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
A causa dell'istruzione using nel file .bicepparam. Non è necessario specificare il parametro --template-spec .

Usare il file dei parametri JSON

Il JSON seguente è un esempio di file dei parametri JSON:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

Passare anche il file dei parametri con:

PowerShell
CLI

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

Controllo delle versioni

Quando si crea una specifica di modello, è necessario specificare un nome di versione. Durante l'iterazione del codice del modello, è possibile aggiornare una versione esistente (per gli hotfix) o pubblicare una nuova versione. La versione è una stringa di testo. È possibile scegliere di seguire qualsiasi sistema di controllo delle versioni, incluso il versionamento semantico. Gli utenti della specifica di modello possono specificare il nome della versione che vogliono usare durante la distribuzione. È possibile disporre di un numero illimitato di versioni.

Usare i tag

I tag consentono di organizzare le risorse in modo logico. È possibile aggiungere tag alle specifiche dei modelli usando Azure PowerShell e l'interfaccia della riga di comando di Azure. Nell'esempio seguente viene illustrato come specificare i tag durante la creazione della specifica di modello:

PowerShell
CLI

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

L'esempio seguente spiega come applicare i tag durante l'aggiornamento di una specifica di modello esistente:

PowerShell
CLI

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

Sia il modello che le relative versioni possono avere tag. I tag vengono applicati o ereditati a seconda dei parametri specificati dall’utente.

Specifica di modello	Versione	Parametro versione	Parametro tag	Valori tag
Exists	N/D	Non specificato	Specificato	applicato alla specifica di modello
Exists	Nuovo	Specificato	Non specificato	ereditato dalla specifica di modello alla versione
Nuovo	Nuovo	Specificato	Specificato	applicato sia alla specifica di modello che alla versione
Exists	Nuovo	Specificato	Specificato	applicato alla versione
Exists	Exists	Specificato	Specificato	applicato alla versione

Collegamento alle specifiche di modello

Dopo aver creato una specifica di modello, è possibile collegarsi a tale specifica di modello in un modulo Bicep. La specifica di modello viene distribuita quando si distribuisce il file Bicep contenente tale modulo. Per ulteriori informazioni, vedere File nella specifica di modello.

Per creare alias per le specifiche di modello destinate al collegamento del modulo, vedere Alias per i moduli.

Passaggi successivi