Specifiche di modello di Azure Resource Manager

  • Articolo

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 dell’organizzazione. Proprio come ogni altra risorsa di Azure, è possibile usare il controllo degli accessi in base al ruolo di Azure (RBAC Azure) per condividere la specifica di modello.

Microsoft.Resources/templateSpecs è il tipo di risorsa per le specifiche di modello. È 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. 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. Usare gli stessi comandi che si userebbero per il modello.

Nota

Per usare le specifiche di modello con Azure PowerShell, è necessario installare versione 5.0.0 o successiva. Per usarla con l'interfaccia della riga di comando di Azure, usare la versione 2.14.2 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 nei modelli insieme ai cicli di copia per creare più istanze di queste risorse.

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.

Suggerimento

È consigliabile Bicep perché offre le stesse funzionalità dei modelli di ARM e la sintassi è più semplice da usare. Per ulteriori informazioni, vedere Specifiche di modello di Azure Resource Manager in Bicep.

Perché usare le specifiche di modello?

Le specifiche di modello offrono i seguenti vantaggi:

  • Si usano modelli di ARM standard per la specifica di 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 modello.
  • È 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 dell’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 dell’organizzazione per rispettare i requisiti e le indicazioni dell'organizzazione.

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.

Creare la specifica di modello

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

{
  "$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": "[concat('store', uniquestring(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "kind": "StorageV2",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      }
    }
  ]
}

Quando si crea la specifica di modello, i comandi di PowerShell o dell'interfaccia della riga di comando vengono passati al file modello principale. Se il modello principale fa riferimento a modelli collegati, i comandi li troveranno e li raggrupperanno per creare la specifica di modello. Per ulteriori informazioni, vedere Creare una specifica di modello con modelli collegati.

Creare una specifica di modello usando:

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

Puoi creare specifiche di modello usando modelli di ARM. Il modello seguente crea una specifica di modello per distribuire un account di archiviazione:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "templateSpecName": {
      "type": "string",
      "defaultValue": "CreateStorageAccount"
    },
    "templateSpecVersionName": {
      "type": "string",
      "defaultValue": "0.1"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/templateSpecs",
      "apiVersion": "2021-05-01",
      "name": "[parameters('templateSpecName')]",
      "location": "[parameters('location')]",
      "properties": {
        "description": "A basic templateSpec - creates a storage account.",
        "displayName": "Storage account (Standard_LRS)"
      }
    },
    {
      "type": "Microsoft.Resources/templateSpecs/versions",
      "apiVersion": "2021-05-01",
      "name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
      ],
      "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": "[concat('store', uniquestring(resourceGroup().id))]",
              "location": "[resourceGroup().location]",
              "kind": "StorageV2",
              "sku": {
                "name": "[parameters('storageAccountType')]"
              }
            }
          ]
        }
      }
    }
  ]
}

Le dimensioni di una specifica di modello sono limitate a circa 2 MB. Se le dimensioni di una specifica di modello superano 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:

Get-AzTemplateSpec

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

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Distribuire la specifica di modello

Dopo aver creato la specifica di modello, gli utenti con il ruolo lettore Specifiche di modello possono distribuirla. 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 modello collegato in una distribuzione di modelli più ampia. 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é inserire un percorso o un URI per un modello, 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.

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

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

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

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $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

L’inserimento di parametri nella specifica di modello è uguale all’inserimento di parametri in un modello di ARM. Aggiungere i valori dei parametri inline oppure in un file di parametri.

Per inserire un parametro inline, usare:

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

Per creare un file di parametri locale, usare:

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

E ancora, inserire il file di parametri con:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./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.

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

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

Quando si crea o si modifica una specifica di modello con il parametro della versione definito, ma senza il parametro tag/tags:

  • Se la specifica di modello esiste e ha tag, ma la versione non esiste, la nuova versione eredita gli stessi tag della specifica di modello esistente.

Quando si crea o si modifica una specifica di modello con il parametro tag/tags e il parametro della versione definito:

  • Se non esistono né le specifiche di modello né la versione, i tag vengono aggiunti sia alla nuova specifica di modello che alla nuova versione.
  • Se la specifica di modello esiste, ma la versione non esiste, i tag vengono aggiunti solo alla nuova versione.
  • Se esistono sia la specifica di modello che la versione, i tag si applicano solo alla versione.

Quando si modifica un modello con il parametro tag/tags definito ma senza il parametro della versione definito, i tag vengono aggiunti solo alla specifica di modello.

Creare una specifica di modello con i modelli collegati

Se il modello principale per le specifiche di modello fa riferimento a modelli collegati, i comandi di PowerShell e dell'interfaccia della riga di comando possono trovare e creare automaticamente il pacchetto dei modelli collegati dall'unità locale. Non è necessario configurare manualmente gli account di archiviazione o i repository per ospitare le specifiche del modello. Tutto è indipendente nella risorsa specifica del modello.

L'esempio seguente è costituito da un modello principale con due modelli collegati. L'esempio è solo un estratto del modello. Si noti che usa una proprietà denominata relativePath per collegarsi agli altri modelli. È necessario usare apiVersion di 2020-06-01 o versione successiva per la risorsa distribuzioni.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/webapp.json"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/database.json"
        }
      }
    }
  ],
  "outputs": {}
}

Quando il comando di PowerShell o dell'interfaccia della riga di comando per creare la specifica di modello viene eseguito per l'esempio precedente, il comando trova tre file, ovvero il modello principale, il modello dell'app Web (webapp.json) e il modello di database (database.json) e li inserisce nella specifica del modello.

Per ulteriori informazioni, vedere Esercitazione: Creare una specifica di modello con modelli collegati.

Distribuire la specifica di modello come modello collegato

Dopo aver creato una specifica di modello, è facile riutilizzarla da un modello di ARM o da un'altra specifica di modello. È possibile collegarsi a una specifica di modello aggiungendo il suo ID risorsa al modello. La specifica del modello collegato viene distribuita automaticamente quando si distribuisce il modello principale. Questo comportamento consente di sviluppare specifiche di modello modulari e riutilizzarle in base alle esigenze.

Ad esempio, è possibile creare una specifica di modello che distribuisca le risorse di rete e un'altra specifica di modello che distribuisca le risorse di archiviazione. Nei modelli di ARM è possibile collegare queste due specifiche di modello ogni volta che è necessario configurare le risorse di rete o di archiviazione.

L'esempio seguente è simile all'esempio precedente, ma si usa la id proprietà per collegarsi a una specifica di modello anziché la relativePath proprietà per collegarsi a un modello locale. Usare 2020-06-01 per la versione API per la risorsa distribuzioni. Nell'esempio le specifiche del modello si trovano in un gruppo di risorse denominato templateSpecsRG.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "networkingDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "storageDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
        }
      }
    }
  ],
  "outputs": {}
}

Per ulteriori informazioni sul collegamento delle specifiche di modello, vedere Esercitazione: Distribuire una specifica di modello come modello collegato.

Passaggi successivi