Creare un modello JSON di Modello Bicep o ARM di Image Builder di Azure

  • Articolo

Si applica a: ✔️ Set di scalabilità flessibili di macchine virtuali ✔️ Windows per macchine virtuali ✔️ Linux

Image Builder di Azure usa un file Bicep o un file di modello JSON del modello ARM per passare informazioni al servizio Image Builder. Questo articolo illustra le sezioni dei file, in modo da poter creare i propri file. Per le versioni più recenti dell'API, vedere informazioni di riferimento sul modello. Per vedere gli esempi di file con estensione JSON completi, fare riferimento al GitHub per Image Builder di Azure.

Il formato di base è:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "apiVersion": "2022-02-14",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "customize": [],
    "errorHandling":[],
    "distribute": [],
    "optimize": [],
    "source": {},
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "validate": {},
    "vmProfile": {
      "vmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>",
        "proxyVmSize": "<vmSize>"
      },
      "userAssignedIdentities": [
              "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName1>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName2>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName3>",
        ...
      ]
    }
  }
}

type e apiVersion

type è il tipo di risorsa che deve essere Microsoft.VirtualMachineImages/imageTemplates. cambierà apiVersion nel tempo man mano che l'API cambia. Vedere Novità di Image Builder di macchine virtuali di Azure per tutte le principali modifiche api e aggiornamenti delle funzionalità per il servizio Image Builder di macchine virtuali di Azure.

"type": "Microsoft.VirtualMachineImages/imageTemplates",
"apiVersion": "2022-02-14",

Ufficio

La località è l'area in cui viene creata l'immagine personalizzata. Sono supportate le aree seguenti:

  • Stati Uniti orientali
  • Stati Uniti orientali 2
  • Stati Uniti centro-occidentali
  • Stati Uniti occidentali
  • West US 2
  • Stati Uniti occidentali 3
  • Stati Uniti centro-meridionali
  • Europa settentrionale
  • Europa occidentale
  • Asia sud-orientale
  • Australia sud-orientale
  • Australia orientale
  • Regno Unito meridionale
  • Regno Unito occidentale
  • Brasile meridionale
  • Canada centrale
  • India centrale
  • Stati Uniti centrali
  • Francia centrale
  • Germania centro-occidentale
  • Giappone orientale
  • Stati Uniti centro-settentrionali
  • Norvegia orientale
  • Svizzera settentrionale
  • India occidentale Jio
  • Emirati Arabi Uniti settentrionali
  • Asia orientale
  • Corea centrale
  • Sudafrica settentrionale
  • Qatar centrale
  • USGov Arizona (anteprima pubblica)
  • USGov Virginia (anteprima pubblica)
  • Cina settentrionale 3 (anteprima pubblica)
  • Svezia centrale
  • Polonia Centrale

Importante

Registrare la funzionalità Microsoft.VirtualMachineImages/FairfaxPublicPreview per accedere all'anteprima pubblica di Azure Image Builder nelle aree Azure per enti pubblici (USGov Arizona e USGov Virginia).

Importante

Registrare la funzionalità Microsoft.VirtualMachineImages/MooncakePublicPreview per accedere all'anteprima pubblica di Azure Image Builder nell'area Cina settentrionale 3.

Per accedere all'anteprima pubblica di Image Builder di macchine virtuali di Azure nelle aree Azure per enti pubblici (USGov Arizona e USGov Virginia), è necessario registrare la funzionalità Microsoft.VirtualMachineImages/FairfaxPublicPreview. A tale scopo, eseguire il comando seguente in PowerShell o nell'interfaccia della riga di comando di Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

Per accedere all'anteprima pubblica di Image Builder di macchine virtuali di Azure nell'area Cina settentrionale 3, è necessario registrare la funzionalità Microsoft.VirtualMachineImages/MooncakePublicPreview . A tale scopo, eseguire il comando seguente in PowerShell o nell'interfaccia della riga di comando di Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Residenza dei dati

Il servizio Image Builder di macchine virtuali di Azure non archivia o elabora i dati dei clienti all'esterno di aree con requisiti rigorosi di residenza dei dati in un'area singola quando un cliente richiede una compilazione in tale area. Se un'interruzione del servizio per le aree con requisiti di residenza dei dati, è necessario creare file/modelli Bicep in un'area e un'area geografica diverse.

Ridondanza della zona

La distribuzione supporta la ridondanza della zona, i dischi rigidi virtuali vengono distribuiti a un account di Archiviazione archiviazione con ridondanza della zona (ZRS) per impostazione predefinita e la versione della raccolta di calcolo di Azure (in precedenza nota come Raccolta immagini condivise) supporterà un tipo di archiviazione con ridondanza della zona, se specificato.

Tag

I tag sono coppie chiave/valore che è possibile specificare per l'immagine generata.

Identità

Esistono due modi per aggiungere identità assegnate dall'utente descritte di seguito.

Identità assegnata dall'utente per la risorsa modello di immagine di Image Builder di Azure

Obbligatorio: affinché Image Builder disponga delle autorizzazioni per leggere/scrivere immagini e leggere gli script da Archiviazione di Azure, è necessario creare un'identità assegnata dall'utente di Azure con autorizzazioni per le singole risorse. Per informazioni dettagliate sul funzionamento delle autorizzazioni di Image Builder e sui passaggi pertinenti, vedere Creare un'immagine e usare un'identità gestita assegnata dall'utente per accedere ai file in un account di archiviazione di Azure.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<imgBuilderId>": {}
    }
}

Identità assegnata dall'utente del servizio Image Builder:

  • Supporta solo una singola identità.
  • Non supporta nomi di dominio personalizzati.

Per altre informazioni, vedere Cosa sono le identità gestite per le risorse di Azure?. Per altre informazioni sulla distribuzione di questa funzionalità, vedere Configurare le identità gestite per le risorse di Azure in una macchina virtuale di Azure tramite l'interfaccia della riga di comando di Azure.

Identità assegnata dall'utente per la macchina virtuale di compilazione di Image Builder

Questa proprietà è disponibile solo nelle versioni 2021-10-01 dell'API o versioni successive.

Facoltativo: la macchina virtuale di compilazione di Image Builder creata dal servizio Image Builder nella sottoscrizione viene usata per compilare e personalizzare l'immagine. Affinché la macchina virtuale di compilazione di Image Builder disponga delle autorizzazioni per l'autenticazione con altri servizi come Azure Key Vault nella sottoscrizione, è necessario creare una o più identità assegnate dall'utente di Azure con autorizzazioni per le singole risorse. Image Builder di Azure può quindi associare queste identità assegnate dall'utente alla macchina virtuale di compilazione. Gli script di personalizzazione in esecuzione all'interno della macchina virtuale di compilazione possono quindi recuperare i token per queste identità e interagire con altre risorse di Azure in base alle esigenze. Tenere presente che l'identità assegnata dall'utente per Image Builder di Azure deve avere l'assegnazione di ruolo "Operatore identità gestita" in tutte le identità assegnate dall'utente affinché Image Builder sia in grado di associarle alla macchina virtuale di compilazione.

Nota

Tenere presente che è possibile specificare più identità per la macchina virtuale di compilazione di Image Builder, inclusa l'identità creata per la risorsa modello di immagine. Per impostazione predefinita, l'identità creata per la risorsa modello di immagine non verrà aggiunta automaticamente alla macchina virtuale di compilazione.

"properties": {
  "vmProfile": {
    "userAssignedIdentities": [
      "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
    ]
  }
}

Image Builder Compila identità assegnata dall'utente della macchina virtuale:

  • Supporta un elenco di una o più identità gestite assegnate dall'utente da configurare nella macchina virtuale.
  • Supporta scenari tra sottoscrizioni (identità creata in una sottoscrizione mentre il modello di immagine viene creato in un'altra sottoscrizione nello stesso tenant).
  • Non supporta scenari tra tenant (identità creata in un tenant mentre il modello di immagine viene creato in un altro tenant).

Per altre informazioni, vedere:

Proprietà: buildTimeoutInMinutes

Durata massima di attesa durante la compilazione del modello di immagine (include tutte le personalizzazioni, le convalide e le distribuzioni).

Se non si specifica la proprietà o si imposta il valore su 0, viene usato il valore predefinito, ovvero 240 minuti o quattro ore. Il valore minimo è 6 minuti e il valore massimo è 960 minuti o 16 ore. Quando viene raggiunto il valore di timeout (indipendentemente dal fatto che la compilazione dell'immagine sia stata completata), viene visualizzato un errore simile al seguente:

[ERROR] Failed while waiting for packerizer: Timeout waiting for microservice to
[ERROR] complete: 'context deadline exceeded'

Per Windows, non è consigliabile impostare buildTimeoutInMinutes al di sotto di 60 minuti. Se si rileva che si raggiunge il timeout, esaminare i log per verificare se il passaggio di personalizzazione è in attesa di qualcosa come l'input dell'utente. Se è necessario più tempo per il completamento delle personalizzazioni, aumentare il buildTimeoutInMinutes valore. Tuttavia, non impostarlo troppo alto perché potrebbe essere necessario attendere che si verifichi un timeout prima di visualizzare un errore.

Proprietà: customize

Image Builder supporta più "personalizzatori", che sono funzioni usate per personalizzare l'immagine, ad esempio l'esecuzione di script o il riavvio dei server.

Quando si usa customize:

  • È possibile usare più strumenti di personalizzazione.
  • Le funzioni di personalizzazione vengono eseguite nell'ordine specificato nel modello.
  • Se una funzione di personalizzazione ha esito negativo, l'intero componente di personalizzazione avrà esito negativo e segnalerà un errore.
  • Testare accuratamente gli script prima di usarli in un modello. Il debug degli script da solo è più semplice.
  • Non inserire dati sensibili negli script. I comandi inline possono essere visualizzati nella definizione del modello di immagine. Se sono presenti informazioni riservate (incluse password, token di firma di accesso condiviso, token di autenticazione e così via), devono essere spostate in script in Archiviazione di Azure, in cui l'accesso richiede l'autenticazione.
  • I percorsi degli script devono essere accessibili pubblicamente, a meno che non si usi l'identità del servizio gestito.

La customize sezione è una matrice. I tipi di personalizzatore supportati sono File, PowerShell, Shell, WindowsRestart e WindowsUpdate.

"customize": [
  {
    "type": "File",
    "destination": "string",
    "sha256Checksum": "string",
    "sourceUri": "string"
  },
  {
    "type": "PowerShell",
    "inline": [ "string" ],
    "runAsSystem": "bool",
    "runElevated": "bool",
    "scriptUri": "string",
    "sha256Checksum": "string",
    "validExitCodes": [ "int" ]
  },
  {
    "type": "Shell",
    "inline": [ "string" ],
    "scriptUri": "string",
    "sha256Checksum": "string"
  },
  {
    "type": "WindowsRestart",
    "restartCheckCommand": "string",
    "restartCommand": "string",
    "restartTimeout": "string"
  },
  {
    "type": "WindowsUpdate",
    "filters": [ "string" ],
    "searchCriteria": "string",
    "updateLimit": "int"
  }
]

Funzione di personalizzazione shell

L'utilità di personalizzazione supporta l'esecuzione Shell di script della shell in Linux. Gli script della shell devono essere accessibili pubblicamente oppure è necessario aver configurato un'identità del servizio gestito per Image Builder per accedervi.

"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<link to script>",
    "sha256Checksum": "<sha256 checksum>"
  }
],
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "inline": "<commands to run>"
  }
]

Proprietà customize:

  • type : shell.

  • name : nome per tenere traccia della personalizzazione.

  • scriptUri: URI per il percorso del file.

  • inline - matrice dei comandi della shell, separati da virgole.

  • sha256Checksum: valore di checksum sha256 del file, si genera questo valore in locale e quindi Image Builder eseguirà il checksum e la convalida.

    Per generare sha256Checksum, usando un terminale in Mac o Linux eseguire: sha256sum <fileName>

Nota

I comandi inline vengono archiviati come parte della definizione del modello di immagine, che è possibile visualizzare quando si esegue il dump della definizione dell'immagine. Se sono presenti comandi o valori sensibili (incluse password, token di firma di accesso condiviso, token di autenticazione e così via), è consigliabile spostarli in script e usare un'identità utente per eseguire l'autenticazione per Archiviazione di Azure.

Privilegi utente con privilegi avanzati

Anteporre i comandi con sudo per eseguirli con privilegi utente con privilegi avanzati. È possibile aggiungere i comandi negli script o usarli inline, ad esempio:

"type": "Shell",
"name": "setupBuildPath",
"inline": [
    "sudo mkdir /buildArtifacts",
    "sudo cp /tmp/index.html /buildArtifacts/index.html"
]

Esempio di script che usa sudo a cui è possibile fare riferimento usando scriptUri:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

echo "Telemetry: running sudo 'as-is' in a script"
sudo touch /myfiles/somethingElevated.txt

Funzione di personalizzazione di riavvio di Windows

Il WindowsRestart personalizzatore consente di riavviare una macchina virtuale Windows e attendere che la macchina virtuale torni online, questo personalizzatore consente di installare il software che richiede un riavvio.

"customize": [
  {
    "type": "WindowsRestart",
    "restartCommand": "shutdown /r /f /t 0",
    "restartCheckCommand": "echo Azure-Image-Builder-Restarted-the-VM  > c:\\buildArtifacts\\azureImageBuilderRestart.txt",
    "restartTimeout": "5m"
  }
]

Proprietà customize:

  • Tipo: WindowsRestart.
  • restartCommand - comando per eseguire il riavvio (facoltativo). Il valore predefinito è 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand - comando per verificare che il riavvio sia stato completato (facoltativo).
  • restartTimeout: timeout del riavvio specificato come stringa di grandezza e unità. Ad esempio, 5m (5 minuti) o 2h (2 ore). Il valore predefinito è : 5m.

Nota

Non è disponibile alcun personalizzatore di riavvio di Linux.

Funzione di personalizzazione PowerShell

Lo strumento di personalizzazione supporta l'esecuzione di script di PowerShell e il comando inline in Windows, gli script devono essere accessibili pubblicamente per consentire all'IB di accedervi.The PowerShell customizer supports running PowerShell scripts and inline command on Windows, the scripts must be accessible pubblicamente for the IB to access them.

"customize": [
  {
    "type": "PowerShell",
    "name":   "<name>",
    "scriptUri": "<path to script>",
    "runElevated": <true false>,
    "runAsSystem": <true false>,
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "PowerShell",
    "name": "<name>",
    "inline": "<PowerShell syntax to run>",
    "validExitCodes": [<exit code>],
    "runElevated": <true or false>,
    "runAsSystem": <true or false>
  }
]

Proprietà customize:

  • type - PowerShell.

  • scriptUri - URI del percorso del file di script di PowerShell.

  • inline - comandi inline da eseguire, separati da virgole.

  • validExitCodes: codici facoltativi validi che possono essere restituiti dal comando script/inline. La proprietà evita l'errore segnalato del comando script/inline.

  • runElevated - valore facoltativo, booleano, supporto per l'esecuzione di comandi e script con autorizzazioni elevate.

  • runAsSystem : facoltativo, booleano, determina se lo script di PowerShell deve essere eseguito come utente di sistema.

  • sha256Checksum: generare il checksum SHA256 del file in locale, aggiornare il valore del checksum in lettere minuscole e Image Builder convaliderà il checksum durante la distribuzione del modello di immagine.

    Per generare sha256Checksum, usare il cmdlet Get-FileHash in PowerShell.

Funzione di personalizzazione File

Lo File strumento di personalizzazione consente a Image Builder di scaricare un file da un repository GitHub o da archiviazione di Azure. L'utilità di personalizzazione supporta sia Linux che Windows. Se si dispone di una pipeline di compilazione di immagini che si basa sugli artefatti di compilazione, è possibile impostare il personalizzatore di file da scaricare dalla condivisione di compilazione e spostare gli artefatti nell'immagine.

"customize": [
  {
    "type": "File",
    "name": "<name>",
    "sourceUri": "<source location>",
    "destination": "<destination>",
    "sha256Checksum": "<sha256 checksum>"
  }
]

Proprietà della funzione di personalizzazione File:

  • sourceUri : un endpoint di archiviazione accessibile, questo endpoint può essere GitHub o Archiviazione di Azure. È possibile scaricare un solo file, non tutta la directory. Se è necessario scaricare una directory, usare un file compresso, quindi decomprimerlo usando la funzione di personalizzazione shell o PowerShell.

    Nota

    Se sourceUri è un account Archiviazione di Azure, indipendentemente dal fatto che il BLOB sia contrassegnato come pubblico, è necessario concedere all'identità utente gestita le autorizzazioni per l'accesso in lettura nel BLOB. Vedere questo esempio per impostare le autorizzazioni di archiviazione.

  • destination : percorso di destinazione completo e nome file. Tutti i percorsi e le sottodirectory a cui si fa riferimento devono esistere, usare gli strumenti di personalizzazione shell o PowerShell per configurare questi percorsi in anticipo. Per creare il percorso, è possibile usare le funzioni di personalizzazione dello script.

Questo personalizzatore è supportato dalle directory di Windows e dai percorsi Linux, ma esistono alcune differenze:

  • Linux: l'unico percorso che image builder può scrivere in è /tmp.
  • Windows: nessuna restrizione del percorso, ma deve essere esistente.

Se si verifica un errore durante il tentativo di scaricare il file o inserirlo in una directory specificata, il passaggio di personalizzazione ha esito negativo e questo errore si troverà nel customization.log.

Nota

Il personalizzatore di file è adatto solo per i download di file di piccole dimensioni, < 20 MB. Per i download di file di dimensioni maggiori, usare uno script o un comando inline, quindi usare il codice per scaricare file, ad esempio, Linux wget o curl, Windows, Invoke-WebRequest. Per i file presenti nell'archiviazione di Azure, assicurarsi di assegnare un'identità con le autorizzazioni per visualizzare il file alla macchina virtuale di compilazione seguendo la documentazione qui: Identità assegnata dall'utente per la macchina virtuale di compilazione di Image Builder. Qualsiasi file non archiviato in Azure deve essere accessibile pubblicamente affinché Image Builder possa scaricarlo.

  • sha256Checksum: generare il checksum SHA256 del file in locale, aggiornare il valore del checksum in lettere minuscole e Image Builder convaliderà il checksum durante la distribuzione del modello di immagine.

    Per generare sha256Checksum, usare il cmdlet Get-FileHash in PowerShell.

Personalizzatore di Windows Update

Lo WindowsUpdate strumento di personalizzazione è basato sul provisioner di Windows Update della community per Packer, che è un progetto open source gestito dalla community di Packer. Microsoft testa e convalida il provisioner con il servizio Image Builder e supporterà l'analisi dei problemi e lavorerà per risolvere i problemi, ma il progetto open source non è ufficialmente supportato da Microsoft. Per informazioni dettagliate su e assistenza con il provisioner di Windows Update, vedere il repository del progetto.

"customize": [
  {
    "type": "WindowsUpdate",
    "searchCriteria": "IsInstalled=0",
    "filters": [
      "exclude:$_.Title -like '*Preview*'",
      "include:$true"
    ],
    "updateLimit": 20
  }
]

Proprietà del personalizzatore:

  • type : WindowsUpdate.
  • searchCriteria : facoltativo, definisce il tipo di aggiornamenti installato (ad esempio Consigliato o Importante), BrowseOnly=0 e IsInstalled=0 (scelta consigliata) è l'impostazione predefinita.
  • filters - facoltativo, consente di specificare un filtro per includere o escludere gli aggiornamenti.
  • updateLimit - facoltativo, definisce il numero di aggiornamenti che è possibile installare, valore predefinito 1000.

Nota

Lo strumento di personalizzazione di Windows Update può non riuscire se sono presenti riavvii di Windows in sospeso o le installazioni di applicazioni ancora in esecuzione, in genere è possibile che venga visualizzato questo errore nella customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. È consigliabile prendere in considerazione l'aggiunta in un riavvio di Windows e/o consentire alle applicazioni un tempo sufficiente per completare le installazioni usando comandi di sospensione o attesa nei comandi o negli script inline prima di eseguire Windows Update.

Generalizza

Per impostazione predefinita, Image Builder di Azure eseguirà deprovision anche il codice alla fine di ogni fase di personalizzazione dell'immagine per generalizzare l'immagine. La generalizzazione è un processo in cui l'immagine è configurata in modo da poter essere riutilizzata per creare più macchine virtuali. Per le macchine virtuali Windows, Image Builder di Azure usa Sysprep. Per Linux, Image Builder di Azure esegue waagent -deprovision.

I comandi di Image Builder che gli utenti di generalizzare potrebbero non essere adatti per ogni situazione, quindi Image Builder di Azure consente di personalizzare questo comando, se necessario.

Se si esegue la migrazione della personalizzazione esistente e si usano comandi Sysprep/waagent diversi, è possibile usare i comandi generici di Image Builder e, se la creazione della macchina virtuale ha esito negativo, usare i propri comandi Sysprep o waagent.

Se Azure Image Builder crea correttamente un'immagine personalizzata di Windows e si crea una macchina virtuale da essa, si noterà che la creazione della macchina virtuale ha esito negativo o non viene completata correttamente, è necessario esaminare la documentazione di Sysprep di Windows Server o generare una richiesta di supporto con il team di supporto clienti di Sysprep di Windows Server, che può risolvere i problemi e consigliare l'utilizzo corretto di Sysprep.

Comando di Sysprep predefinito

Write-Output '>>> Waiting for GA Service (RdAgent) to start ...'
while ((Get-Service RdAgent).Status -ne 'Running') { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureTelemetryService) to start ...'
while ((Get-Service WindowsAzureTelemetryService) -and ((Get-Service WindowsAzureTelemetryService).Status -ne 'Running')) { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureGuestAgent) to start ...'
while ((Get-Service WindowsAzureGuestAgent).Status -ne 'Running') { Start-Sleep -s 5 }
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Write-Output '>>> Removing Sysprep\unattend.xml ...'
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
if (Test-Path $Env:SystemRoot\Panther\unattend.xml) {
  Write-Output '>>> Removing Panther\unattend.xml ...'
  Remove-Item $Env:SystemRoot\Panther\unattend.xml -Force
}
Write-Output '>>> Sysprepping VM ...'
& $Env:SystemRoot\System32\Sysprep\Sysprep.exe /oobe /generalize /quiet /quit
while($true) {
  $imageState = (Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\State).ImageState
  Write-Output $imageState
  if ($imageState -eq 'IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE') { break }
  Start-Sleep -s 5
}
Write-Output '>>> Sysprep complete ...'

Comando di deprovisioning predefinito di Linux

WAAGENT=/usr/sbin/waagent
waagent -version 1> /dev/null 2>&1
if [ $? -eq 0 ]; then
  WAAGENT=waagent
fi
$WAAGENT -force -deprovision+user && export HISTSIZE=0 && sync

Override dei comandi

Per eseguire l'override dei comandi, usare lo strumento di provisioning dello script PowerShell o Shell per creare i file di comando con il nome esatto del file e inserirli nelle directory corrette:

  • Windows: c:\DeprovisioningScript.ps1
  • Linux: /tmp/DeprovisioningScript.sh

Image Builder legge questi comandi, questi comandi vengono scritti nei log AIB, customization.log. Consultare la risoluzione dei problemi su come raccogliere i log.

Proprietà: errorHandling

La errorHandling proprietà consente di configurare la modalità di gestione degli errori durante la creazione dell'immagine.

{
  "errorHandling": {
    "onCustomizerError": "abort",
    "onValidationError": "cleanup"
  }
}

La errorHandling proprietà consente di configurare la modalità di gestione degli errori durante la creazione dell'immagine. Ha due proprietà:

  • onCustomizerError : specifica l'azione da eseguire quando si verifica un errore durante la fase di personalizzazione della creazione dell'immagine.
  • onValidationError : specifica l'azione da eseguire quando si verifica un errore durante la convalida del modello di immagine.

La errorHandling proprietà ha anche due valori possibili per la gestione degli errori durante la creazione dell'immagine:

  • cleanup : assicura che le risorse temporanee create da Packer vengano pulite anche se Packer o una delle personalizzazioni/convalide rileva un errore. Ciò mantiene la compatibilità con le versioni precedenti con il comportamento esistente.
  • abort : nel caso in cui Packer riscontri un errore, il servizio Azure Image Builder (AIB) ignora la pulizia delle risorse temporanee. Il proprietario del modello AIB è responsabile della pulizia di queste risorse dalla sottoscrizione. Queste risorse possono contenere informazioni utili, ad esempio log e file lasciati indietro in una macchina virtuale temporanea, che può essere utile per analizzare l'errore rilevato da Packer.

Proprietà: distribute

Azure Image Builder supporta tre destinazioni di distribuzione:

  • ManagedImage : immagine gestita.
  • sharedImage - Raccolta di calcolo di Azure.
  • VHD - disco rigido virtuale in un account di archiviazione.

È possibile distribuire un'immagine a entrambi i tipi di destinazione nella stessa configurazione.

Nota

Il comando AIB sysprep predefinito non include "/mode:vm", ma questa proprietà potrebbe essere necessaria quando si creano immagini con il ruolo HyperV installato. Se è necessario aggiungere questo argomento di comando, è necessario eseguire l'override del comando sysprep.

Poiché è possibile distribuire in più di una destinazione, Image Builder mantiene uno stato per ogni destinazione di distribuzione a cui è possibile accedere eseguendo una query per runOutputName. runOutputName è un oggetto per cui è possibile eseguire una query dopo la distribuzione per ottenere informazioni su tale distribuzione. Ad esempio, è possibile eseguire una query per il percorso del disco rigido virtuale o delle aree in cui è stata replicata la versione dell'immagine oppure in cui è stata creata la versione dell'immagine SIG. Si tratta di una proprietà di tutte le destinazioni di distribuzione. runOutputName deve essere univoco per ogni destinazione di distribuzione. Di seguito è riportato un esempio per eseguire query sulla distribuzione di una raccolta di calcolo di Azure:

subscriptionID=<subcriptionID>
imageResourceGroup=<resourceGroup of image template>
runOutputName=<runOutputName>

az resource show \
  --ids "/subscriptions/$subscriptionID/resourcegroups/$imageResourceGroup/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/$runOutputName"  \
  --api-version=2021-10-01

Output:

{
  "id": "/subscriptions/xxxxxx/resourcegroups/rheltest/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/rhel77",
  "identity": null,
  "kind": null,
  "location": null,
  "managedBy": null,
  "name": "rhel77",
  "plan": null,
  "properties": {
    "artifactId": "/subscriptions/xxxxxx/resourceGroups/aibDevOpsImg/providers/Microsoft.Compute/galleries/devOpsSIG/images/rhel/versions/0.24105.52755",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "rheltest",
  "sku": null,
  "tags": null,
  "type": "Microsoft.VirtualMachineImages/imageTemplates/runOutputs"
}

Distribute: managedImage

L'output dell'immagine è una risorsa immagine gestita.

{
  "type":"ManagedImage",
  "imageId": "<resource ID>",
  "location": "<region>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Proprietà distribute:

  • type – ManagedImage
  • imageId : ID risorsa dell'immagine di destinazione, formato previsto: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location - percorso dell'immagine gestita.
  • runOutputName - nome univoco per identificare la distribuzione.
  • artifactTags : tag key\value specificati dall'utente facoltativi.

Nota

Il gruppo di risorse di destinazione deve essere esistente. Se si vuole che l'immagine venga distribuita in un'area diversa, il tempo di distribuzione aumenterà.

Distribute: sharedImage

La raccolta di calcolo di Azure è un nuovo servizio di gestione delle immagini che consente di gestire la replica dell'area dell'immagine, il controllo delle versioni e la condivisione di immagini personalizzate. Image Builder di Azure supporta la distribuzione con questo servizio, in modo da poter distribuire immagini alle aree supportate dalle raccolte di calcolo di Azure.

Una raccolta di calcolo di Azure è costituita da:

  • Raccolta : contenitore per più immagini. Una raccolta viene distribuita in un'area.
  • Definizioni di immagini : raggruppamento concettuale per le immagini.
  • Versioni dell'immagine: tipo di immagine usato per la distribuzione di una macchina virtuale o di un set di scalabilità. Le versioni delle immagini possono essere replicate in altre aree in cui è necessario distribuire le macchine virtuali.

Prima di poter eseguire la distribuzione nella raccolta, è necessario creare una raccolta e una definizione di immagine, vedere Creare una raccolta.

Nota

L'ID versione dell'immagine deve essere distinto o diverso da qualsiasi versione dell'immagine presente nella raccolta di calcolo di Azure esistente.

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Il codice JSON seguente è un esempio di come usare il replicationRegions campo per la distribuzione in una raccolta di calcolo di Azure.

  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]

Nota

replicationRegions è deprecato per le distribuzioni della raccolta così come targetRegions viene aggiornata la proprietà . Per altre informazioni, vedere targetRegions.

Distribuisci: targetRegions

Il codice JSON seguente è un esempio di come usare il campo targetRegions per la distribuzione in una raccolta di calcolo di Azure.

"distribute": [
      {
        "type": "SharedImage",
        "galleryImageId": "<resource ID>",
        "runOutputName": "<name>",
        "artifactTags": {
          "<name>": "<value>",
          "<name>": "<value>"
        },
        "targetRegions": [
             {
              "name": "eastus",
              "replicaCount": 2,
              "storageAccountType": "Standard_ZRS"
             },
             {
              "name": "eastus2",
              "replicaCount": 3,
              "storageAccountType": "Premium_LRS"
             }
          ]
       },
    ]

Distribuire le proprietà per le raccolte:

  • type - sharedImage

  • galleryImageId : ID della raccolta di calcolo di Azure, questa proprietà può essere specificata in due formati:

    • Controllo delle versioni automatico - Image Builder genera automaticamente un numero di versione monotonico, questa proprietà è utile per quando si desidera mantenere la ricompilazione delle immagini dallo stesso modello: il formato è: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Controllo delle versioni esplicito: è possibile passare il numero di versione che si vuole che il generatore di immagini usi. Il formato è: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>

  • runOutputName - nome univoco per identificare la distribuzione.

  • artifactTags: tag key\value specificati dall'utente facoltativi .

  • replicationRegions : matrice di aree per la replica. Una delle aree deve essere l'area in cui è distribuita la raccolta. L'aggiunta di aree implica un aumento del tempo di compilazione, perché la compilazione non viene completata fino al completamento della replica. Questo campo è deprecato a partire dalla versione 2022-07-01 dell'API, usare targetRegions quando si distribuisce un tipo "SharedImage".

  • targetRegions : matrice di aree per la replica. È stato appena introdotto come parte dell'API 2022-07-01 e si applica solo alla distribuzione del SharedImage tipo.

  • excludeFromLatest (facoltativo): consente di contrassegnare la versione dell'immagine creata non come versione più recente nella definizione della raccolta, il valore predefinito è "false".

  • storageAccountType (facoltativo): AIB supporta la specifica di questi tipi di archiviazione per la versione dell'immagine da creare:

    • "Standard_LRS"
    • "Standard_ZRS","

Nota

Se il modello di immagine e a cui si fa image definition riferimento non si trovano nella stessa posizione, si noterà tempo aggiuntivo per creare immagini. Image Builder attualmente non dispone di un location parametro per la risorsa della versione dell'immagine, che viene preso dal relativo elemento padre image definition. Ad esempio, se una definizione di immagine è in westus e si vuole che la versione dell'immagine venga replicata in eastus, viene copiato westusun BLOB in , viene creata una risorsa della versione dell'immagine in westus e quindi viene eseguita la replica in eastus. Per evitare il tempo di replica aggiuntivo, assicurarsi che il image definition modello di immagine e si trovi nella stessa posizione.

stringa di query

La proprietà di controllo delle versioni è solo per il sharedImage tipo di distribuzione. Si tratta di un'enumerazione con due valori possibili:

  • latest - Nuovo schema strettamente crescente per ogni progettazione
  • source : schema basato sul numero di versione dell'immagine di origine.

Lo schema di numerazione delle versioni predefinito è latest. Lo schema più recente ha una proprietà aggiuntiva , "major", che specifica la versione principale in cui generare la versione più recente.

Nota

La logica di generazione della versione esistente per sharedImage la distribuzione è deprecata. Sono disponibili due nuove opzioni: versioni che aumentano in modo monotonico che sono sempre la versione più recente in una raccolta e le versioni generate in base al numero di versione dell'immagine di origine. L'enumerazione che specifica lo schema di generazione della versione consente l'espansione in futuro con schemi di generazione di versioni aggiuntivi.

    "distribute": [
        "versioning": {
            "scheme": "Latest",
            "major": 1
        }
    ]

proprietà di controllo delle versioni:

  • scheme : generare un nuovo numero di versione per la distribuzione. Latest o Source sono due valori possibili.
  • major : specifica la versione principale in cui generare la versione più recente. Applicabile solo quando è scheme impostato su Latest. Ad esempio, in una raccolta con le versioni seguenti pubblicate: 0.1.1, 0.1.2, 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0, 2.0.0, 2.0.1, 2.1.0
    • Con major not set o major impostato su 2, Lo Latest schema genera la versione 2.1.1
    • Con il valore principale impostato su 1, lo schema più recente genera la versione 1.2.1
    • Con il valore principale impostato su 0, lo schema più recente genera la versione 0.1.3

Distribuisci: disco rigido virtuale

È possibile eseguire l'output in un disco rigido virtuale. È quindi possibile copiare il disco rigido virtuale e usarlo per pubblicare in Azure Marketplace oppure usarlo con Azure Stack.

{
  "type": "VHD",
  "runOutputName": "<VHD name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Supporto del sistema operativo: Windows e Linux

Parametri del disco rigido virtuale per la proprietà distribute:

  • type - VHD.
  • runOutputName - nome univoco per identificare la distribuzione.
  • tags - facoltativo, tag della coppia chiave-valore specificata dall'utente.

Image Builder di Azure non consente all'utente di specificare una posizione dell'account di archiviazione, ma è possibile eseguire una query sullo stato di runOutputs per ottenere la posizione.

az resource show \
  --ids "/subscriptions/$subscriptionId/resourcegroups/<imageResourceGroup>/providers/Microsoft.VirtualMachineImages/imageTemplates/<imageTemplateName>/runOutputs/<runOutputName>"  | grep artifactUri

Nota

Dopo aver creato il disco rigido virtuale, copiarlo in un percorso diverso appena possibile. Il disco rigido virtuale viene memorizzato in un account di archiviazione nel gruppo di risorse temporaneo creato quando il modello di immagine viene inviato al servizio Image Builder di Azure. Se si elimina il modello di immagine, si perderà il disco rigido virtuale.

Il codice JSON seguente distribuisce l'immagine come disco rigido virtuale a un account di archiviazione personalizzato.

"distribute": [
  {
    "type": "VHD",
    "runOutputName": "<VHD name>",
    "artifactTags": {
        "<name>": "<value>",
        "<name>": "<value>"
    },
    "uri": "<replace with Azure storage URI>"
  }
]

Proprietà di distribuzione del disco rigido virtuale:

URI: URI facoltativo Archiviazione di Azure per il BLOB VHD distribuito. Omettere di usare la stringa predefinita (stringa vuota), nel qual caso il disco rigido virtuale verrà pubblicato nell'account di archiviazione nel gruppo di risorse di staging.

Proprietà: ottimizzare

La optimize proprietà può essere abilitata durante la creazione di un'immagine di macchina virtuale e consente all'ottimizzazione della macchina virtuale di migliorare il tempo di creazione dell'immagine.

"optimize": {
      "vmboot": {
        "state": "Enabled"
      }
    }
  • vmboot: una configurazione correlata al processo di avvio della macchina virtuale (VM), usata per controllare le ottimizzazioni che possono migliorare il tempo di avvio o altri aspetti delle prestazioni.
  • state: lo stato della funzionalità di ottimizzazione dell'avvio all'interno vmbootdi , con il valore Enabled che indica che la funzionalità è attivata per migliorare il tempo di creazione dell'immagine.

Per altre informazioni, vedere Ottimizzazione delle macchine virtuali per le immagini della raccolta con Image Builder di macchine virtuali di Azure.

Proprietà: source

La sezione source contiene informazioni sull'immagine di origine che verrà usata da Image Builder. Azure Image Builder supporta solo immagini generalizzate come immagini di origine, le immagini specializzate non sono attualmente supportate.

L'API richiede un SourceType oggetto che definisce l'origine per la compilazione dell'immagine, attualmente sono disponibili tre tipi:

  • PlatformImage: indica che l'immagine di origine è un'immagine del Marketplace.
  • ManagedImage: usato quando si inizia da un'immagine gestita normale.
  • SharedImageVersion: usato quando si usa una versione dell'immagine in una raccolta di calcolo di Azure come origine.

Nota

Quando si usano immagini personalizzate di Windows esistenti, è possibile eseguire il comando Sysprep fino a tre volte in un'unica immagine windows 7 o Windows Server 2008 R2 o 1001 volte in una singola immagine di Windows per le versioni successive; Per altre informazioni, vedere la documentazione di sysprep .

Origine PlatformImage

Image Builder di Azure supporta le immagini windows Server e client e Linux di Azure Marketplace, vedere Informazioni su Azure Image Builder per l'elenco completo.

"source": {
  "type": "PlatformImage",
  "publisher": "Canonical",
  "offer": "UbuntuServer",
  "sku": "18.04-LTS",
  "version": "latest"
}

Le proprietà sono le stesse usate per creare le macchine virtuali con l'interfaccia della riga di comando AZ; eseguire il comando seguente per ottenere le proprietà:

az vm image list -l westus -f UbuntuServer -p Canonical --output table --all

È possibile usare latest nella versione, la versione viene valutata quando viene eseguita la compilazione dell'immagine, non quando viene inviato il modello. Se si usa questa funzionalità con la destinazione della raccolta di calcolo di Azure, è possibile evitare di inviare nuovamente il modello ed eseguire di nuovo la compilazione dell'immagine a intervalli, in modo che le immagini vengano ricreate dalle immagini più recenti.

Supporto per informazioni sul piano sul mercato

È anche possibile specificare informazioni sul piano, ad esempio:

"source": {
  "type": "PlatformImage",
  "publisher": "RedHat",
  "offer": "rhel-byos",
  "sku": "rhel-lvm75",
  "version": "latest",
  "planInfo": {
    "planName": "rhel-lvm75",
    "planProduct": "rhel-byos",
    "planPublisher": "redhat"
  }
}

Origine ManagedImage

Imposta l'immagine di origine come un'immagine gestita esistente di un disco rigido virtuale generalizzato o di una macchina virtuale.

Nota

L'immagine gestita di origine deve essere di un sistema operativo supportato e l'immagine deve trovarsi nella stessa sottoscrizione e nella stessa area del modello di Image Builder di Azure.

"source": {
  "type": "ManagedImage",
  "imageId": "/subscriptions/<subscriptionId>/resourceGroups/{destinationResourceGroupName}/providers/Microsoft.Compute/images/<imageName>"
}

imageId deve essere l'ID della risorsa dell'immagine gestita. Usare az image list per elencare le immagini disponibili.

Origine SharedImageVersion

Imposta l'immagine di origine come versione dell'immagine esistente in una raccolta di calcolo di Azure.

Nota

La versione dell'immagine condivisa di origine deve essere di un sistema operativo supportato e la versione dell'immagine deve risiedere nella stessa area del modello di Image Builder di Azure, in caso contrario, replicare la versione dell'immagine nell'area modello di Image Builder.

"source": {
  "type": "SharedImageVersion",
  "imageVersionID": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId : ID risorsa del modello di Resource Manager della versione dell'immagine. Quando il nome della versione dell'immagine è 'latest', la versione viene valutata quando viene eseguita la compilazione dell'immagine. Deve imageVersionId essere della ResourceId versione dell'immagine. Usare az sig image-version list per elencare le versioni delle immagini.

Il codice JSON seguente imposta l'immagine di origine come immagine archiviata in una raccolta condivisa diretta.

Nota

La raccolta condivisa diretta è attualmente disponibile in anteprima.

    source: {
      "type": "SharedImageVersion",
      "imageVersionId": "<replace with resourceId of the image stored in the Direct Shared Gallery>"
    },

Il codice JSON seguente imposta l'immagine di origine come versione più recente dell'immagine per un'immagine archiviata in una raccolta di calcolo di Azure.

"properties": {
    "source": {
        "type": "SharedImageVersion",
        "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<azureComputeGalleryName>/images/<imageDefinitionName>/versions/latest"
    }
},

Proprietà SharedImageVersion:

imageVersionId : ID risorsa del modello di Resource Manager della versione dell'immagine. Quando il nome della versione dell'immagine è 'latest', la versione viene valutata quando viene eseguita la compilazione dell'immagine.

Proprietà: stagingResourceGroup

La stagingResourceGroup proprietà contiene informazioni sul gruppo di risorse di staging creato dal servizio Image Builder durante il processo di compilazione dell'immagine. stagingResourceGroup è una proprietà facoltativa per chiunque desideri un maggiore controllo sul gruppo di risorse creato da Image Builder durante il processo di compilazione dell'immagine. È possibile creare un gruppo di risorse personalizzato e specificarlo nella stagingResourceGroup sezione oppure crearne uno per conto di Image Builder.

Importante

Il gruppo di risorse di staging specificato non può essere associato a un altro modello di immagine, deve essere vuoto (nessuna risorsa all'interno), nella stessa area del modello di immagine e avere il controllo degli accessi in base al ruolo "Collaboratore" o "Proprietario" applicato all'identità assegnata alla risorsa modello di immagine di Image Builder di Azure.

"properties": {
  "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>"
}

Scenari di creazione di modelli

  • La proprietà stagingResourceGroup rimane vuota

    Se la stagingResourceGroup proprietà non è specificata o specificata con una stringa vuota, il servizio Image Builder crea un gruppo di risorse di staging con la convenzione di nome predefinita "IT_**". Al gruppo di risorse di staging sono applicati i tag predefiniti: createdBy, imageTemplateName, imageTemplateResourceGroupName. Inoltre, il controllo degli accessi in base al ruolo predefinito viene applicato all'identità assegnata alla risorsa modello di Azure Image Builder, ovvero "Collaboratore".

  • La proprietà stagingResourceGroup viene specificata con un gruppo di risorse esistente

    Se la stagingResourceGroup proprietà viene specificata con un gruppo di risorse esistente, il servizio Image Builder verifica che il gruppo di risorse non sia associato a un altro modello di immagine, è vuoto (nessuna risorsa all'interno), nella stessa area del modello di immagine e ha il controllo degli accessi in base al ruolo "Collaboratore" o "Proprietario" applicato all'identità assegnata alla risorsa modello di immagine di Azure Image Builder. Se uno dei requisiti indicati in precedenza non viene soddisfatto, viene generato un errore. Al gruppo di risorse di staging sono stati aggiunti i tag seguenti: usedBy, imageTemplateName, imageTemplateResourceGroupName. I tag preesistenti non vengono eliminati.

Importante

È necessario assegnare il ruolo di collaboratore al gruppo di risorse per l'entità servizio corrispondente all'app di prima parte di Image Builder di Azure quando si tenta di specificare un gruppo di risorse e una rete virtuale preesistenti al servizio Azure Image Builder con un'immagine di origine Di Windows. Per istruzioni sul comando e sul portale dell'interfaccia della riga di comando su come assegnare il ruolo collaboratore al gruppo di risorse, vedere la documentazione seguente Risolvere i problemi relativi a Image Builder di macchine virtuali di Azure: Errore di autorizzazione durante la creazione del disco

  • La proprietà stagingResourceGroup viene specificata con un gruppo di risorse che non esiste

    Se la stagingResourceGroup proprietà viene specificata con un gruppo di risorse che non esiste, il servizio Image Builder crea un gruppo di risorse di staging con il nome specificato nella stagingResourceGroup proprietà . Se il nome specificato non soddisfa i requisiti di denominazione di Azure per i gruppi di risorse, si verifica un errore. Al gruppo di risorse di staging sono applicati i tag predefiniti: createdBy, imageTemplateName, imageTemplateResourceGroupName. Per impostazione predefinita, l'identità assegnata alla risorsa modello di immagine di Image Builder di Azure ha il controllo degli accessi in base al ruolo "Collaboratore" applicato nel gruppo di risorse.

Eliminazione del modello

Qualsiasi gruppo di risorse di staging creato dal servizio Image Builder verrà eliminato dopo l'eliminazione del modello di immagine. L'eliminazione include i gruppi di risorse di staging specificati nella stagingResourceGroup proprietà , ma non esistevano prima della compilazione dell'immagine.

Se Image Builder non ha creato il gruppo di risorse di staging, ma le risorse all'interno del gruppo di risorse verranno eliminate dopo l'eliminazione del modello di immagine, dato che il servizio Image Builder ha le autorizzazioni o il ruolo appropriati necessari per eliminare le risorse.

Proprietà: convalidare

È possibile usare la validate proprietà per convalidare le immagini della piattaforma e le immagini personalizzate create indipendentemente dall'uso di Image Builder di Azure per crearle.

Image Builder di Azure supporta una modalità 'Source-Validation-Only' che può essere impostata usando la sourceValidationOnly proprietà . Se la sourceValidationOnly proprietà è impostata su true, l'immagine specificata nella source sezione verrà convalidata direttamente. Non verrà eseguita alcuna compilazione separata per generare e quindi convalidare un'immagine personalizzata.

La inVMValidations proprietà accetta un elenco di validator che verranno eseguiti sull'immagine. Azure Image Builder supporta validator file, PowerShell e Shell.

La continueDistributeOnFailure proprietà è responsabile se le immagini di output verranno distribuite in caso di esito negativo della convalida. Per impostazione predefinita, se la convalida ha esito negativo e questa proprietà è impostata su false, le immagini di output non verranno distribuite. Se la convalida ha esito negativo e questa proprietà è impostata su true, le immagini di output verranno comunque distribuite. Usare questa opzione con cautela perché può comportare la distribuzione di immagini non riuscite per l'uso. In entrambi i casi (true o false), l'esecuzione dell'immagine end-to-end verrà segnalata come non riuscita se si verifica un errore di convalida. Questa proprietà non ha alcun effetto sul fatto che la convalida abbia esito positivo o negativo.

Quando si usa validate:

  • È possibile usare più validator.
  • I validator sono eseguiti nell'ordine specificato nel modello.
  • Se un validator ha esito negativo, l'intero componente di convalida avrà esito negativo e restituirà un errore.
  • È consigliabile testare accuratamente lo script prima di usarlo in un modello. Il debug dello script nella propria macchina virtuale sarà più semplice.
  • Non inserire dati sensibili negli script.
  • I percorsi degli script devono essere accessibili pubblicamente, a meno che non si usi l'identità del servizio gestito.

Come usare la proprietà per convalidare le validate immagini di Windows:

{
   "properties":{
      "validate":{
         "continueDistributeOnFailure":false,
         "sourceValidationOnly":false,
         "inVMValidations":[
            {
               "type":"File",
               "destination":"string",
               "sha256Checksum":"string",
               "sourceUri":"string"
            },
            {
               "type":"PowerShell",
               "name":"test PowerShell validator inline",
               "inline":[
                  "<command to run inline>"
               ],
               "validExitCodes":"<exit code>",
               "runElevated":"<true or false>",
               "runAsSystem":"<true or false>"
            },
            {
               "type":"PowerShell",
               "name":"<name>",
               "scriptUri":"<path to script>",
               "runElevated":"<true false>",
               "sha256Checksum":"<sha256 checksum>"
            }
         ]
      }
   }
}

inVMValidations Proprietà:

  • type - PowerShell.

  • name : nome del validator

  • scriptUri : URI del file di script di PowerShell.

  • inline : matrice di comandi da eseguire, separati da virgole.

  • validExitCodes: codici facoltativi validi che possono essere restituiti dal comando script/inline, in questo modo si evita l'errore segnalato del comando script/inline.

  • runElevated - valore facoltativo, booleano, supporto per l'esecuzione di comandi e script con autorizzazioni elevate.

  • sha256Checksum - valore di checksum sha256 del file, viene generato in locale, quindi Image Builder lo genera e lo verifica.

    Per generare sha256Checksum, usare il comando Get-hash di PowerShell in Windows

Come usare la proprietà per convalidare le validate immagini Linux:

{
  "properties": {
    "validate": {
      "continueDistributeOnFailure": false,
      "sourceValidationOnly": false,
      "inVMValidations": [
        {
          "type": "Shell",
          "name": "<name>",
          "inline": [
            "<command to run inline>"
          ]
        },
        {
          "type": "Shell",
          "name": "<name>",
          "scriptUri": "<path to script>",
          "sha256Checksum": "<sha256 checksum>"
        },
        {
          "type": "File",
          "destination": "string",
          "sha256Checksum": "string",
          "sourceUri": "string"
        }
      ]
    }
  }
}

inVMValidations Proprietà:

  • type : shell o file specificato come tipo di convalida da eseguire.

  • name : nome del validator

  • scriptUri - URI del file di script

  • inline : matrice di comandi da eseguire, separati da virgole.

  • sha256Checksum - valore di checksum sha256 del file, viene generato in locale, quindi Image Builder lo genera e lo verifica.

    Per generare sha256Checksum, usando un terminale in Mac o Linux eseguire: sha256sum <fileName>

  • destination : destinazione del file.

  • sha256Checksum: specifica il checksum SHA256 del file.

  • sourceUri : URI di origine del file.

Proprietà: vmProfile

vmSize (facoltativo)

Image Builder usa una dimensione sku predefinita di Standard_D1_v2 per le immagini Gen1 e Standard_D2ds_v4 per le immagini Gen2. La generazione viene definita dall'immagine specificata in source. È possibile eseguire l'override di vmSize per questi motivi:

  • Esecuzione di personalizzazioni che richiedono una maggiore quantità di memoria, CPU e gestione di file di grandi dimensioni ( GB).
  • Esecuzione di build di Windows, è consigliabile usare "Standard_D2_v2" o le dimensioni equivalenti della macchina virtuale.
  • Richiedere l'isolamento della macchina virtuale.
  • Personalizzare un'immagine che richiede hardware specifico. Ad esempio, per una macchina virtuale GPU è necessaria una dimensione di MACCHINA virtuale GPU.
  • Richiedere la crittografia end-to-end nella macchina virtuale di compilazione, è necessario specificare le dimensioni della macchina virtuale di compilazione di supporto che non usano dischi temporanei locali.

osDiskSizeGB

Per impostazione predefinita, Image Builder non modifica le dimensioni dell'immagine, ma usa le dimensioni dell'immagine di origine. Facoltativamente, è possibile aumentare solo le dimensioni del disco del sistema operativo (Win e Linux) e il valore 0 significa lasciare le stesse dimensioni dell'immagine di origine. Non è possibile ridurre le dimensioni del disco del sistema operativo a dimensioni inferiori a quelle dell'immagine di origine.

{
  "osDiskSizeGB": 100
}

vnetConfig (facoltativo)

Se non si specificano proprietà della rete virtuale, Image Builder crea una propria rete virtuale, un indirizzo IP pubblico e un gruppo di sicurezza di rete. L'indirizzo IP pubblico viene usato per comunicare con il servizio con la macchina virtuale di compilazione. Se non si vuole avere un indirizzo IP pubblico o si vuole che Image Builder abbia accesso alle risorse di rete virtuale esistenti, ad esempio i server di configurazione (DSC, Chef, Puppet, Ansible), le condivisioni file, è possibile specificare una rete virtuale. Per altre informazioni, vedere la documentazione sulla rete.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
}

Operazioni sul modello di immagine

Avvio di una compilazione di immagini

Per avviare una compilazione, è necessario richiamare "Esegui" nella risorsa Modello di immagine, esempi di run comandi:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Run -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

Annullamento di una compilazione di immagini

Se si esegue una compilazione di immagini che si ritiene non corretta, in attesa dell'input dell'utente o si ritiene che non venga mai completata correttamente, è possibile annullare la compilazione.

La compilazione può essere annullata in qualsiasi momento. Se la fase di distribuzione è stata avviata, è comunque possibile annullare, ma è necessario pulire tutte le immagini che potrebbero non essere completate. Il comando cancel non attende il completamento dell'annullamento, monitora lastrunstatus.runstate lo stato di avanzamento dell'annullamento, usando questi comandi di stato.

Esempi di cancel comandi:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Cancel -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Cancel

Passaggi successivi

Nel GitHub di Image Builder di Azure sono disponibili file JSON di esempio per diversi scenari.