Convertire ed eseguire la migrazione delle risorse in un file Bicep

Completato

Quando si avvia il processo di migrazione a Bicep, è importante seguire un processo strutturato per assicurarsi che il file Bicep descriva correttamente le risorse di Azure. È necessario assicurarsi che il codice Bicep segua le procedure consigliate e che sia completamente testato e sicuro per l'uso per le distribuzioni successive. In questa unità verranno presentate le prime due fasi della migrazione a Bicep: la conversione e la migrazione.

L'obiettivo principale di queste due fasi è preparare un nuovo file Bicep prima di effettuarne il refactoring e testarlo in un secondo momento.

Fase di conversione

L’obiettivo della fase di conversione della migrazione delle risorse a Bicep consiste nell’acquisire una rappresentazione iniziale delle risorse di Azure. Il file Bicep creato in questa fase non è completo e non è pronto per l'uso. Tuttavia, il file offre un punto di partenza per la migrazione.

La fase di conversione è costituita da due possibili passaggi, completati in sequenza:

1. Acquisire una rappresentazione delle risorse di Azure.
2. Se necessario, convertire la rappresentazione JSON in Bicep usando il comando decompile.

Nel caso di un modello JSON esistente da convertire in Bicep, il primo passaggio è semplice perché il modello di origine è già disponibile. In questa unità si apprenderà come decompilarlo per Bicep.

Se si convertono risorse di Azure distribuite usando il portale di Azure o un altro strumento, è necessario acquisire le definizioni delle risorse. È possibile esportare le definizioni delle risorse e convertirle in Bicep oppure usare il comando Inserisci risorsa in Visual Studio Code per inserire una rappresentazione Bicep della risorsa di Azure.

Rappresentazione delle risorse in Azure

Azure Resource Manager è il servizio usato per distribuire e gestire le risorse in Azure. Tutte le risorse distribuite in Azure vengono monitorate da Resource Manager, indipendentemente dal metodo usato per distribuire la risorsa. È possibile usare il portale di Azure, l'interfaccia della riga di comando di Azure, Azure PowerShell, l'API REST di Resource Manager e gli SDK di Azure per interagire con Resource Manager.

Esistono due tipi di operazioni in Azure: operazioni del piano di controllo e operazioni del piano dati. Le operazioni del piano di controllo vengono usate per gestire le risorse nella sottoscrizione. Le operazioni del piano dati vengono usate per accedere alle funzionalità esposte da una risorsa. Ad esempio, si usa un'operazione del piano di controllo per creare una macchina virtuale, ma si usa un'operazione del piano dati per connettersi alla macchina virtuale usando Remote Desktop Protocol (RDP).

Esportare le risorse esistenti in un modello JSON

Indipendentemente dalla modalità di creazione delle risorse di Azure, le informazioni su ogni risorsa vengono rese disponibili in formato JSON da Resource Manager. Quando si richiede una copia della rappresentazione JSON di una risorsa, si esporta la risorsa. Il file JSON esportato può essere decompilato in Bicep.

Resource Manager offre diversi modi per esportare le risorse di Azure in un modello. È possibile usare il portale di Azure, l'interfaccia della riga di comando di Azure e i cmdlet di Azure PowerShell per esportare singole risorse, più risorse e interi gruppi di risorse.

Il processo di esportazione è un'operazione del piano di controllo, il che significa che viene esportata solo la configurazione delle risorse di Azure. Ad esempio, quando si esporta una macchina virtuale, i dati nel disco rigido della macchina virtuale non vengono esportati. Quando si esporta un account di archiviazione, i BLOB e altri contenuti dell'account di archiviazione non sono inclusi nel processo di esportazione.

Quando si esportano le risorse esistenti, è necessario prendere in considerazione alcuni aspetti:

• La definizione della risorsa esportata è uno snapshot dello stato corrente di tale risorsa. Include tutte le modifiche apportate alla risorsa dalla distribuzione iniziale.
• Il modello esportato potrebbe includere alcune proprietà della risorsa predefinite che in genere vengono omesse da una definizione Bicep. Ad esempio, il processo di esportazione potrebbe aggiungere proprietà di sola lettura impostate automaticamente da Azure. Non ha senso includere queste proprietà perché sono di sola lettura. Prendere in considerazione la rimozione di queste proprietà dalle definizioni di risorse quando si esegue la migrazione a Bicep, per non inserire codice superfluo che potrebbe causare confusione nei file Bicep.
• Il modello esportato probabilmente non includerà tutti i parametri necessari per rendere riutilizzabile il modello. Quando si esporta un modello, molte delle proprietà saranno hardcoded nel modello. Si vedrà come aggiungere parametri più avanti in questo modulo.
• Alcune risorse non possono essere esportate usando questo approccio ed è necessario definirle manualmente nel file Bicep. Si apprenderà come ricreare le risorse più avanti in questa unità.

Salvare le distribuzioni in un modello JSON

Se è già stata eseguita la distribuzione manuale di una risorsa dal portale di Azure, è possibile aver notato l'opzione Scaricare un modello per l'automazione nella scheda Rivedi e crea. Questa opzione salva un modello di ARM JSON in base ai nomi e alle proprietà impostati durante la creazione della risorsa nel portale.

Resource Manager tiene traccia anche delle distribuzioni delle risorse. Le operazioni di distribuzione includono le modifiche inviate dall'esperienza di creazione delle risorse del portale di Azure ed eventuali distribuzioni di modelli di ARM. Le modifiche alle risorse esistenti apportate usando il portale di Azure, i cmdlet di Azure PowerShell, l'interfaccia della riga di comando di Azure o altri strumenti in genere non creano distribuzioni.

Se le distribuzioni sono state create usando uno strumento compatibile, è possibile accedere al modello di distribuzione dalla cronologia di distribuzione del gruppo di risorse. È possibile usare il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell per salvare le distribuzioni.

Quando si salvano i modelli usando questo metodo, è necessario prendere in considerazione alcuni aspetti:

• Il modello salvato mostra lo stato delle risorse al momento della distribuzione. Non include eventuali modifiche apportate dopo la distribuzione.
• Se la distribuzione conteneva più risorse, non è possibile selezionare risorse specifiche da includere ed escludere. Questa operazione scarica la definizione di tutte le risorse che fanno parte della distribuzione iniziale. Tuttavia, quando si passa alla fase di migrazione del processo, è possibile ignorare manualmente le risorse non necessarie.
• Il modello include solo le proprietà delle risorse necessarie per la distribuzione.
• Il modello potrebbe includere parametri che è possibile usare per ridistribuire il modello in più ambienti. È tuttavia necessario verificare che questi parametri siano adatti alle specifiche esigenze.
• Il modello probabilmente non include proprietà superflue, ma è comunque necessario verificare che il modello includa tutti gli elementi previsti e rimuovere le proprietà che non dovrebbero essere presenti.

Nota

Comunque vengano esportate le risorse, ovvero con l'esportazione di risorse esistenti o il salvataggio delle distribuzioni, trattare il file esportato come punto di partenza e non usarlo direttamente. Usarle invece come punto di partenza per il modello finale.

Inserire risorse esistenti in Bicep

L'estensione Bicep per Visual Studio Code include il comando Inserisci risorsa, che acquisisce una rappresentazione di Bicep di una risorsa di Azure. Questo comando legge la definizione JSON della risorsa da Azure, rimuove le proprietà riconosciute come di sola lettura e decompila il JSON in Bicep. Come per la funzione di esportazione, il codice Bicep risultante può essere usato come punto di partenza per il file Bicep finale.

È possibile inserire una risorsa aprendo il riquadro comandi di Visual Studio Code. Usare CTRL+MAIUSC+P in Windows e Linux e ⌘+MAIUSC+P in macOS.

Decompilare il modello di ARM JSON di origine

Il secondo passaggio per la migrazione delle risorse di Azure a Bicep consiste nella conversione dei modelli di ARM JSON e delle risorse di Azure in modelli Bicep. Gli strumenti Bicep includono il comando decompile per convertire i modelli. È possibile richiamare il comando decompile dall'interfaccia della riga di comando di Azure o dall'interfaccia della riga di comando di Bicep.

Il processo di decompilazione non garantisce un mapping completo da JSON a Bicep. Potrebbe essere necessario rivedere il file Bicep generato per conformarsi alle procedure consigliate del modello prima di usare il file per distribuire le risorse. Considerarlo il punto di partenza per la migrazione. Più avanti in questo modulo si apprenderà come risolvere eventuali problemi riscontrati durante il processo di decompilazione.

Dopo aver decompilato il modello, la fase di conversione è completata. A questo punto, è disponibile un file Bicep valido da cui iniziare.

Fase di migrazione

L’obiettivo della fase di migrazione delle risorse a Bicep consiste nel creare la prima bozza del file Bicep distribuibile e assicurarsi che definisca tutte le risorse di Azure nell'ambito della migrazione.

La fase di migrazione è costituita da tre passaggi, completati in sequenza:

1. Creare un nuovo file Bicep vuoto.
2. Copiare ogni risorsa dal modello decompilato.
3. Identificare e ricreare le risorse mancanti.

Creare un nuovo file Bicep

È buona norma creare un nuovo file Bicep. Il file creato nella fase di conversione è un punto di riferimento da esaminare, ma non è consigliabile considerarlo finale o distribuirlo così com'è.

Copiare le risorse nel nuovo file Bicep

Copiare ogni risorsa singolarmente dal file Bicep convertito nel nuovo file Bicep. Questo processo consente di risolvere eventuali problemi in base alle risorse ed evitare confusione man mano che il modello diventa più grande.

Ricreare le risorse non supportate

Non tutti i tipi di risorse di Azure possono essere esportati tramite il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Ad esempio, le estensioni delle macchine virtuali come DependencyAgentWindows e MMAExtension (Microsoft Monitoring Agent) sono tipi di risorse che non è possibile esportare.

Quando si tenta di esportare una risorsa usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell e l'esportazione include un tipo di risorsa non supportato, viene generato un messaggio di errore dettagliato. Qualsiasi risorsa non esportata, ad esempio le estensioni macchina virtuale, dovrà essere ricreata nel nuovo file Bicep. È possibile scegliere diversi strumenti e approcci per ricreare le risorse, tra cui Azure Resource Explorer, la documentazione di riferimento sui modelli di ARM e modelli di avvio rapido di Azure.

Azure Resource Explorer

Azure Resource Explorer è uno strumento incorporato nel portale di Azure. Il portale non mostra determinati tipi di risorse, ma Resource Explorer offre una rappresentazione JSON delle risorse. Per accedere a Resource Explorer, cercarlo nella casella di ricerca:

Il riquadro dei risultati mostra un elenco dei provider di risorse registrati per la sottoscrizione e dei dettagli relativi a tutte le risorse, ai gruppi di risorse e alle sottoscrizioni che si è autorizzati a visualizzare. Per visualizzare una rappresentazione JSON di una risorsa, selezionare la gerarchia sul lato sinistro del riquadro:

Selezionando una risorsa, è possibile visualizzare la rappresentazione JSON, come in questo esempio:

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

È possibile usare questa rappresentazione JSON per definire manualmente una risorsa Bicep:

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

Nota

La rappresentazione JSON include una proprietà denominata provisioningState. La proprietà provisioningState è di sola lettura e viene impostata automaticamente da Azure, quindi non è inclusa nella definizione di risorsa Bicep.

Suggerimento

L'estensione Bicep per Visual Studio Code consente di definire le risorse di Azure in Bicep. Ad esempio la rappresentazione Bicep della risorsa include una versione API, diversamente dalla versione JSON esportata. In Visual Studio Code quando si inizia a immettere il tipo di risorsa, viene suggerita automaticamente una versione dell'API.

Informazioni di riferimento sui modelli di Azure Resource Manager

La documentazione di riferimento per il modello di ARM è una fonte di informazioni sulla struttura del modello di ARM, sui tipi di risorse, le versioni delle API e le definizioni di proprietà per le risorse di Azure. La documentazione contiene esempi sia nei formati Bicep che JSON.

È possibile scegliere provider di risorse e tipi di risorse specifici, ad esempio Microsoft.Web/serverfarms, e le relative versioni delle API. È possibile verificare quali proprietà delle risorse sono obbligatorie e quali sono facoltative. È anche possibile visualizzare le descrizioni delle proprietà che consentono di comprendere le operazioni eseguite dalle proprietà.

Modelli di avvio rapido di Azure

Il repository Modelli di avvio rapido di Azure è una raccolta di modelli forniti dalla community. Questo repository di modelli che supporta la ricerca fornisce esempi di molte risorse e soluzioni di Azure. In alcuni modelli di avvio rapido sono disponibili sia un modello di ARM JSON che un modello di ARM Bicep. È possibile usare questi modelli come punto di riferimento per creare e verificare i modelli per la distribuzione.

Si supponga, ad esempio, di voler trovare un modello che crea un piano di servizio app e un'app. Ogni modello di avvio rapido offre la possibilità di distribuire il modello direttamente in Azure o di visualizzarlo in GitHub.

Tenere presente che i modelli di Avvio rapido di Azure sono contributi della community. Alcuni esempi possono essere non aggiornati, perché vengono aggiunte regolarmente funzionalità ai servizi di Azure. Gli esempi possono includere anche risorse e proprietà che non sono necessarie per l'uso del modello. Tuttavia, il repository dei modelli di avvio rapido è una risorsa utile per comprendere come distribuire le risorse usando i modelli di Resource Manager.