Condividi tramite

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, usare 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 del 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 progetta la distribuzione, prendere in considerazione il ciclo di vita delle risorse. 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, con ogni istanza contenente i propri database e contenitori. Poiché i database e i contenitori non cambiano molto, creare una specifica di modello per includere un'istanza di Cosmos DB e i relativi database e contenitori sottostanti. Per creare più istanze di queste risorse, usare istruzioni condizionali nei modelli insieme ai cicli di copia.

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 nei processi di distribuzione esistenti, 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 i modelli sono attualmente disponibili in un repository GitHub o in un account di archiviazione, si verificano diversi problemi quando si tenta di condividere e 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, è possibile creare copie locali, che alla fine divergono dal modello originale. Le specifiche dei modelli semplificano la condivisione dei modelli.

Per seguire i requisiti e le indicazioni dell'organizzazione, gli amministratori devono verificare i modelli inclusi in una specifica di modello.

Autorizzazioni necessarie

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

Inoltre, sono necessarie le autorizzazioni per la distribuzione di un file Bicep. Per altre informazioni, 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 trovano e li comprimono. Per altre 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 una dimensione della specifica di modello supera il limite, si ottiene 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 della specifica di modello possono distribuirlo. Inoltre, sono necessarie anche le autorizzazioni per la distribuzione di un modello di ARM. Per altre informazioni, vedere Distribuire - Interfaccia della riga di comando o Distribuire - PowerShell.

È possibile distribuire specifiche di modello tramite il portale, PowerShell, l'interfaccia della riga di comando di Azure o come modello collegato 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é 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, in genere si esegue Get-AzTemplateSpec o az ts show si ottiene l'ID della specifica di modello da 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

Il passaggio di parametri alla specifica di modello è simile al passaggio di parametri a un modello di Resource Manager. 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 avere 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 version specificato, ma senza il parametro tag:

  • 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 e il parametro version specificato:

  • 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 specificando il parametro tag, ma senza specificare il parametro version, si aggiungono i tag 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 si esegue il comando di PowerShell o dell'interfaccia della riga di comando per creare la specifica di modello 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, è possibile riutilizzarla facilmente da un modello di Resource Manager o da un'altra specifica di modello. Per collegarsi a una specifica di modello, aggiungere il relativo ID risorsa al modello. Quando si distribuisce il modello principale, la specifica del modello collegato viene distribuita automaticamente. 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