Freigeben über

Erstellen einer Azure Image Builder-Bicep- oder -ARM-JSON-Vorlage

  • Artikel

Gilt für: ✔️ Linux-VMs ✔️ Windows-VMs ✔️ Flexible Skalierungsgruppen

Azure Image Builder verwendet eine Bicep-Datei oder eine ARM-JSON-Vorlagendatei, um Informationen an den Image Builder-Dienst zu übergeben. In diesem Artikel werden die einzelnen Abschnitte der Dateien erläutert, damit Sie Ihre eigene Datei erstellen können. Informationen zu den neuesten API-Versionen finden Sie in der Vorlagenreferenz. Vollständige JSON-Beispieldateien finden Sie im GitHub-Repository für Azure Image Builder.

Das grundlegende Format ist:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "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/<subnetName1>",
        "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
        "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>",
        ...
      ]
    }
  }
}

API-Version

Die API-Version ändert sich im Laufe der Zeit, während sich die API ändert. Weitere Informationen zu allen wichtigen API-Änderungen und Featureupdates für den Azure VM Image Builder-Dienst finden Sie unter Neuerungen in Azure VM Image Builder.

type

type ist der Ressourcentyp, der Microsoft.VirtualMachineImages/imageTemplates entsprechen muss.

"type": "Microsoft.VirtualMachineImages/imageTemplates",

Standort

„Location“ entspricht der Region, in der das benutzerdefinierte Image erstellt wird. Die folgenden Regionen werden unterstützt:

  • East US
  • USA (Ost) 2
  • USA, Westen-Mitte
  • USA (Westen)
  • USA, Westen 2
  • USA, Westen 3
  • USA Süd Mitte
  • Nordeuropa
  • Europa, Westen
  • Südostasien
  • Australien, Südosten
  • Australien (Osten)
  • UK, Süden
  • UK, Westen
  • Brasilien Süd
  • Kanada, Mitte
  • Indien, Mitte
  • USA (Mitte)
  • Frankreich, Mitte
  • Deutschland, Westen-Mitte
  • Japan, Osten
  • USA Nord Mitte
  • Norwegen, Osten
  • Schweiz, Norden
  • Jio Indien, Westen
  • Vereinigte Arabische Emirate, Norden
  • Asien, Osten
  • Korea, Mitte
  • Südafrika, Norden
  • Katar, Mitte
  • USGov Arizona (Public Preview)
  • USGov Virginia (Public Preview)
  • China, Norden 3 (Public Preview)
  • Schweden, Mitte
  • Polen, Mitte
  • Italien, Norden
  • Israel, Mitte

Wichtig

Registrieren Sie die Funktion Microsoft.VirtualMachineImages/FairfaxPublicPreview, um auf die öffentliche Vorschau von Azure Image Builder in den Azure Government-Regionen (USGov Arizona und USGov Virginia) zuzugreifen.

Wichtig

Registrieren Sie das Feature Microsoft.VirtualMachineImages/MooncakePublicPreview für den Zugriff auf die öffentliche Vorschauversion von Azure Image Builder in der Region „China, Norden 3“.

Um auf die öffentliche Vorschau von Azure VM Image Builder in den Azure Government-Regionen (USGov Arizona und USGov Virginia) zuzugreifen, müssen Sie das Feature Microsoft.VirtualMachineImages/FairfaxPublicPreview registrieren. Führen Sie hierzu den folgenden Befehl entweder in PowerShell oder in der Azure-Befehlszeilenschnittstelle aus:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

Um auf die öffentliche Vorschau von Azure VM Image Builder in der Region „China, Norden 3“ zuzugreifen, müssen Sie das Feature Microsoft.VirtualMachineImages/MooncakePublicPreview registrieren. Führen Sie hierzu den folgenden Befehl entweder in PowerShell oder in der Azure-Befehlszeilenschnittstelle aus:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Datenresidenz

Der Azure VM Image Builder-Dienst speichert oder verarbeitet Kundendaten nicht außerhalb von Regionen, die strenge Anforderungen an die Datenresidenz in einer Region haben, wenn ein Kunde einen Build in dieser Region anfordert. Bei einem Dienstausfall für Regionen mit Anforderungen an die Datenresidenz müssen Sie Bicep-Dateien/-Vorlagen in einer anderen Region und Geografie erstellen.

Zonenredundanz

Die Verteilung unterstützt Zonenredundanz, VHDs werden standardmäßig auf ein Konto für zonenredundanten Speicher (ZRS) verteilt, und die Version der Azure Compute Gallery (ehemals Shared Image Gallery) unterstützt einen ZRS-Speichertyp, falls angegeben.

`Tags`

Tags sind Schlüssel-Wert-Paare, die Sie für das generierte Image angeben können.

Identity

Es gibt zwei Möglichkeiten, vom Benutzer zugewiesene Identitäten hinzuzufügen, die unten erläutert werden.

Vom Benutzer zugewiesene Identität für die Imagevorlagenressource von Azure Image Builder

Erforderlich: Damit Image Builder die Berechtigung zum Lesen/Schreiben von Images hat und Skripts aus Azure Storage lesen darf, müssen Sie eine benutzerseitig zugewiesene Azure-Identität erstellen, die über Berechtigungen für die einzelnen Azure-Ressourcen verfügt. Einzelheiten zur Funktionsweise von Image Builder-Berechtigungen sowie die entsprechenden Schritte finden Sie unter Erstellen eines Images und Verwenden einer benutzerseitig zugewiesenen verwalteten Identität für den Zugriff auf Dateien in einem Azure-Speicherkonto.

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

Die vom Benutzer zugewiesene Identität des Image Builder-Diensts:

  • Unterstützt nur eine einzelne Identität.
  • Unterstützt keine benutzerdefinierten Domänennamen.

Weitere Informationen finden Sie unter Was sind verwaltete Identitäten für Azure-Ressourcen?. Weitere Informationen zur Bereitstellung dieses Features finden Sie unter Konfigurieren von verwalteten Identitäten für Azure-Ressourcen auf einem virtuellen Azure-Computer mithilfe der Azure-Befehlszeilenschnittstelle.

Benutzerseitig zugewiesene Identität für die Image Builder-Build-VM

Dieses Feld ist nur in den API-Versionen 2021-10-01 oder höher verfügbar.

Optional: Die Image Builder-Build-VM, die vom Image Builder-Dienst in Ihrem Abonnement erstellt wird, wird zum Erstellen und Anpassen des Images verwendet. Damit die Image Builder Build-VM über Berechtigungen für die Authentifizierung bei anderen Diensten in Ihrem Abonnement wie Azure Key Vault verfügt, müssen Sie mindestens eine Azure-Benutzeridentität erstellen, die Berechtigungen für die einzelnen Ressourcen aufweist. Azure Image Builder kann diese vom Benutzer zugewiesenen Identitäten dann dem virtuellen Buildcomputer zuordnen. Benutzerdefinierte Skripts, die auf der Build-VM ausgeführt werden, können Token für diese Identitäten abrufen und bei Bedarf mit anderen Azure-Ressourcen interagieren. Beachten Sie, dass die vom Benutzer zugewiesene Identität für Azure Image Builder über die Rollenzuweisung „Operator für verwaltete Identitäten“ für alle vom Benutzer zugewiesenen Identitäten für Azure Image Builder verfügen muss, um sie dem virtuellen Buildcomputer zuordnen zu können.

Hinweis

Beachten Sie, dass mehrere Identitäten für die Image Builder Build-VM angegeben werden können, einschließlich der Identität, die Sie für die Imagevorlagenressource erstellt haben. Standardmäßig wird die Identität, die Sie für die Imagevorlagenressource erstellt haben, der Build-VM nicht automatisch hinzugefügt.

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

Vom Benutzer zugewiesene Identität für die Image Builder Build-VM:

  • Unterstützt eine Liste mit mindestens einer benutzerseitig zugewiesenen verwalteten Identität, die auf der VM konfiguriert werden soll.
  • Unterstützt abonnementübergreifende Szenarien (Identität wird in einem Abonnement erstellt, während die Imagevorlage in einem anderen Abonnement unter demselben Mandanten erstellt wird).
  • Unterstützt keine mandantenübergreifenden Szenarien (Identität wird in einem Mandanten erstellt, während die Imagevorlage in einem anderen Mandanten erstellt wird).

Weitere Informationen finden Sie unter:

Eigenschaften: buildTimeoutInMinutes

Maximale Wartezeit beim Erstellen der Imagevorlage (umfasst alle Anpassungen, Überprüfungen und Distributionen).

Wenn Sie die Eigenschaft nicht angeben oder den Wert auf 0 festlegen, wird der Standardwert verwendet, der 240 Minuten (vier Stunden) beträgt. Der Mindestwert ist 6  Minuten, der Maximalwert 960 Minuten (16 Stunden). Wenn der Timeoutwert erreicht wird (unabhängig davon, ob der Imagebuild abgeschlossen ist), wird eine Fehlermeldung ähnlich der folgenden angezeigt:

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

Für Windows wird empfohlen, buildTimeoutInMinutes nicht auf einen Wert unter 60 Minuten festzulegen. Wenn es zu einem Timeout kommt, überprüfen Sie in den Protokollen, ob der Anpassungsschritt auf ein Ereignis wartet, z. B. auf eine Benutzereingabe. Wenn Sie mehr Zeit benötigen, damit Anpassungen abgeschlossen werden können, erhöhen Sie den buildTimeoutInMinutes-Wert. Wählen Sie aber keinen zu hohen Wert, da ein Fehler erst bei einem Timeout angezeigt wird.

Eigenschaften: customize

Image Builder unterstützt mehrere „Anpassungen“. Dies sind Funktionen zum Anpassen Ihres Image, z. B. zum Ausführen von Skripts oder Neustarten von Servern.

Folgendes ist bei Verwendung von customize zu beachten:

  • Sie können mehrere Anpassungen verwenden.
  • Anpassungen werden nach der in der Vorlage festgelegten Reihenfolge ausgeführt.
  • Wenn eine Anpassung fehlschlägt, schlägt die gesamte Anpassungskomponente fehl, und ein Fehler wird zurückgegeben.
  • Testen Sie die Skripts gründlich, bevor Sie sie in einer Vorlage verwenden. Das Debuggen der Skripts selbst ist einfacher.
  • Fügen Sie in die Skripts keine vertraulichen Daten ein. Inlinebefehle können in der Imagevorlagendefinition angezeigt werden. Wenn Sie über sensible Informationen wie Kennwörter, SAS-Token oder Authentifizierungstoken verfügen, sollten diese in Skripts in Azure Storage verschoben werden, weil dort für den Zugriff Authentifizierung erforderlich ist.
  • Die Speicherorte für die Skripts müssen öffentlich zugänglich sein, es sei denn, Sie verwenden die verwaltete Dienstidentität.

Der Abschnitt „customize“ ist ein Array. Die unterstützten Anpassungstypen sind: Datei, PowerShell, Shell, WindowsRestart und 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"
  }
]

Shellanpassung

Die Shell-Anpassung unterstützt die Ausführung von Shellskripts unter Linux. Die Shellskripts müssen öffentlich zugänglich sein, oder Sie müssen eine MSI konfiguriert haben, damit Image Builder auf sie zugreifen kann.

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

Anpassungseigenschaften:

  • type: Shell.

  • name: Name für die Nachverfolgung der Anpassung.

  • scriptUri: URI für den Speicherort der Datei.

  • inline: Array von Shellbefehlen, die durch Kommas getrennt sind

  • sha256Checksum: Der Wert der SHA256-Prüfsumme der Datei, den Sie lokal generieren. Anschließend überprüft Image Builder die Prüfsumme und validiert sie.

    Um sha256Checksum mithilfe eines Terminals unter Mac/Linux zu generieren, führen Sie Folgendes aus: sha256sum <fileName>

Hinweis

Inlinebefehle werden als Bestandteil der Imagevorlagendefinition gespeichert. Sie können sie anzeigen, indem Sie die Imagedefinition ausgeben. Wenn Sie vertrauliche Befehle oder Werte wie Kennwörter, SAS-Token oder Authentifizierungstoken verwenden, empfiehlt es sich, diese in Skripts zu verschieben und eine Benutzeridentität zur Authentifizierung bei Azure Storage zu verwenden.

Administratorrechte

Stellen Sie den Befehlen sudo als Präfix voran, um sie mit Superuserberechtigungen auszuführen. Sie können die Befehle in Skripts hinzufügen oder Inlinebefehle verwenden, beispielsweise:

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

Beispiel eines Skripts mit dem Präfix „sudo“, auf das mithilfe von „scriptUri“ verwiesen werden kann:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

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

Windows-Neustartanpassung

Mithilfe der WindowsRestart-Anpassung können Sie eine Windows-VMM neu starten und darauf warten, dass die VM wieder online geschaltet wird. Diese Anpassung ermöglicht die Installation von Software, für die ein Neustart erforderlich ist.

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

Anpassungseigenschaften:

  • Typ: WindowsRestart.
  • restartCommand: Hiermit wird der Befehl zum Ausführen des Neustarts festgelegt (Optional). Der Standardwert lautet 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand: Befehl zur Überprüfung, ob der Neustart erfolgreich war (Optional).
  • restartTimeout: Zeichenfolge von Größe und Einheit des Timeouts für den Neustart. z. B. 5m (5 Minuten) oder 2h (2 Stunden). Der Standardwert lautet 5m.

Hinweis

Es gibt keinen Linux-Neustartanpasser.

PowerShell-Anpassung

Die PowerShell-Anpassung unterstützt das Ausführen von PowerShell-Skripts und Inlinebefehlen unter Windows. Diese Skripts müssen öffentlich zugänglich sein, damit Image Builder auf diese zugreifen kann.

"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>
  }
]

Anpassungseigenschaften:

  • type: PowerShell

  • scriptUri: URI für den Speicherort der PowerShell-Skriptdatei

  • inline: Durch Kommas getrennte Inlinebefehle, die ausgeführt werden sollen

  • validExitCodes: Optionale, gültige Codes, die von dem Skript/Inlinebefehl zurückgegeben werden können. Die Eigenschaft verhindert den gemeldeten Fehler des Skripts/Inlinebefehls.

  • runElevated: Optionaler boolescher Wert, Unterstützung für das Ausführen von Befehlen und Skripts mit erhöhten Berechtigungen.

  • runAsSystem – Optional, boolesch, bestimmt, ob das PowerShell-Skript als Systembenutzer ausgeführt werden soll.

  • sha256Checksum – Generieren Sie die SHA256-Prüfsumme der Datei lokal, aktualisieren Sie den Prüfsummenwert in Kleinbuchstaben, und Image Builder überprüft die Prüfsumme während der Bereitstellung der Imagevorlage.

    Um Sha256Checksum zu generieren, verwenden Sie das Cmdlet Get-FileHash in PowerShell.

Dateianpassung

Mithilfe der File-Anpassung kann Image Builder eine Datei aus einem GitHub-Repository oder Azure Storage herunterladen. Die Anpassung unterstützt sowohl Linux als auch Windows. Wenn Sie über eine Buildpipeline für Images verfügen, die Buildartefakte verwendet, können Sie die Dateianpassung für den Download aus der Buildfreigabe konfigurieren und die Artefakte in das Image verschieben.

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

Dateianpassungseigenschaften:

  • sourceUri: ein Speicherendpunkt, auf den zugegriffen werden kann. Hier kann GitHub oder Azure Storage verwendet werden. Sie können nur eine Datei herunterladen, kein ganzes Verzeichnis. Wenn Sie ein Verzeichnis herunterladen müssen, verwenden Sie eine komprimierte Datei, und dekomprimieren Sie diese dann mithilfe der Shell- oder PowerShell-Anpassungen.

    Hinweis

    Wenn sourceUri ein Azure Storage-Konto ist, müssen Sie unabhängig davon, ob das Blob als öffentlich markiert ist, der verwalteten Benutzeridentität Berechtigungen für den Schreibzugriff auf das Blob erteilen. Informationen zum Festlegen der Speicherberechtigungen finden Sie in diesem Beispiel.

  • destination: Der vollständige Zielpfad mit dem Dateinamen. Alle referenzierten Pfade und Unterverzeichnisse müssen vorhanden sein. Verwenden Sie die Shell- oder PowerShell-Anpassungen, um diese im Voraus einzurichten. Sie können die Skriptanpassungen zum Erstellen des Pfads verwenden.

Diese Anpassung wird von Windows-Verzeichnissen und Linux-Pfaden unterstützt, jedoch gibt es einige Unterschiede:

  • Linux: Image Builder kann nur in den Pfad „/tmp“ schreiben.
  • Windows: Es besteht keine Pfadeinschränkung, jedoch muss der Pfad vorhanden sein.

Wenn beim Herunterladen der Datei oder beim Platzieren der Datei im festgelegten Verzeichnis ein Fehler auftritt, schlägt der Anpassungsschritt fehl. Dieser Fehler wird im Protokoll „customization.log“ dokumentiert.

Hinweis

Die Dateianpassung ist nur für kleine Dateidownloads geeignet, < 20 MB. Für größere Dateidownloads verwenden Sie einen Skript- oder Inline-Befehl und dann den Code zum Herunterladen von Dateien, z. B. Linux wget oder curl, Windows, Invoke-WebRequest. Für Dateien, die sich im Azure-Speicher befinden, stellen Sie sicher, dass Sie der Build-VM eine Identität zuweisen, die die Berechtigung hat, diese Datei anzuzeigen. Folgen Sie dazu der Dokumentation hier: Vom Benutzer zugewiesene Identität für die Image Builder Build-VM. Jede Datei, die nicht in Azure gespeichert ist, muss öffentlich zugänglich sein, damit Azure Image Builder sie herunterladen kann.

  • sha256Checksum – Generieren Sie die SHA256-Prüfsumme der Datei lokal, aktualisieren Sie den Prüfsummenwert in Kleinbuchstaben, und Image Builder überprüft die Prüfsumme während der Bereitstellung der Imagevorlage.

    Um Sha256Checksum zu generieren, verwenden Sie das Cmdlet Get-FileHash in PowerShell.

Windows Update-Anpassung

Die WindowsUpdate-Anpassung basiert auf dem Community Windows Update Provisioner für Packer. Dabei handelt es sich um ein von der Packer-Community verwaltetes Open-Source-Projekt. Microsoft testet und überprüft den Provisioner mit dem Image Builder-Dienst und unterstützt das Untersuchen von Problemen mit dem Dienst sowie das Beheben von Problemen. Das Open-Source-Projekt wird jedoch nicht offiziell von Microsoft unterstützt. Eine ausführliche Dokumentation und Hilfe zu Windows Update Provisioner finden Sie im Projektrepository.

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

Anpassungseigenschaften:

  • type: WindowsUpdate
  • searchCriteria: Optional, definiert, welche Art von Updates installiert werden (wie etwa empfohlene Updates oder wichtige Updates), die Standardeinstellung ist „BrowseOnly=0 and „IsInstalled=0“ (Recommended).
  • filters: Optional können Sie einen Filter zum Ein- oder Ausschließen von Updates angeben.
  • updateLimit: Optional, definiert, wie viele Updates installiert werden können. Der Standardwert ist „1000“.

Hinweis

Die Windows Update-Anpassung kann einen Fehler verursachen, wenn Windows-Neustarts ausstehen oder Anwendungsinstallationen noch ausgeführt werden. in der Regel wird dieser Fehler in der Datei „customization.log“ angezeigt: System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. Es wird dringend empfohlen, einen Windows-Neustart hinzuzufügen und/oder in Anwendungen mithilfe von sleep- oder wait-Befehlen in den Inlinebefehlen oder Skripts genug Zeit zum Abschluss der Installation festzulegen, bevor Sie Windows Update ausführen.

Generalize

Azure Image Builder führt außerdem nach jeder Imageanpassungsphase standardmäßig deprovision-Code aus, um das Image zu generalisieren. Das Generalisieren ist ein Prozess, bei dem das Image so eingerichtet wird, dass es für die Erstellung mehrerer VMs wiederverwendet werden kann. Azure Image Builder verwendet Sysprep für Windows-VMs. Unter Linux führt Azure Image Builder waagent -deprovision aus.

Die Befehle, die Image Builder für die Generalisierung verwendet, eignen sich möglicherweise nicht für jede Situation, weshalb Azure Image Builder die Anpassung der Befehle bei Bedarf zulässt.

Wenn Sie vorhandene Anpassungen migrieren und verschiedene Sysprep- oder waagent-Befehle verwenden, können Sie die allgemeinen Image Builder-Befehle nutzen. Und wenn die VM-Erstellung fehlschlägt, können Sie Ihre eigenen Sysprep- oder waagent-Befehle verwenden.

Wenn Azure Image Builder erfolgreich ein benutzerdefiniertes Windows-Image erstellt, Sie mit dem Image einen virtuellen Computer erstellen und die Erstellung des virtuellen Computers dann fehlschlägt bzw. nicht erfolgreich durchgeführt wird, müssen Sie die Dokumentation zu Windows Server-Sysprep zu Rate ziehen oder eine Supportanfrage beim Supportteam für den Kundendienst für Windows Server-Sysprep eröffnen, um Unterstützung bei der Problembehandlung und Tipps zur ordnungsgemäßen Nutzung von Sysprep zu erhalten.

Sysprep-Standardbefehl

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

deprovision-Standardbefehl für 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

Überschreiben der Befehle

Verwenden Sie zum Überschreiben der Befehle die Shell- oder PowerShell-Skriptbereitstellungen, um die Befehlsdateien mit dem gleichen Dateinamen zu erstellen, und fügen Sie sie in die richtigen Verzeichnisse ein:

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

Diese Befehle werden von Image Builder gelesen und in den AIB-Protokollen (customization.log) dokumentiert. Auf der Seite zur Problembehandlung erfahren Sie, wie Sie Protokolle erfassen.

Eigenschaften: errorHandling

Mit der Eigenschaft errorHandling können Sie konfigurieren, wie Fehler bei der Imageerstellung behandelt werden.

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

Mit der Eigenschaft errorHandling können Sie konfigurieren, wie Fehler bei der Imageerstellung behandelt werden. Sie verfügt über zwei Eigenschaften:

  • onCustomizerError: Gibt die auszuführende Aktion an, wenn in der Anpassungsphase der Imageerstellung ein Fehler auftritt.
  • onValidationError: Gibt die auszuführende Aktion an, wenn bei der Prüfung der Imagevorlage ein Fehler auftritt.

Die Eigenschaft errorHandling hat auch zwei mögliche Werte für die Behandlung von Fehlern bei der Imageerstellung:

  • cleanup: Stellt sicher, dass temporäre Ressourcen, die von Packer erstellt wurden, bereinigt werden, auch wenn Packer oder eine der Anpassungen/Prüfungen einen Fehler feststellt. Dadurch bleibt die Abwärtskompatibilität mit vorhandenem Verhalten erhalten.
  • abort: Wenn Packer einen Fehler feststellt, überspringt der Azure VM Image Builder (AIB)-Dienst die Bereinigung der temporären Ressourcen. Als Besitzer der AIB-Vorlage sind Sie dafür verantwortlich, diese Ressourcen aus Ihrem Abonnement zu bereinigen. Diese Ressourcen können nützliche Informationen umfassen, z. B. Protokolle und Dateien, die auf einer temporären VM zurückgelassen werden, was bei der Untersuchung des von Packer festgestellten Fehlers hilfreich sein kann.

Eigenschaften: distribute

Azure Image Builder unterstützt drei Verteilungsziele:

  • ManagedImage: Verwaltetes Image.
  • sharedImage - Azure Compute Gallery.
  • VHD: VHD in einem Speicherkonto

Sie können ein Image in ein und derselben Konfiguration an beide Zieltypen verteilen.

Hinweis

Der standardmäßige AIB-Sysprep-Befehl enthält „/mode:vm“ nicht. Diese Eigenschaft ist jedoch möglicherweise erforderlich, wenn Sie Images erstellen, in denen die HyperV-Rolle installiert ist. Wenn Sie dieses Befehlsargument hinzufügen müssen, müssen Sie den Sysprep-Befehl überschreiben.

Da Sie mehrere Verteilungsziele verwenden können, verwaltet Image Builder für jedes Verteilungsziel einen Zustand, auf den durch Abfragen von runOutputName zugegriffen werden kann. runOutputName ist ein Objekt, das Sie nach der Verteilung abfragen können, um Informationen über die Verteilung abzurufen. Sie können beispielsweise den Speicherort der VHD oder die Regionen abfragen, in denen die Imageversion repliziert wurde. Dies ist eine Eigenschaft aller Verteilungsziele. runOutputName muss für jedes Verteilungsziel eindeutig sein. Das folgende Beispiel fragt eine Azure Compute Gallery-Distribution ab:

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=2023-07-01

Ausgabe:

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

Die Imageausgabe ist eine verwaltete Imageressource.

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

Verteilungseigenschaften:

  • Typ: ManagedImage
  • imageId: Die Ressourcen-ID des Zielimages. Das folgende Format wird erwartet: /subscriptions/<Abonnement-ID>/resourceGroups/<Ziel-Ressourcengruppenname>/providers/Microsoft.Compute/images/<Imagename>
  • location: der Speicherort des verwalteten Images.
  • runOutputName: eindeutiger Name zur Identifikation der Verteilung.
  • artifactTags: optionale vom Benutzer angegebene Schlüssel-Wert-Tags.

Hinweis

Die Zielressourcengruppe muss vorhanden sein. Wenn Sie ein Image in einer anderen Region verteilt werden soll, steigt auch die erforderliche Bereitstellungszeit.

Distribute: sharedImage

Die Azure Compute Gallery ist ein neuer Dienst für die Verwaltung von Images, mit dem die Imagereplikation in Regionen, die Versionskontrolle und die Freigabe benutzerdefinierter Images verwaltet werden können. Azure Image Builder unterstützt die Verteilung mit diesem Dienst. Sie können Images also in Regionen verteilen, die von der Azure Compute Gallery unterstützt werden.

Eine Azure Compute Gallery besteht aus:

  • Katalog: Container für mehrere Images. Ein Katalog wird in einer Region bereitgestellt.
  • Imagedefinitionen: Eine konzeptionelle Gruppierung von Images.
  • Imageversionen: Ein Imagetyp für die Bereitstellung einer VM oder Skalierungsgruppe. Imageversionen können in andere Regionen repliziert werden, in denen VMs bereitgestellt werden müssen.

Bevor Sie ein Image an den Katalog verteilen können, müssen Sie einen Katalog und eine Imagedefinition erstellen. Informationen dazu finden Sie unter Erstellen eines Katalogs.

Hinweis

Die Imageversions-ID muss sich von allen Imageversionen unterscheiden, die in der vorhandenen Azure Compute Gallery-Instanz enthalten sind.

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

Der folgende JSON-Code ist ein Beispiel für die Verwendung des Felds replicationRegions zum Verteilen an eine Azure Compute Gallery.

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

Hinweis

replicationRegions ist für Katalogverteilungen veraltet, da targetRegions die aktualisierte Eigenschaft ist. Weitere Informationen finden Sie unter targetRegions.

Distribute: targetRegions

Der folgende JSON-Code ist ein Beispiel für die Verwendung des Felds „targetRegions“ zum Verteilen an eine Azure Compute Gallery.

"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"
             }
          ]
       },
    ]

Verteilen von Eigenschaften für Kataloge:

  • type: sharedImage

  • galleryImageId: ID der Azure Compute Gallery. Diese Eigenschaft kann in zwei Formaten angegeben werden:

    • Automatische Versionsverwaltung: Image Builder generiert eine monotone Versionsnummer für Sie. Diese Eigenschaft ist nützlich, wenn Sie weiterhin Images aus derselben Vorlage neu erstellen möchten: Das Format ist: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Explizite Versionsverwaltung: Sie können die Versionsnummer übergeben, die von Image Builder verwendet werden soll. Das Format ist /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>

  • runOutputName: eindeutiger Name zur Identifikation der Verteilung.

  • artifactTags: Optionale, vom Benutzer angegebene Schlüssel-Wert-Tags.

  • replicationRegions: Array von Regionen für die Replikation. In einer der hier enthaltenen Regionen muss der Katalog bereitgestellt werden. Das Hinzufügen von Regionen bedeutet eine Erhöhung der Buildzeit, da der Build erst abgeschlossen wird, wenn die Replikation fertig ist. Dieses Feld ist ab API-Version 2022-07-01 veraltet. Verwenden Sie targetRegions beim Verteilen eines „SharedImage“-Typs.

  • targetRegions: Array von Regionen für die Replikation. Es wurde als Teil der API 2022-07-01 neu eingeführt und gilt nur für den Verteilungstyp SharedImage.

  • excludeFromLatest (optional): Hiermit können Sie die von Ihnen erstellte Imageversion markieren, die nicht als neueste Version in der Katalogdefinition verwendet wird. Der Standardwert ist FALSE.

  • storageAccountType (optional): AIB unterstützt die Angabe dieser Speichertypen für die Imageversion, die erstellt werden soll:

    • „Standard_LRS“
    • „Standard_ZRS“,“

Hinweis

Wenn sich die Imagevorlage und die referenzierte image definition nicht am gleichen Standort befinden, wird zusätzliche Zeit zum Erstellen von Images angezeigt. Image Builder verfügt derzeit nicht über einen location-Parameter für die Imageversionsressource, daher nehmen wir ihn von seiner übergeordneten image definition. Wenn sich z. B. eine Imagedefinition in westus befindet und Sie möchten, dass die Imageversion nach eastus repliziert wird, wird ein Blob nach westus kopiert. Daraus wird eine Imageversionsressource in westus erstellt und dann nach eastus repliziert. Stellen Sie zur Vermeidung der zusätzlichen Replikationszeit sicher, dass sich image definition und die Imagevorlage am selben Standort befinden.

Versionskontrolle

Die Eigenschaft versioning gilt nur für den Verteilungstyp sharedImage. Es handelt sich um eine Enumeration mit zwei möglichen Werten:

  • latest: Neues, strikt ansteigendes Schema pro Entwurf
  • source: Schema basierend auf der Versionsnummer des Quellimages.

Das Standardschema für die Versionsnummerierung ist latest. Das neueste Schema verfügt über die zusätzliche Eigenschaft „major“, die die Hauptversion angibt, unter der die neueste Version generiert werden soll.

Hinweis

Die vorhandene Versionsgenerierungslogik für den Verteilungstyp sharedImage ist veraltet. Es werden zwei neue Optionen bereitgestellt: monoton ansteigende Versionen, die immer die neueste Version in einem Katalog sind, und Versionen, die basierend auf der Versionsnummer des Quellimages generiert werden. Die Enumeration, die das Versionsgenerierungsschema angibt, ermöglicht mithilfe von zusätzlichen Versionsgenerierungsschemas eine zukünftige Erweiterung.

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

Versionsverwaltungseigenschaften:

  • scheme: Generiert eine neue Versionsnummer für die Verteilung. Als mögliche Werte stehen Latest oder Source zur Verfügung.
  • major: Gibt die Hauptversion an, unter der die neueste Version generiert werden soll. Nur anwendbar, wenn das scheme auf Latest festgelegt wurde. Beispielsweise in einem Katalog mit den folgenden veröffentlichten Versionen: 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
    • Wenn „major“ nicht oder auf 2 festgelegt ist, generiert das Schema Latest Version 2.1.1
    • Wenn „major“ auf 1 festgelegt ist, generiert das Schema „latest“ Version 1.2.1
    • Wenn „major“ auf 0 festgelegt ist, generiert das Schema „latest“ Version 0.1.3

Distribute: VHD

Sie können die Ausgabe in einer VHD erstellen. Anschließend können Sie die VHD kopieren und für die Veröffentlichung im Azure Marketplace oder mit Azure Stack verwenden.

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

Betriebssystemunterstützung: Windows und Linux

VHD-Verteilungsparameter:

  • type: VHD
  • runOutputName: eindeutiger Name zur Identifikation der Verteilung.
  • tags: optionale vom Benutzer angegebene Schlüssel-Wert-Paar-Tags.

Azure Image Builder ermöglicht das Festlegen von Speicherkontostandorten durch Benutzer nicht, Sie können jedoch den Status von runOutputs abfragen, um den Standort abzurufen.

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

Hinweis

Kopieren Sie die VHD so bald wie möglich an einen anderen Speicherort, sobald diese erstellt wurde. Die VHD wird in einem Speicherkonto in der temporären Ressourcengruppe gespeichert, die erstellt wird, wenn die Imagevorlage an den Azure Image Builder-Dienst übermittelt wird. Wenn Sie die Imagevorlage löschen, wird auch die VHD gelöscht.

Der folgende JSON-Code verteilt das Image als VHD an ein benutzerdefiniertes Speicherkonto.

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

VHD-Verteilungseigenschaften:

uri: Optionaler Azure Storage-URI für das verteilte VHD-Blob. Lassen Sie diese Option weg, um den Standardwert (leere Zeichenfolge) zu verwenden. In diesem Fall würde die VHD im Speicherkonto in der Stagingressourcengruppe veröffentlicht werden.

Eigenschaften: optimize

Die optimize-Eigenschaft kann aktiviert werden, wenn ein VM-Image erstellt wird. Sie ermöglicht die VM-Optimierung, damit Images schneller erstellt werden können.

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: Eine Konfiguration im Zusammenhang mit dem Startprozess des virtuellen Computers (VM), die zur Steuerung von Optimierungen verwendet wird, die die Startzeit oder andere Leistungsaspekte verbessern können.
  • state: Der Status des Features „Startoptimierung“ innerhalb von vmBoot. Der Wert Enabled zeigt an, dass das Feature aktiviert ist, um die Erstellungszeit des Images zu verbessern.

Weitere Informationen finden Sie in der VM-Optimierung für Katalogimages mit dem Azure VM Image Builder.

Eigenschaften: source

Der Abschnitt source enthält Informationen über das Quellimage, das von Image Builder verwendet wird. Azure Image Builder unterstützt nur generalisierte Images als Quellimages, spezialisierte Images werden derzeit nicht unterstützt.

Die API erfordert einen SourceType, der die Quelle für die Imageerstellung definiert. Derzeit stehen die folgenden drei Typen zur Verfügung:

  • PlatformImage: gibt an, dass es sich beim Quellimage um ein Marketplace-Image handelt.
  • ManagedImage: Wird verwendet, wenn mit einem normalen verwalteten Image begonnen wird.
  • SharedImageVersion: Wird verwendet, wenn Sie eine Imageversion aus einer Azure Compute Gallery als Quellimage verwenden.

Hinweis

Wenn Sie vorhandene benutzerdefinierte Windows-Images verwenden, können Sie den Sysprep-Befehl bis zu drei Mal für ein einzelnes Windows 7- oder Windows Server 2008 R2-Image oder 1001 Mal für ein einzelnes Windows-Image für höhere Versionen ausführen. Weitere Informationen finden Sie in der sysprep-Dokumentation.

PlatformImage-Quelle

Azure Image Builder unterstützt Windows Server- und -Client- sowie Azure Marketplace Linux-Images. Die vollständige Liste finden Sie unter Weitere Informationen zu Azure Image Builder.

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

Die Eigenschaften hier entsprechen denen, die zum Erstellen der VM verwendet wurden. Führen Sie den folgenden Befehl in der Azure CLI aus, um die Eigenschaften abzurufen:

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

Sie können latest in der Version verwenden. Die Version wird bei der Imageerstellung und nicht beim Übermitteln der Vorlage ausgewertet. Wenn Sie diese Funktion mit dem Azure Compute Gallery-Ziel verwenden, können Sie die erneute Übermittlung der Vorlage vermeiden und die Imageerstellung in Intervallen erneut ausführen, sodass Ihre Images aus den neuesten Images neu erstellt werden.

Unterstützung für Informationen zum Marketplaceplan

Sie können auch Planinformationen angeben. Beispiel:

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

ManagedImage-Quelle

Hiermit wird ein vorhandenes verwaltetes Image einer generalisierten VHD oder VM als Quellimage festgelegt.

Hinweis

Das verwaltete Quellimage muss ein Image eines unterstützten Betriebssystems sein und sich im selben Abonnement und in derselben Region wie Ihre Azure Image Builder-Vorlage befinden.

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

imageId sollte dem ResourceId-Wert des verwalteten Images entsprechen. Verwenden Sie den Befehl az image list, um die verfügbaren Images aufzulisten.

SharedImageVersion-Quelle

Hiermit wird eine vorhandene Imageversion aus einer Azure Compute Gallery als Quellimage festgelegt.

Hinweis

Die Version des freigegebenen Quellimages muss von einem unterstützten Betriebssystem stammen, und die Imageversion muss sich in derselben Region wie Ihre Azure Image Builder-Vorlage befinden. Replizieren Sie andernfalls die Imageversion in die Region der Image Builder-Vorlage.

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId: ARM-Vorlagenressourcen-ID der Imageversion. Wenn der Imageversionsname „latest“ lautet, wird die Version ausgewertet, wenn der Imagebuild stattfindet. Die imageVersionId sollte der ResourceId der Imageversion entsprechen. Verwenden Sie den Befehl az sig image-version list, um die Imageversionen aufzulisten.

Der folgende JSON-Code legt das Quellimage als ein in einem direkt freigegebenen Katalog gespeichertes Image fest.

Hinweis

Der direkt freigegebene Katalog ist derzeit in der Vorschau verfügbar.

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

Der folgende JSON-Code legt das Quellimage als neueste Imageversion für ein in einer Azure Compute Gallery-Instanz gespeichertes Image fest.

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

SharedImageVersion-Eigenschaften:

imageVersionId: ARM-Vorlagenressourcen-ID der Imageversion. Wenn der Imageversionsname „latest“ lautet, wird die Version ausgewertet, wenn der Imagebuild stattfindet.

Eigenschaften: stagingResourceGroup

Die Eigenschaft stagingResourceGroup enthält Informationen zur Stagingressourcengruppe, die der Image Builder-Dienst für die Verwendung während des Imagebuildprozesses erstellt. stagingResourceGroup ist eine optionale Eigenschaft für alle Personen, die während des ImageBuild-Prozesses mehr Kontrolle über die Ressourcengruppe wünschen, die von Image Builder erstellt wird. Sie können Ihre eigene Ressourcengruppe erstellen und im Abschnitt stagingResourceGroup angeben oder sie vom Image Builder in Ihrem Auftrag erstellen lassen.

Wichtig

Die angegebene Stagingressourcengruppe muss folgende Kriterien erfüllen: sie darf nicht mit einer anderen Imagevorlage verknüpft sein, sie muss leer sein (darf keine Ressourcen enthalten), und sie muss sich in derselben Region wie die Imagevorlage befinden. Außerdem muss der Identität, die der Azure Image Builder-Imagevorlagenressource zugewiesen ist, entweder die RBAC-Rolle „Mitwirkender“ oder „Besitzer“ zugewiesen sein.

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

Szenarien für die Vorlagenerstellung

  • Die Eigenschaft stagingResourceGroup wird leer gelassen

    Wenn die Eigenschaft stagingResourceGroup nicht oder mit einer leeren Zeichenfolge angegeben wird, erstellt der Image Builder-Dienst eine Stagingressourcengruppe mit der Standardnamenskonvention „IT_***“. Auf die Stagingressourcengruppe werden die folgenden Standardtags angewendet: createdBy, imageTemplateName, imageTemplateResourceGroupName. Außerdem wird auf die Identität, die der Azure Image Builder-Vorlagenressource zugewiesen ist, die Standard-RBAC „Mitwirkender“ angewendet.

  • Die Eigenschaft stagingResourceGroup wird mit einer vorhandenen Ressourcengruppe angegeben

    Wenn die Eigenschaft stagingResourceGroup mit einer Ressourcengruppe angegeben wird, die vorhanden ist, überprüft der Image Builder-Dienst, ob die Ressourcengruppe nicht mit einer anderen Imagevorlage verknüpft ist, ob sie leer ist (keine Ressourcen enthalten), ob sie sich in derselben Region wie die Imagevorlage befindet und ob auf die Identität, die der Azure Image Builder-Imagevorlagenressource zugewiesen ist, die RBAC-Rolle „Mitwirkender“ oder „Besitzer“ angewendet wurde. Wenn eine der oben genannten Anforderungen nicht erfüllt ist, wird ein Fehler ausgelöst. Der Stagingressourcengruppe werden die folgenden Tags hinzugefügt: usedBy, imageTemplateName, imageTemplateResourceGroupName. Bereits vorhandene Tags werden nicht gelöscht.

Wichtig

Wenn Sie versuchen, dem Azure Image Builder-Dienst mit einem Windows-Quellimage eine bereits vorhandene Ressourcengruppe und ein VNet zuzuweisen, müssen Sie der Ressourcengruppe für den Dienstprinzipal, der der Erstanbieter-App von Azure Image Builder entspricht, die Rolle „Mitwirkender“ zuweisen. Den CLI-Befehl und die Portalanweisungen zum Zuweisen der Rolle „Mitwirkender“ zur Ressourcengruppe finden Sie in der folgenden Dokumentation: Problembehandlung VM Azure Image Builder: Autorisierungsfehler beim Erstellen eines Datenträgers.

  • Die Eigenschaft stagingResourceGroup wird mit einer nicht vorhandenen Ressourcengruppe angegeben

    Wenn die Eigenschaft stagingResourceGroup mit einer nicht vorhandenen Ressourcengruppe angegeben wird, erstellt der Image Builder-Dienst eine Stagingressourcengruppe mit dem Namen, der in der Eigenschaft stagingResourceGroup angegeben ist. Es tritt ein Fehler auf, wenn der angegebene Name nicht den Azure-Benennungsanforderungen für Ressourcengruppen entspricht. Auf die Stagingressourcengruppe werden die folgenden Standardtags angewendet: createdBy, imageTemplateName, imageTemplateResourceGroupName. Standardmäßig wird auf die Identität, die der Azure Image Builder-Imagevorlagenressource zugewiesen ist, die RBAC-Rolle „Mitwirkender“ in der Ressourcengruppe angewendet.

Löschung von Vorlagen

Jede vom Image Builder-Dienst erstellte Stagingressourcengruppe wird gelöscht, nachdem die Imagevorlage gelöscht wurde. Der Löschvorgang umfasst Stagingressourcengruppen, die in der Eigenschaft stagingResourceGroup angegeben wurden, aber vor dem Imagebuild nicht vorhanden waren.

Wenn Image Builder die Stagingressourcengruppe nicht erstellt hat, aber die Ressourcen innerhalb der Ressourcengruppe, werden diese Ressourcen gelöscht, nachdem die Imagevorlage gelöscht wurde, sofern der Image Builder-Dienst über die entsprechenden Berechtigungen oder Rollen verfügt, die zum Löschen von Ressourcen erforderlich sind.

Eigenschaften: validate

Sie können die validate-Eigenschaft verwenden, um Plattformimages und alle von Ihnen erstellten angepassten Images zu überprüfen, unabhängig davon, ob Sie Azure Image Builder zum Erstellen verwendet haben.

Azure Image Builder unterstützt einen Modus „Nur Quellüberprüfung“, der mithilfe der Eigenschaft sourceValidationOnly festgelegt werden kann. Wenn die Eigenschaft sourceValidationOnly auf TRUE festgelegt ist, wird das im Abschnitt source angegebene Image direkt überprüft. Es wird kein separater Build ausgeführt, um ein angepasstes Image zu generieren und dann zu überprüfen.

Die Eigenschaft inVMValidations nimmt eine Liste von Validierungselementen an, die für das Image ausgeführt werden. Azure Image Builder unterstützt File-, PowerShell- und Shell-Validierungselemente.

Die Eigenschaft continueDistributeOnFailure steuert, ob die Ausgabeimages auch bei Überprüfungsfehlern verteilt werden. Wenn die Überprüfung fehlschlägt und diese Eigenschaft auf FALSE festgelegt ist, werden die Ausgabeimages nicht verteilt. Wenn die Überprüfung fehlschlägt und diese Eigenschaft auf TRUE festgelegt ist, werden die Ausgabeimages trotzdem verteilt. Verwenden Sie diese Option umsichtig, da sie dazu führen kann, dass fehlerhafte Images zur Verwendung verteilt werden. In beiden Fällen (TRUE oder FALSE) wird die End-to-End-Imageausführung bei einem Überprüfungsfehler als fehlgeschlagen gemeldet. Diese Eigenschaft hat keine Auswirkung darauf, ob die Überprüfung erfolgreich ist oder nicht.

Folgendes ist bei Verwendung von validate zu beachten:

  • Sie können mehrere Validierungselemente verwenden.
  • Validierungselemente werden nach der in der Vorlage festgelegten Reihenfolge ausgeführt.
  • Wenn bei einem Validierungselement ein Fehler auftritt, gilt die gesamte Validierungskomponente als fehlgeschlagen, und es wird ein Fehler zurückgegeben.
  • Es wird empfohlen, dass Sie das Skript gründlich testen, bevor Sie es in einer Vorlage verwenden. Das Debuggen des Skripts ist in Ihrer eigenen VM einfacher.
  • Fügen Sie in die Skripts keine vertraulichen Daten ein.
  • Die Speicherorte für die Skripts müssen öffentlich zugänglich sein, es sei denn, Sie verwenden die verwaltete Dienstidentität.

Verwenden der validate-Eigenschaft zum Überprüfen von Windows-Images:

{
   "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-Eigenschaften:

  • type: PowerShell

  • name: der Name des Validierungselements

  • scriptUri: der URI der PowerShell-Skriptdatei

  • inline: Array auszuführender Befehle, durch Kommas getrennt.

  • validExitCodes: Optional. Gültige Codes, die vom Skript-/Inline-Befehl zurückgegeben werden können, um die Meldung eines Fehlers im Skript-/Inline-Befehl zu vermeiden.

  • runElevated: Optionaler boolescher Wert, Unterstützung für das Ausführen von Befehlen und Skripts mit erhöhten Berechtigungen.

  • sha256Checksum: Der Wert der SHA256-Prüfsumme der Datei, den Sie lokal generieren. Anschließend überprüft Image Builder die Prüfsumme und validiert sie.

    So generieren Sie sha256Checksum mithilfe des PowerShell-Befehls Get-Hash unter Windows

Verwenden der validate-Eigenschaft zum Überprüfen von Linux-Images:

{
  "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-Eigenschaften:

  • type: Shell oder Datei, die als Überprüfungstyp angegeben ist, der ausgeführt werden soll.

  • name: der Name des Validierungselements

  • scriptUri: der URI der Skriptdatei

  • inline: Array auszuführender Befehle, durch Kommas getrennt.

  • sha256Checksum: Der Wert der SHA256-Prüfsumme der Datei, den Sie lokal generieren. Anschließend überprüft Image Builder die Prüfsumme und validiert sie.

    Um sha256Checksum mithilfe eines Terminals unter Mac/Linux zu generieren, führen Sie Folgendes aus: sha256sum <fileName>

  • destination: Ziel der Datei.

  • sha256Checksum: Gibt die SHA256-Prüfsumme der Datei an.

  • sourceUri: Der Quell-URI der Datei.

Eigenschaften: vmProfile

vmSize (optional)

Image Builder verwendet eine SKU-Standardgröße von Standard_D1_v2 für Gen1-Images und Standard_D2ds_v4 für Gen2-Images. Die Generierung wird durch das Image definiert, das Sie in der sourceangeben. Sie können vmSize aus folgenden Gründen außer Kraft setzen:

  • Durchführen von Anpassungen, die mehr Arbeitsspeicher, CPU und Verarbeitung großer Dateien (GBs) erfordern.
  • Wenn Sie Windows-Builds ausführen, sollten Sie „Standard_D2_v2“ oder eine gleichmäßige VM-Größe verwenden.
  • Forderung nach VM-Isolation.
  • Passen Sie ein Image an, das bestimmte Hardware erfordert. Für eine GPU-VM benötigen Sie beispielsweise eine GPU-VM-Größe.
  • Fordern Sie End-to-End-Verschlüsselung im Ruhespeicher des virtuellen Buildcomputers an. Sie müssen die Größe des unterstützenden virtuellen Buildcomputers angeben, für den keine lokalen temporären Datenträger verwendet werden.

osDiskSizeGB

Standardmäßig ändert Image Builder die Größe des Images nicht. Es wird die Größe des Quellimages verwendet. Sie können optional nur die Größe des Betriebssystemdatenträgers erhöhen (Windows und Linux). Der Wert „0“ bedeutet, dass die Größe der Größe des Quellimages entspricht. Die Größe des Betriebssystemdatenträgers kann nicht auf einen Wert reduziert werden, der niedriger ist als die Größe des Quellimages.

{
  "osDiskSizeGB": 100
}

vnetConfig (optional)

Wenn Sie keine VNet-Eigenschaften angeben, erstellt Image Builder ein eigenes VNet, eine öffentliche IP-Adresse und eine Netzwerksicherheitsgruppe (NSG). Die öffentliche IP-Adresse wird für den Dienst verwendet, um mit der Build-VM zu kommunizieren. Wenn Sie jedoch keine öffentliche IP-Adresse verwenden möchten oder Image Builder Zugriff auf Ihre vorhandenen VNet-Ressourcen wie Konfigurationsserver (DSC, Chef, Puppet, Ansible) oder Dateifreigaben besitzen soll, können Sie ein VNet angeben. Lesen Sie die Netzwerkdokumentation, um weitere Informationen zu erhalten.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
  "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
  "proxyVmSize": "<vmSize>"
}

subnetId

Ressourcen-ID eines bereits vorhandenen Subnetzes, in dem die Build-VM und die Validierungs-VM bereitgestellt werden.

containerInstanceSubnetId (optional)

Ressourcen-ID eines bereits vorhandenen Subnetzes, auf dem Azure Container Instance (ACI) für isolierte Builds bereitgestellt wird. Wenn dieses Feld nicht angegeben ist, wird ein temporäres virtuelles Netzwerk zusammen mit Subnetzen und Netzwerksicherheitsgruppen zusätzlich zu anderen Netzwerkressourcen (Privater Endpunkt, Privater LinkDienst, Azure Load Balancer und der Proxy-VM) in der Stagingressourcengruppe bereitgestellt, um die Kommunikation zwischen der ACI und der Build-VM zu ermöglichen.

[Diese Eigenschaft ist nur in API-Versionen oder neueren Versionen 2024-02-01 verfügbar, obwohl vorhandene Vorlagen, die mit früheren API-Versionen erstellt wurden, aktualisiert werden können, um diese Eigenschaft anzugeben.]

Dieses Feld kann nur angegeben werden, wenn subnetId es auch angegeben ist und die folgenden Anforderungen erfüllen muss:

  • Dieses Subnetz muss sich im gleichen virtuellen Netzwerk wie das in subnetId.
  • Dieses Subnetz darf nicht dasselbe Subnetz sein wie das in subnetId.
  • Dieses Subnetz muss an den ACI-Dienst delegiert werden, damit es zum Bereitstellen von ACI-Ressourcen verwendet werden kann. Weitere Informationen zur Subnetzdelegierung für Azure-Dienste finden Sie hier. Hier finden Sie ACI-spezifische Subnetzdelegierungsinformationen.
  • Dieses Subnetz muss ausgehenden Zugriff auf das Internet und auf das in subnetIdder Datei angegebene Subnetz zulassen. Diese Zugriffe sind erforderlich, damit die ACI bereitgestellt werden kann und mit der Build-VM kommunizieren kann, um Anpassungen/Überprüfungen durchzuführen. Am anderen Ende muss das angegebene subnetId Subnetz den eingehenden Zugriff von diesem Subnetz zulassen. Im Allgemeinen ermöglichen standardsicherheitsregeln von Azure Network Security Groups (NSGs) diese Zugriffe. Wenn Sie Ihren NSGs jedoch weitere Sicherheitsregeln hinzufügen, müssen die folgenden Zugriffsberechtigungen weiterhin zulässig sein:
    1. Ausgehender Zugriff vom subnetz, in dem folgendes containerInstanceSubnetId angegeben ist:
      1. Zum Internet am Port 443 (für die Bereitstellung des Containerimages).
      2. Zum Internet am Port 445 (für die Bereitstellung der Dateifreigabe aus Azure Storage).
      3. Zum subnetz, das in subnetId Port 22 (für ssh/Linux) und Port 5986 (für WinRM/Windows) angegeben ist (zum Herstellen einer Verbindung mit der Build-VM).
    2. Eingehender Zugriff auf das unter :subnetId
      1. To Port 22 (for ssh/Linux) and Port 5986 (for WinRM/Windows) from the subnet specified in containerInstanceSubnetId (for ACI to connect to the build VM).
  • Die Vorlagenidentität muss über die Berechtigung zum Ausführen der Aktion "Microsoft.Network/virtualNetworks/subnets/join/action" im Bereich dieses Subnetzes verfügen. Weitere Informationen zu Azure-Berechtigungen für Netzwerke finden Sie hier.

proxyVmSize (optional)

Die Größe des virtuellen Proxycomputers, der zum Übergeben des Datenverkehrs an den virtuellen Buildcomputer und die Überprüfungs-VM verwendet wird. Dieses Feld darf nicht angegeben werden, wenn containerInstanceSubnetId angegeben wird, da in diesem Fall kein virtueller Proxycomputer bereitgestellt wird. Lassen Oder geben Sie leere Zeichenfolge an, um die Standardeinstellung zu verwenden (Standard_A1_v2).

Eigenschaften: autoRun

Mit der autoRun Eigenschaft können Sie steuern, ob der Erstellungsprozess für Bildvorlagen automatisch gestartet werden soll, wenn die Vorlage erstellt wird. Es handelt sich um eine Enumeration mit zwei möglichen Werten:

  • Aktiviert – Die automatische Ausführung ist aktiviert, sodass der Erstellungsprozess für Bildvorlagen automatisch gestartet wird, wenn die Vorlage erstellt wird.
  • Deaktiviert – Die automatische Ausführung ist deaktiviert, sodass Sie den Imagebuildprozess nach dem Erstellen der Vorlage manuell starten müssen.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Hinweis

Wenn Sie auf "Aktiviert" festgelegt habenautoRun, wird der Imagebuildprozess nach der Vorlagenerstellung einmal ausgeführt. Dadurch wird sichergestellt, dass der anfängliche Imagebuild nahtlos erfolgt. Es bietet jedoch keine konsistenten und fortlaufenden Imagebuilds. Konsistente und fortlaufende Imagebuilds, die ausgeführt werden, nachdem eine Imagevorlage aktualisiert wurde, finden Sie unter Verwenden von Azure Image Builder-Triggern zum Einrichten eines automatischen Imagebuilds.

Im Gegensatz dazu autoRunstellt die automatische Imageerstellung über die Azure Image Builder-Triggerressource sicher, dass Imagebuilds konsistent auftreten. Wenn Änderungen an der Vorlage vorgenommen werden, löst der Azure Image Builder-Dienst automatisch den Imagebuildprozess aus.

Wählen Sie autoRun nach der Vorlagenerstellung eine Auswahl für sofortige Bilder aus. Entscheiden Sie sich für die automatische Imageerstellung, wenn Sie eine fortlaufende Konsistenz in Imagebuilds benötigen. Berücksichtigen Sie Ihre spezifischen Anforderungen, und verwenden Sie die entsprechende Option basierend auf Ihrem Workflow.

Eigenschaften: managedResourceTags

Sie können die managedResourceTags Eigenschaft verwenden, um Tags auf die Ressourcen anzuwenden, die der Azure Image Builder-Dienst während des Imagebuilds in der Stagingressourcengruppe erstellt. Weitere Informationen zur Stagingressourcengruppe finden Sie in der Übersicht über den Azure Image Builder

"properties": {
		"managedResourceTags": {
			"tag1": "value1",
      			"tag2": "value2"
              }
}

Vorgänge für Imagevorlagen

Starten der Imageerstellung

Um einen Build zu starten, müssen Sie „Ausführen“ für die Imagevorlagenressource aufrufen. Beispiele für run-Befehle:

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

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

Abbrechen einer Imageerstellung

Wenn Sie eine Imageerstellung ausführen, die Ihrer Meinung nach fehlerhaft ist, auf Benutzereingaben wartet oder von der Sie glauben, dass sie nie erfolgreich abgeschlossen werden kann, können Sie die Erstellung abbrechen.

Der Build kann jederzeit abgebrochen werden. Wenn die Verteilungsphase begonnen hat, können Sie immer noch abbrechen, aber Sie müssen alle Images bereinigen, die möglicherweise nicht abgeschlossen sind. Der Abbruchbefehl wartet nicht auf den Abschluss des Abbruchs. Überwachen Sie lastrunstatus.runstate mithilfe dieser Statusbefehle auf den Fortschritt des Abbruchvorgangs.

Beispiele für cancel-Befehle:

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

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

Nächste Schritte

JSON-Beispieldateien für verschiedene Szenarios finden Sie im GitHub-Repository für Azure Image Builder.