Procedure consigliate per i modelli di Resource Manager

Questo articolo illustra come usare le procedure consigliate quando si costruisce il modello di Azure Resource Manager (modello di Resource Manager). Questi consigli consentono di evitare problemi comuni quando si usa un modello di Resource Manager per distribuire una soluzione.

Limiti del modello

Limitare le dimensioni del modello a 4 MB. Il limite di 4 MB si applica allo stato finale del modello dopo che è stato espanso con definizioni di risorse iterative e valori per variabili e parametri. Il file di parametri è limitato anche a 4 MB. È possibile che venga visualizzato un errore con un modello o un file di parametri inferiore a 4 MB, se la dimensione totale della richiesta è troppo grande. Per altre informazioni su come semplificare il modello per evitare una richiesta di grandi dimensioni, vedere Risolvere gli errori per le dimensioni del processo superate.

Esistono anche i limiti seguenti:

  • 256 parametri
  • 256 variabili
  • 800 risorse (incluso il conteggio copie)
  • 64 valori di output
  • 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 durante la distribuzione delle 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.

Resource group

Quando si distribuiscono le risorse in un gruppo di risorse, il gruppo di risorse archivia i metadati sulle 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.

  • Specificare una descrizione di ogni parametro nei metadati.

    "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 usa allowedValues troppo ampiamente, è possibile bloccare le distribuzioni valide non mantenendo 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 tipo secureObject. 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. Fornendo un parametro di posizione, gli utenti del modello possono specificare una posizione in cui hanno l'autorizzazione per distribuire le risorse.

    "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 il caso 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. Il modello è più semplice da leggere quando l'espressione complessa viene visualizzata solo nelle variabili.

  • Non è possibile usare la funzione di riferimento nella variables sezione del modello. La reference funzione deriva il relativo valore dallo stato di runtime della risorsa. ma le variabili vengono risolte durante l'analisi iniziale del modello. Costruire valori che richiedono la reference funzione direttamente nella resources sezione o outputs 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 proprietà su una versione dell'API apiVersion 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, vedere informazioni di riferimento sul 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 potrebbero essere introdotte nelle versioni successive.

Non usare un parametro per la versione dell'API. Le proprietà e i valori 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 versione api che non corrisponde alle proprietà nel modello, la distribuzione avrà esito negativo.

Non usare le variabili per la versione dell'API.

Dipendenze delle risorse

Quando si decide quali dipendenze impostare, usare le linee guida seguenti:

  • Usare la funzione e passare il nome della reference risorsa per impostare una dipendenza implicita tra le risorse che devono condividere una proprietà. Non aggiungere un elemento dependsOn 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 funzioni di riferimento e elenco.

  • 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:

  • Per consentire ad altri collaboratori di comprendere lo scopo della risorsa, specificare comments per ogni risorsa nel modello.

    "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. Usare la reference funzione per recuperare dinamicamente lo spazio dei nomi. 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 è condiviso con un'altra risorsa nel modello, non è necessario specificare lo spazio dei nomi del provider o quando apiVersion si fa riferimento alla risorsa. Nell'esempio seguente viene illustrata la sintassi semplificata.

    "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.

    "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 (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.

    Per altre informazioni sulla connessione alle macchine virtuali, vedere:

  • La domainNameLabel proprietà per gli indirizzi IP pubblici deve essere univoca. Il domainNameLabel valore deve avere una lunghezza compresa tra 3 e 63 caratteri e seguire le regole specificate da questa espressione regolare: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Poiché la uniqueString funzione genera una stringa lunga 13 caratteri, il dnsPrefixString parametro è limitato 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, utilizzare la commandToExecute proprietà nella protectedSettings proprietà .

    "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.

  • 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 kubernetesVersion proprietà. Se non viene specificato, per impostazione predefinita il cluster è la versione secondaria N-1 e la patch più recente. Quando si distribuisce il cluster usando un modello di Resource Manager, questo comportamento predefinito potrebbe non essere quello previsto. La ridistribuzione del modello può comportare l'aggiornamento imprevisto del cluster a una nuova versione di Kubernetes. È invece consigliabile specificare un numero di versione esplicito e quindi modificarlo manualmente quando si è pronti per aggiornare il cluster.

Usare il toolkit di test

Il toolkit di test del modello di Resource Manager è uno script che controlla se il modello usa le procedure consigliate. Quando 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 Resource Manager.

Passaggi successivi