Procedure consigliate per i modelli di Resource Manager

  • Articolo

Questo articolo illustra come usare le procedure consigliate durante la costruzione del modello di Azure Resource Manager (modello arm). 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 e ogni definizione di risorsa a 1 MB. I limiti si applicano allo stato finale del modello dopo che è stato espanso con definizioni di risorse iterative e valori per 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 delle copie)
  • 64 valori di output
  • 10 percorsi univoci 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.

Resource group

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

  • 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 su larga scala, è possibile bloccare le distribuzioni valide senza mantenere 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. Se si specifica un parametro location, gli utenti del modello possono specificare un percorso in cui dispongono dell'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 la distinzione tra maiuscole e minuscole 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ù facile 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 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, 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 causano un'interruzione 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 dell'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 reference funzione e passare il nome della 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 ed elenco.

  • Impostare una risorsa figlio come dipendente dalla risorsa padre.

  • Le risorse con l'elemento condition impostato su false vengono rimosse automaticamente 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 aiutare altri collaboratori a 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 il modello di Resource Manager viene archiviato in un .jsonc file, i commenti che usano la // sintassi sono supportati, 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 altre informazioni sui commenti e sui metadati, vedere Comprendere la struttura e la sintassi dei modelli di Resource Manager.

  • 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 per recuperare dinamicamente lo reference 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 creato 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 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 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 essere compreso 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 funzione genera una stringa lunga 13 caratteri, il uniqueStringdnsPrefixString 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, usare 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 lo si specifica, il cluster è predefinito per 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 del cluster a una nuova versione di Kubernetes in modo imprevisto. Si consideri invece di specificare un numero di versione esplicito e quindi modificarlo manualmente quando si è pronti per aggiornare il cluster.

Commenti

Oltre alla comments proprietà, i commenti che usano la // sintassi sono supportati. Per altre informazioni sui commenti e sui metadati, vedere Comprendere la struttura e la sintassi dei modelli di Resource Manager. È possibile scegliere di salvare i file JSON contenenti // commenti usando l'estensione del file, per indicare che il .jsonc file JSON contiene commenti. Il servizio ARM accetterà anche commenti in qualsiasi file JSON, inclusi i file di parametri.

Strumenti arm di Visual Studio Code

L'uso dei modelli di Resource Manager è molto più semplice con gli strumenti di Azure Resource Manager (ARM) per Visual Studio Code. Questa estensione fornisce il supporto del linguaggio, i frammenti di risorsa e il completamento automatico delle risorse per creare e convalidare i modelli di Azure Resource Manager. Per altre informazioni e installare l'estensione, vedere Strumenti di Azure Resource Manager (ARM).

Usare il toolkit di test

Il toolkit di test dei modelli di Resource Manager è uno script che verifica se il modello usa le procedure consigliate. Quando il modello non è conforme alle procedure consigliate, restituisce un elenco di avvisi con 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 sono disponibili modi per migliorare l'implementazione. Per altre informazioni, vedere Usare il toolkit di test dei modelli di Arm.

Passaggi successivi