Procedure consigliate per i modelli di Resource Manager
Questo articolo spiega come usare le procedure consigliate per la creazione del modello di Azure Resource Manager (modello di ARM). Queste indicazioni consentono di evitare i problemi comuni quando si usa un modello di ARM per distribuire una soluzione.
Limiti del modello
Limitare le dimensioni del modello a 4 MB e ogni definizione di risorsa a 1 MB. Questi limiti si applicano allo stato finale del modello dopo che è stato espanso con le definizioni delle risorse iterative e i valori di variabili e parametri. Anche il file di parametri è limitato a 4 MB. È possibile che venga visualizzato un errore con un modello o un file di parametri di dimensioni inferiori a 4 MB se le dimensioni totali della richiesta sono troppo grandi. Per altre informazioni su come semplificare il modello per evitare una richiesta di grandi dimensioni, vedere Risolvere gli errori per il superamento delle dimensioni del processo.
Esistono anche i limiti seguenti:
- 256 parametri
- 256 variabili
- 800 risorse (incluso il conteggio copie)
- 64 valori di output
- 10 posizioni univoche per sottoscrizione/tenant/ambito del gruppo di gestione
- 24.576 caratteri in un'espressione di modello
È possibile superare alcuni limiti del modello usando un modello annidato. Per altre informazioni, vedere Uso di modelli collegati e annidati nella distribuzione di risorse di Azure. Per ridurre il numero di parametri, variabili o output, è possibile combinare più valori in un oggetto. Per altre informazioni, vedere Oggetti come parametri.
Gruppo di risorse
Quando si distribuiscono le risorse in un gruppo di risorse, tale gruppo di risorse archivia i metadati relativi alle risorse. I metadati vengono archiviati nella posizione del gruppo di risorse.
Se l'area del gruppo di risorse è temporaneamente non disponibile, non è possibile aggiornare le risorse nel gruppo di risorse perché i metadati non sono disponibili. Le risorse in altre aree continueranno a funzionare come previsto, ma non è possibile aggiornarle. Per ridurre il rischio, collocare il gruppo di risorse e le risorse nella stessa area.
Parametri
Le informazioni di questa sezione possono essere utili quando si usano i parametri.
Raccomandazioni generali per i parametri
Ridurre al minimo l'uso di parametri. Usare invece i valori letterali o le variabili per le proprietà che non è necessario specificare durante la distribuzione.
Usare la notazione Camel per i nomi dei parametri.
Usare i parametri per impostazioni che variano in base all'ambiente, ad esempio SKU, dimensioni o capacità.
Usare i parametri per i nomi di risorse da specificare per facilitare l'identificazione.
Indicare una descrizione nei metadati per ogni parametro.
"parameters": { "storageAccountType": { "type": "string", "metadata": { "description": "The type of the new storage account created to store the VM disks." } } }
Definire i valori predefiniti per i parametri non riservati. Specificando un valore predefinito, è più semplice distribuire il modello e gli utenti del modello vedono un esempio di un valore appropriato. Qualsiasi valore predefinito per un parametro deve essere valido per tutti gli utenti nella configurazione della distribuzione predefinita.
"parameters": { "storageAccountType": { "type": "string", "defaultValue": "Standard_GRS", "metadata": { "description": "The type of the new storage account created to store the VM disks." } } }
Per specificare un parametro facoltativo, non usare una stringa vuota come valore predefinito. Usare invece un valore letterale o un'espressione del linguaggio per costruire un valore.
"storageAccountName": { "type": "string", "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]", "metadata": { "description": "Name of the storage account" } }
Usare
allowedValues
solo in casi limitati. Usarlo solo quando è necessario assicurarsi che alcuni valori non vengano inclusi nelle opzioni consentite. Se si usaallowedValues
troppo diffusamente, si potrebbero bloccare le distribuzioni valide non tenendo aggiornato l'elenco.Quando il nome di un parametro nel modello corrisponde a un parametro nel comando di distribuzione di PowerShell, Resource Manager risolve questo conflitto di denominazione aggiungendo il suffisso FromTemplate al parametro del modello. Se, ad esempio, si include un parametro denominato ResourceGroupName nel modello, si crea un conflitto con il parametro ResourceGroupName nel cmdlet New-AzResourceGroupDeployment. Durante la distribuzione verrà quindi richiesto di specificare un valore per ResourceGroupNameFromTemplate.
Raccomandazioni sulla sicurezza per i parametri
Usare sempre i parametri per i nomi utente e le password (o i segreti).
Usare
securestring
per tutte le password e i segreti. Se si passano dati sensibili in un oggetto JSON, usare il tiposecureObject
. Non è possibile leggere i parametri di modello di tipo stringa sicura o oggetto sicuro dopo la distribuzione delle risorse."parameters": { "secretValue": { "type": "securestring", "metadata": { "description": "The value of the secret to store in the vault." } } }
Non fornire valori predefiniti per nomi utente, password o valori che richiedono un tipo
secureString
.Non fornire valori predefiniti per le proprietà che aumentano la superficie di attacco dell'applicazione.
Raccomandazioni sulla posizione per i parametri
Usare un parametro per specificare la posizione delle risorse e impostare il valore predefinito su
resourceGroup().location
. Fornire un parametro location consente agli utenti del modello di specificare una posizione in cui sono autorizzati a eseguire la distribuzione."parameters": { "location": { "type": "string", "defaultValue": "[resourceGroup().location]", "metadata": { "description": "The location in which the resources should be deployed." } } }
Non specificare
allowedValues
per il parametro location. Le posizioni specificate potrebbero non essere disponibili in tutti i cloud.Usare il valore del parametro location per le risorse che potrebbero essere nella stessa posizione. Questo approccio permette di ridurre al minimo il numero di volte in cui gli utenti devono dare informazioni sulla posizione.
Per le risorse che non sono disponibili in tutte le posizioni, usare un parametro distinto oppure specificare un valore letterale per location.
Variabili
Le informazioni seguenti possono essere utili quando si usano le variabili:
Usare la notazione Camel per i nomi delle variabili.
Usare le variabili per i valori da usare più volte in un modello. Se un valore viene usato una sola volta, un valore hardcoded facilita la lettura del modello.
Usare le variabili per i valori costruiti da una disposizione complessa delle funzioni del modello. È più facile leggere il modello quando l'espressione complessa viene visualizzata solo nelle variabili.
Non è possibile usare la funzione reference nella sezione
variables
del modello. La funzionereference
deriva il proprio valore dallo stato di runtime della risorsa. ma le variabili vengono risolte durante l'analisi iniziale del modello. Costruire i valori che richiedono la funzionereference
direttamente nella sezioneresources
ooutputs
del modello.Includere le variabili per i nomi di risorse che devono essere univoci.
Usare un ciclo di copia nelle variabili per creare un modello ripetitivo di oggetti JSON.
Rimuovere le variabili non usate.
Versione dell'API
Impostare la apiVersion
proprietà su una versione dell'API hardcoded per il tipo di risorsa. Quando si crea un nuovo modello, è consigliabile usare la versione più recente dell'API per un tipo di risorsa. Per determinare i valori disponibili, vedi riferimento al modello.
Quando il modello funziona come previsto, è consigliabile continuare a usare la stessa versione dell'API. Usando la stessa versione dell'API, non è necessario preoccuparsi delle modifiche che causano un'interruzione che potrebbero essere introdotte nelle versioni successive.
Non usare un parametro per la versione dell'API. I valori e le proprietà delle risorse possono variare in base alla versione dell’API. Quando la versione dell'API è impostata su un parametro, IntelliSense negli editor di codice non può determinare lo schema corretto. Se si passa una funzione in una versione dell'API che non corrisponde alle proprietà nel modello, la distribuzione avrà esito negativo.
Non usare variabili per la versione dell'API.
Dipendenze delle risorse
Quando si decidono le dipendenze da impostare, usare le linee guida seguenti:
Usare la funzione
reference
passando il nome della risorsa per impostare una dipendenza implicita tra risorse che devono condividere una proprietà. Non aggiungere un elementodependsOn
esplicito quando è già stata definita una dipendenza implicita. Questo approccio riduce il rischio di creare dipendenze non necessarie. Per un esempio di impostazione di una dipendenza implicita, vedere Riferimento ed elenco delle funzioni.Impostare una risorsa figlio come dipendente dalla risorsa padre.
Le risorse con l'elemento condition impostato su
false
vengono automaticamente rimosse dall'ordine di dipendenza. Impostare le dipendenze come se la risorsa venisse sempre distribuita.Consentire la propagazione a catena delle dipendenze senza impostarle esplicitamente. Ad esempio, una macchina virtuale dipende da un'interfaccia di rete virtuale e tale interfaccia dipende da una rete virtuale e indirizzi IP pubblici. La macchina virtuale viene quindi distribuita dopo tutte e tre le risorse, ma non deve essere impostata esplicitamente come dipendente da tutte e tre. Questo approccio offre chiarezza nell'ordine delle dipendenze e semplifica la successiva modifica del modello.
Se un valore può essere determinato prima della distribuzione, provare a distribuire le risorse senza una dipendenza. Se un valore di configurazione richiede il nome di un'altra risorsa, ad esempio, potrebbe non essere necessaria una dipendenza. Questa indicazione non è sempre valida perché alcune risorse verificano l'esistenza dell'altra risorsa. Se viene visualizzato un errore, aggiungere una dipendenza.
Risorse
Le informazioni seguenti possono essere utili quando si usano le risorse:
Specificare
comments
per ogni risorsa nel modello per consentire ad altri collaboratori di comprendere lo scopo della risorsa."resources": [ { "name": "[variables('storageAccountName')]", "type": "Microsoft.Storage/storageAccounts", "apiVersion": "2019-06-01", "location": "[resourceGroup().location]", "comments": "This storage account is used to store the VM disks.", ... } ]
Se il modello di ARM viene archiviato in un file
.jsonc
, sono supportati i commenti che usano la sintassi//
, come illustrato di seguito."resources": [ { // This storage account is used to store the VM disks. "name": "[variables('storageAccountName')]", "type": "Microsoft.Storage/storageAccounts", "apiVersion": "2019-06-01", "location": "[resourceGroup().location]", ... } ]
Per altri dettagli sui commenti e i metadati, vedere Comprendere la struttura e la sintassi dei modelli di ARM.
Se si usa un endpoint pubblico nel modello, come ad esempio un endpoint pubblico di archiviazione BLOB di Azure, non impostare come hardcoded lo spazio dei nomi. Usare la funzione
reference
per recuperare lo spazio dei nomi in modo dinamico. Questo approccio consente di distribuire il modello in ambienti diversi dello spazio dei nomi pubblico senza dover modificare manualmente l'endpoint nel modello. Impostare la versione dell'API sulla stessa versione usata per l'account di archiviazione nel modello."diagnosticsProfile": { "bootDiagnostics": { "enabled": "true", "storageUri": "[reference(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').primaryEndpoints.blob]" } }
Se l'account di archiviazione viene distribuito nello stesso modello che si sta creando e il nome dell'account di archiviazione non viene condiviso con un'altra risorsa nel modello, non è necessario specificare lo spazio dei nomi del provider o
apiVersion
quando si fa riferimento alla risorsa. L'esempio seguente mostra la sintassi semplificata."diagnosticsProfile": { "bootDiagnostics": { "enabled": "true", "storageUri": "[reference(variables('storageAccountName')).primaryEndpoints.blob]" } }
È anche possibile fare riferimento a un account di archiviazione esistente in un gruppo di risorse diverso.
"diagnosticsProfile": { "bootDiagnostics": { "enabled": "true", "storageUri": "[reference(resourceId(parameters('existingResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('existingStorageAccountName')), '2019-06-01').primaryEndpoints.blob]" } }
Assegnare indirizzi IP pubblici a una macchina virtuale solo se richiesto per un'applicazione. Per connettersi a una macchina virtuale per scopi amministrativi, usare le regole NAT in ingresso, un gateway di rete virtuale o un jumpbox.
Per altre informazioni sulla connessione alle macchine virtuali, vedere:
La proprietà
domainNameLabel
per gli indirizzi IP pubblici deve essere univoca. Il valoredomainNameLabel
deve avere una lunghezza compresa tra 3 e 63 caratteri e seguire le regole specificate dall'espressione regolare seguente:^[a-z][a-z0-9-]{1,61}[a-z0-9]$
. Poiché la funzioneuniqueString
genera una stringa lunga 13 caratteri, la lunghezza del parametrodnsPrefixString
è limitata a 50 caratteri."parameters": { "dnsPrefixString": { "type": "string", "maxLength": 50, "metadata": { "description": "The DNS label for the public IP address. It must be lowercase. It should match the following regular expression, or it will raise an error: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$" } } }, "variables": { "dnsPrefix": "[concat(parameters('dnsPrefixString'),uniquestring(resourceGroup().id))]" }
Quando si aggiunge una password a un'estensione di script personalizzata, usare la proprietà
commandToExecute
nella proprietàprotectedSettings
."properties": { "publisher": "Microsoft.Azure.Extensions", "type": "CustomScript", "typeHandlerVersion": "2.0", "autoUpgradeMinorVersion": true, "settings": { "fileUris": [ "[concat(variables('template').assets, '/lamp-app/install_lamp.sh')]" ] }, "protectedSettings": { "commandToExecute": "[concat('sh install_lamp.sh ', parameters('mySqlPassword'))]" } }
Nota
Per verificare che i segreti passati come parametri a macchine virtuali ed estensioni siano crittografati, usare la proprietà
protectedSettings
delle estensioni pertinenti.Specificare valori espliciti per le proprietà con valori predefiniti che potrebbero cambiare nel tempo. Ad esempio, se si distribuisce un cluster del servizio Azure Kubernetes, è possibile specificare o omettere la proprietà
kubernetesVersion
. Se non la si specifica, il cluster viene impostato sulla versione secondaria N-1 e sulla la patch più recente predefiniti. Quando si distribuisce il cluster con un modello di ARM, il comportamento predefinito potrebbe non essere quello previsto. La ridistribuzione del modello può causare l'aggiornamento imprevisto del cluster a una nuova versione di Kubernetes. Prendere invece in considerazione la possibilità di specificare un numero di versione esplicito e quindi modificarlo manualmente quando si è pronti a eseguire l’aggiornamento del cluster.
Commenti
Oltre alla proprietà comments
, sono supportati i commenti che usano la sintassi //
. Per altri dettagli sui commenti e i metadati, vedere Comprendere la struttura e la sintassi dei modelli di ARM. È possibile scegliere di salvare i file JSON contenenti commenti //
usando l'estensione file .jsonc
per indicare che il file JSON contiene commenti. Il servizio di ARM accetterà anche commenti in qualsiasi file JSON, inclusi i file di parametri.
Strumenti ARM di Visual Studio Code
Usare i modelli di ARM è molto più semplice con gli strumenti di Azure Resource Manager (ARM) per Visual Studio Code. Questa estensione fornisce supporto per il linguaggio, frammenti di risorse e completamento automatico delle risorse che aiutano l’utente a creare e convalidare i modelli di Azure Resource Manager. Per altre informazioni e per installare l'estensione, vedere Strumenti di Azure Resource Manager (ARM).
Usare il toolkit di test
Il toolkit di test dei modelli di ARM uno script che controlla se il modello usa le procedure consigliate. Se il modello non è conforme alle procedure consigliate, restituisce un elenco di avvisi con le modifiche suggerite. Il toolkit di test consente di apprendere come implementare le procedure consigliate nel modello.
Dopo aver completato il modello, eseguire il toolkit di test per verificare se esistono modi per migliorarne l'implementazione. Per altre informazioni, vedere Usare il toolkit di test dei modelli di ARM.
Passaggi successivi
- Per informazioni sulla struttura del file modello, vedere Comprendere la struttura e la sintassi dei modelli di ARM.
- Per indicazioni su come compilare modelli funzionanti in tutti gli ambienti cloud di Azure, vedere Sviluppare modelli di ARM per la coerenza del cloud.
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per