Condividi tramite

Procedure consigliate per i modelli di Resource Manager

  • Articolo

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
  • 512 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 usa allowedValues 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 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. 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 funzione reference 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 funzione reference direttamente nella sezione resources 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, 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 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 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 Azure 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 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 valore domainNameLabel 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 funzione uniqueString genera una stringa lunga 13 caratteri, la lunghezza del parametro dnsPrefixString è 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 Azure Resource Manager. È 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 Azure Resource Manager è 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