Procedure consigliate per il modello ARMARM template best practices

Questo articolo illustra come usare le procedure consigliate per la creazione di un modello di Azure Resource Manager (modello ARM).This article shows you how to use recommended practices when constructing your Azure Resource Manager template (ARM template). Questi consigli consentono di evitare problemi comuni quando si usa un modello ARM per distribuire una soluzione.These recommendations help you avoid common problems when using an ARM template to deploy a solution.

Limiti del modelloTemplate limits

Limitare le dimensioni del modello a 4 MB e ogni file di parametri a 64 KB.Limit the size of your template to 4 MB, and each parameter file to 64 KB. Il limite di 4 MB si applica allo stato finale del modello dopo che è stato espanso con le definizioni di risorse iterative e i valori per variabili e parametri.The 4-MB limit applies to the final state of the template after it has been expanded with iterative resource definitions, and values for variables and parameters.

Esistono anche i limiti seguenti:You're also limited to:

  • 256 parametri256 parameters
  • 256 variabili256 variables
  • 800 risorse (incluso il conteggio copie)800 resources (including copy count)
  • 64 valori di output64 output values
  • 24.576 caratteri in un'espressione di modello24,576 characters in a template expression

È possibile superare alcuni limiti del modello usando un modello annidato.You can exceed some template limits by using a nested template. Per altre informazioni, vedere uso di modelli collegati e annidati durante la distribuzione di risorse di Azure.For more information, see Using linked and nested templates when deploying Azure resources. Per ridurre il numero di parametri, variabili o output, è possibile combinare più valori in un oggetto.To reduce the number of parameters, variables, or outputs, you can combine several values into an object. Per altre informazioni, vedere Oggetti come parametri.For more information, see Objects as parameters.

Resource groupResource group

Quando si distribuiscono le risorse in un gruppo di risorse, il gruppo di risorse archivia i metadati relativi alle risorse.When you deploy resources to a resource group, the resource group stores metadata about the resources. I metadati vengono archiviati nella posizione del gruppo di risorse.The metadata is stored in the location of the resource group.

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.If the resource group's region is temporarily unavailable, you can't update resources in the resource group because the metadata is unavailable. Le risorse in altre aree continueranno a funzionare come previsto, ma non è possibile aggiornarle.The resources in other regions will still function as expected, but you can't update them. Per ridurre il rischio, collocare il gruppo di risorse e le risorse nella stessa area.To minimize risk, locate your resource group and resources in the same region.

ParametriParameters

Le informazioni di questa sezione possono essere utili quando si usano i parametri.The information in this section can be helpful when you work with parameters.

Raccomandazioni generali per i parametriGeneral recommendations for parameters

  • Ridurre al minimo l'uso di parametri.Minimize your use of parameters. Usare invece i valori letterali o le variabili per le proprietà che non è necessario specificare durante la distribuzione.Instead, use variables or literal values for properties that don't need to be specified during deployment.

  • Usare la notazione Camel per i nomi dei parametri.Use camel case for parameter names.

  • Usare i parametri per impostazioni che variano in base all'ambiente, ad esempio SKU, dimensioni o capacità.Use parameters for settings that vary according to the environment, like SKU, size, or capacity.

  • Usare i parametri per i nomi di risorse da specificare per facilitare l'identificazione.Use parameters for resource names that you want to specify for easy identification.

  • Fornire una descrizione di ogni parametro nei metadati.Provide a description of every parameter in the metadata.

    "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.Define default values for parameters that aren't sensitive. Specificando un valore predefinito, è più semplice distribuire il modello e gli utenti del modello vedono un esempio di un valore appropriato.By specifying a default value, it's easier to deploy the template, and users of your template see an example of an appropriate value. Qualsiasi valore predefinito per un parametro deve essere valido per tutti gli utenti nella configurazione della distribuzione predefinita.Any default value for a parameter must be valid for all users in the default deployment configuration.

    "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.To specify an optional parameter, don't use an empty string as a default value. Usare invece un valore letterale o un'espressione del linguaggio per costruire un valore.Instead, use a literal value or a language expression to construct a value.

    "storageAccountName": {
       "type": "string",
       "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]",
       "metadata": {
         "description": "Name of the storage account"
       }
    }
    
  • Usare allowedValues solo in casi limitati.Use allowedValues sparingly. Usarlo solo quando è necessario assicurarsi che alcuni valori non vengano inclusi nelle opzioni consentite.Use it only when you must make sure some values aren't included in the permitted options. Se si usa allowedValues troppo ampio, è possibile bloccare le distribuzioni valide non mantenendo aggiornato l'elenco.If you use allowedValues too broadly, you might block valid deployments by not keeping your list up to date.

  • 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.When a parameter name in your template matches a parameter in the PowerShell deployment command, Resource Manager resolves this naming conflict by adding the postfix FromTemplate to the template parameter. Se, ad esempio, si include un parametro denominato ResourceGroupName nel modello, si crea un conflitto con il parametro ResourceGroupName nel cmdlet New-AzResourceGroupDeployment.For example, if you include a parameter named ResourceGroupName in your template, it conflicts with the ResourceGroupName parameter in the New-AzResourceGroupDeployment cmdlet. Durante la distribuzione verrà quindi richiesto di specificare un valore per ResourceGroupNameFromTemplate.During deployment, you're prompted to provide a value for ResourceGroupNameFromTemplate.

Raccomandazioni sulla sicurezza per i parametriSecurity recommendations for parameters

  • Usare sempre i parametri per i nomi utente e le password (o i segreti).Always use parameters for user names and passwords (or secrets).

  • Usare securestring per tutte le password e i segreti.Use securestring for all passwords and secrets. Se si passano dati sensibili in un oggetto JSON, usare il tipo secureObject.If you pass sensitive data in a JSON object, use the secureObject type. Non è possibile leggere i parametri di modello di tipo stringa sicura o oggetto sicuro dopo la distribuzione delle risorse.Template parameters with secure string or secure object types can't be read after resource deployment.

    "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.Don't provide default values for user names, passwords, or any value that requires a secureString type.

  • Non fornire valori predefiniti per le proprietà che aumentano la superficie di attacco dell'applicazione.Don't provide default values for properties that increase the attack surface area of the application.

Raccomandazioni sulla posizione per i parametriLocation recommendations for parameters

  • Usare un parametro per specificare la posizione delle risorse e impostare il valore predefinito su resourceGroup().location.Use a parameter to specify the location for resources, and set the default value to resourceGroup().location. Fornire un parametro location consente agli utenti del modello di specificare un percorso in cui sono autorizzati a distribuire le risorse.Providing a location parameter enables users of the template to specify a location where they have permission to deploy resources.

    "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.Don't specify allowedValues for the location parameter. Le posizioni specificate potrebbero non essere disponibili in tutti i cloud.The locations you specify might not be available in all clouds.

  • Usare il valore del parametro location per le risorse che potrebbero essere nella stessa posizione.Use the location parameter value for resources that are likely to be in the same location. Questo approccio permette di ridurre al minimo il numero di volte in cui gli utenti devono dare informazioni sulla posizione.This approach minimizes the number of times users are asked to provide location information.

  • Per le risorse che non sono disponibili in tutte le posizioni, usare un parametro distinto oppure specificare un valore letterale per location.For resources that aren't available in all locations, use a separate parameter or specify a literal location value.

variablesVariables

Le informazioni seguenti possono essere utili quando si usano le variabili:The following information can be helpful when you work with variables:

  • Usare il caso Camel per i nomi delle variabili.Use camel case for variable names.

  • Usare le variabili per i valori da usare più volte in un modello.Use variables for values that you need to use more than once in a template. Se un valore viene usato una sola volta, un valore hardcoded facilita la lettura del modello.If a value is used only once, a hard-coded value makes your template easier to read.

  • Usare le variabili per i valori costruiti da una disposizione complessa delle funzioni del modello.Use variables for values that you construct from a complex arrangement of template functions. Il modello è più facile da leggere quando l'espressione complessa viene visualizzata solo nelle variabili.Your template is easier to read when the complex expression only appears in variables.

  • Non è possibile usare la funzione Reference nella variables sezione del modello.You can't use the reference function in the variables section of the template. La reference funzione deriva il proprio valore dallo stato di runtime della risorsa.The reference function derives its value from the resource's runtime state. ma le variabili vengono risolte durante l'analisi iniziale del modello.However, variables are resolved during the initial parsing of the template. Costruire valori che richiedono la reference funzione direttamente nella resources sezione o outputs del modello.Construct values that need the reference function directly in the resources or outputs section of the template.

  • Includere le variabili per i nomi di risorse che devono essere univoci.Include variables for resource names that must be unique.

  • Usare un ciclo di copia nelle variabili per creare un modello ripetitivo di oggetti JSON.Use a copy loop in variables to create a repeated pattern of JSON objects.

  • Rimuovere le variabili non usate.Remove unused variables.

Versione dell'APIAPI version

Impostare la apiVersion proprietà su una versione API hardcoded per il tipo di risorsa.Set the apiVersion property to a hard-coded API version for the resource type. Quando si crea un nuovo modello, è consigliabile usare la versione più recente dell'API per un tipo di risorsa.When creating a new template, we recommend you use the latest API version for a resource type. Per determinare i valori disponibili, vedere riferimento ai modelli.To determine available values, see template reference.

Quando il modello funziona come previsto, è consigliabile continuare a usare la stessa versione API.When your template works as expected, we recommend you continue using the same API version. Con la stessa versione dell'API, non è necessario preoccuparsi delle modifiche di rilievo che potrebbero essere introdotte nelle versioni successive.By using the same API version, you don't have to worry about breaking changes that might be introduced in later versions.

Non usare un parametro per la versione dell'API.Don't use a parameter for the API version. Le proprietà e i valori delle risorse possono variare in base alla versione dell'API.Resource properties and values can vary by API version. Quando la versione dell'API è impostata su un parametro, IntelliSense negli editor di codice non può determinare lo schema corretto.IntelliSense in a code editor can't determine the correct schema when the API version is set to a parameter. Se si passa una versione dell'API che non corrisponde alle proprietà del modello, la distribuzione avrà esito negativo.If you pass in an API version that doesn't match the properties in your template, the deployment will fail.

Non usare le variabili per la versione dell'API.Don't use variables for the API version. In particolare, non usare la funzione Providers per ottenere dinamicamente le versioni dell'API durante la distribuzione.In particular, don't use the providers function to dynamically get API versions during deployment. La versione dell'API recuperata in modo dinamico potrebbe non corrispondere alle proprietà del modello.The dynamically retrieved API version might not match the properties in your template.

Dipendenze delle risorseResource dependencies

Quando si definiscono le dipendenze da impostare, attenersi alle linee guida seguenti:When deciding what dependencies to set, use the following guidelines:

  • Usare la reference funzione e passare il nome della risorsa per impostare una dipendenza implicita tra le risorse che devono condividere una proprietà.Use the reference function and pass in the resource name to set an implicit dependency between resources that need to share a property. Non aggiungere un elemento dependsOn esplicito quando è già stata definita una dipendenza implicita.Don't add an explicit dependsOn element when you've already defined an implicit dependency. Questo approccio riduce il rischio di creare dipendenze non necessarie.This approach reduces the risk of having unnecessary dependencies. Per un esempio di impostazione di una dipendenza implicita, vedere funzioni di riferimento ed elenco.For an example of setting an implicit dependency, see reference and list functions.

  • Impostare una risorsa figlio come dipendente dalla risorsa padre.Set a child resource as dependent on its parent resource.

  • Le risorse con l'elemento condition impostato su false vengono automaticamente rimosse dall'ordine di dipendenza.Resources with the condition element set to false are automatically removed from the dependency order. Impostare le dipendenze come se la risorsa venisse sempre distribuita.Set the dependencies as if the resource is always deployed.

  • Consentire la propagazione a catena delle dipendenze senza impostarle esplicitamente.Let dependencies cascade without setting them explicitly. Ad esempio, una macchina virtuale dipende da un'interfaccia di rete virtuale e tale interfaccia dipende da una rete virtuale e indirizzi IP pubblici.For example, your virtual machine depends on a virtual network interface, and the virtual network interface depends on a virtual network and public IP addresses. La macchina virtuale viene quindi distribuita dopo tutte e tre le risorse, ma non deve essere impostata esplicitamente come dipendente da tutte e tre.Therefore, the virtual machine is deployed after all three resources, but don't explicitly set the virtual machine as dependent on all three resources. Questo approccio offre chiarezza nell'ordine delle dipendenze e semplifica la successiva modifica del modello.This approach clarifies the dependency order and makes it easier to change the template later.

  • Se un valore può essere determinato prima della distribuzione, provare a distribuire le risorse senza una dipendenza.If a value can be determined before deployment, try deploying the resource without a dependency. Se un valore di configurazione richiede il nome di un'altra risorsa, ad esempio, potrebbe non essere necessaria una dipendenza.For example, if a configuration value needs the name of another resource, you might not need a dependency. Questa indicazione non è sempre valida perché alcune risorse verificano l'esistenza dell'altra risorsa.This guidance doesn't always work because some resources verify the existence of the other resource. Se viene visualizzato un errore, aggiungere una dipendenza.If you receive an error, add a dependency.

RisorseResources

Le informazioni seguenti possono essere utili quando si usano le risorse:The following information can be helpful when you work with resources:

  • Per consentire ad altri collaboratori di comprendere lo scopo della risorsa, specificare comments per ogni risorsa nel modello.To help other contributors understand the purpose of the resource, specify comments for each resource in the template.

    "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 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.If you use a public endpoint in your template (such as an Azure Blob storage public endpoint), don't hard-code the namespace. Utilizzare la reference funzione per recuperare in modo dinamico lo spazio dei nomi.Use the reference function to dynamically retrieve the namespace. Questo approccio consente di distribuire il modello in ambienti diversi dello spazio dei nomi pubblico senza dover modificare manualmente l'endpoint nel modello.You can use this approach to deploy the template to different public namespace environments without manually changing the endpoint in the template. Impostare la versione dell'API sulla stessa versione usata per l'account di archiviazione nel modello.Set the API version to the same version that you're using for the storage account in your template.

    "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 è condiviso con un'altra risorsa nel modello, non è necessario specificare lo spazio dei nomi del provider o apiVersion quando si fa riferimento alla risorsa.If the storage account is deployed in the same template that you're creating and the name of the storage account isn't shared with another resource in the template, you don't need to specify the provider namespace or the apiVersion when you reference the resource. Nell'esempio seguente viene illustrata la sintassi semplificata.The following example shows the simplified syntax.

    "diagnosticsProfile": {
      "bootDiagnostics": {
        "enabled": "true",
        "storageUri": "[reference(variables('storageAccountName')).primaryEndpoints.blob]"
      }
    }
    

    È anche possibile fare riferimento a un account di archiviazione esistente che si trova in un gruppo di risorse diverso.You also can reference an existing storage account that's in a different resource group.

    "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.Assign public IP addresses to a virtual machine only when an application requires it. Per connettersi a una macchina virtuale (VM) per il debug o per la gestione o a scopi amministrativi, usare le regole NAT in ingresso, un gateway di rete virtuale o un jumpbox.To connect to a virtual machine (VM) for debugging, or for management or administrative purposes, use inbound NAT rules, a virtual network gateway, or a jumpbox.

    Per altre informazioni sulla connessione alle macchine virtuali, vedere:For more information about connecting to virtual machines, see:

  • La domainNameLabel proprietà per gli indirizzi IP pubblici deve essere univoca.The domainNameLabel property for public IP addresses must be unique. Il domainNameLabel valore deve avere una lunghezza compresa tra 3 e 63 caratteri e seguire le regole specificate dall'espressione regolare: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$ .The domainNameLabel value must be between 3 and 63 characters long, and follow the rules specified by this regular expression: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Poiché la uniqueString funzione genera una stringa di 13 caratteri, il dnsPrefixString parametro è limitato a 50 caratteri.Because the uniqueString function generates a string that is 13 characters long, the dnsPrefixString parameter is limited to 50 characters.

    "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, utilizzare la commandToExecute proprietà nella protectedSettings Proprietà.When you add a password to a custom script extension, use the commandToExecute property in the protectedSettings property.

    "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 assicurarsi che i segreti vengano crittografati quando vengono passati come parametri alle macchine virtuali e alle estensioni, usare la protectedSettings proprietà delle estensioni pertinenti.To ensure that secrets are encrypted when they are passed as parameters to VMs and extensions, use the protectedSettings property of the relevant extensions.

USA test ToolkitUse test toolkit

ARM template test Toolkit è uno script che controlla se il modello usa le procedure consigliate.The ARM template test toolkit is a script that checks whether your template uses recommended practices. Quando il modello non è conforme alle procedure consigliate, restituisce un elenco di avvisi con le modifiche suggerite.When your template isn't compliant with recommended practices, it returns a list of warnings with suggested changes. Il Toolkit di test può essere utile per apprendere come implementare le procedure consigliate nel modello.The test toolkit can help you learn how to implement best practices in your template.

Una volta completato il modello, eseguire il Toolkit di test per verificare se è possibile migliorare l'implementazione.After you've completed your template, run the test toolkit to see if there are ways you can improve its implementation. Per altre informazioni, vedere use ARM template test Toolkit.For more information, see Use ARM template test toolkit.

Passaggi successiviNext steps