Udostępnij przez

Tworzenie szablonu JSON szablonu usługi Azure Image Builder lub Bicep lub ARM

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets

Narzędzie Azure Image Builder używa pliku Bicep lub pliku szablonu JSON szablonu usługi ARM do przekazywania informacji do usługi Image Builder. W tym artykule omówimy sekcje plików, dzięki czemu możesz utworzyć własne. For latest API versions, see template reference. Aby zapoznać się z przykładami pełnych plików .json, zobacz GitHub narzędzia Azure Image Builder.

Podstawowy format to:

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

Follow all Best Practices while creating image templates.

API version

Wersja interfejsu API zmieni się wraz ze zmianą interfejsu API w miarę upływu czasu. Zobacz Co nowego w narzędziu Image Builder maszyny wirtualnej platformy Azure, aby zapoznać się ze wszystkimi ważnymi zmianami interfejsu API i aktualizacjami funkcji dla usługi Azure VM Image Builder.

Typ

Jest type to typ zasobu, który musi mieć wartość Microsoft.VirtualMachineImages/imageTemplates.

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

Location

Usługa Vm Image Builder jest dostępna w następujących regionach:

Note

Obrazy można nadal dystrybuować poza tymi regionami.

  • Wschodnie stany USA
  • Wschodnie stany USA 2
  • Zachodnio-środkowe stany USA
  • Zachodnie stany USA
  • Zachodnie stany USA 2
  • Zachodnie stany USA 3
  • Południowo-środkowe stany USA
  • Europa Północna
  • Europa Zachodnia
  • Azja Południowo-Wschodnia
  • Australia Południowo-Wschodnia
  • Australia Wschodnia
  • Południowe Zjednoczone Królestwo
  • Zachodnie Zjednoczone Królestwo
  • Brazylia Południowa
  • Kanada Środkowa
  • Indie Środkowe
  • Środkowe stany USA
  • Francja Środkowa
  • Niemcy Środkowo-Zachodnie
  • Japonia Wschodnia
  • Północno-środkowe stany USA
  • Norwegia Wschodnia
  • Szwajcaria Północna
  • Indie Zachodnie (Jio)
  • Północne Zjednoczone Emiraty Arabskie
  • Azja Wschodnia
  • Korea Środkowa
  • Północna Republika Południowej Afryki
  • Katar Środkowy
  • USGov Arizona (publiczna wersja zapoznawcza)
  • USGov Virginia (publiczna wersja zapoznawcza)
  • Chiny Północne 3 (publiczna wersja zapoznawcza)
  • Szwecja Środkowa
  • Polska Środkowa
  • Włochy Północne
  • Izrael Środkowy
  • Nowa Zelandia Północna
  • Taiwan Northwest

Important

Zarejestruj funkcję Microsoft.VirtualMachineImages/FairfaxPublicPreview , aby uzyskać dostęp do publicznej wersji zapoznawczej narzędzia Azure Image Builder w regionach platformy Azure Government (USGov Arizona i USGov Virginia).

Important

Zarejestruj funkcję Microsoft.VirtualMachineImages/MooncakePublicPreview , aby uzyskać dostęp do publicznej wersji zapoznawczej narzędzia Azure Image Builder w regionie Chiny Północne 3.

To access the Azure VM Image Builder public preview in the Azure Government regions (USGov Arizona and USGov Virginia), you must register the Microsoft.VirtualMachineImages/FairfaxPublicPreview feature. W tym celu uruchom następujące polecenie w programie PowerShell lub interfejsie wiersza polecenia platformy Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

To access the Azure VM Image Builder public preview in the China North 3 region, you must register the Microsoft.VirtualMachineImages/MooncakePublicPreview feature. W tym celu uruchom następujące polecenie w programie PowerShell lub interfejsie wiersza polecenia platformy Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Data residency

Usługa Azure VM Image Builder przechowuje dane klientów w regionach, w których obowiązują ścisłe reguły rezydencji danych. Jeśli awaria usługi dla regionów mających wymagania dotyczące rezydencji danych, musisz utworzyć pliki/szablony Bicep w innym regionie i lokalizacji geograficznej.

Zone redundancy

Dystrybucja obsługuje nadmiarowość strefy, wirtualne dyski twarde (VHD) są domyślnie dystrybuowane do konta magazynu strefowo nadmiarowego (ZRS), a wersja usługi Azure Compute Gallery (wcześniej znana jako Shared Image Gallery) będzie obsługiwać typ magazynu ZRS , jeśli zostanie określony.

Tags

Tagi to pary klucz/wartość, które można określić dla wygenerowanego obrazu.

Identity

Poniżej wyjaśniono dwa sposoby dodawania tożsamości przypisanych przez użytkownika.

Tożsamość przypisana przez użytkownika dla zasobu szablonu obrazu narzędzia Azure Image Builder

Wymagane — aby konstruktor obrazów miał uprawnienia do odczytu/zapisu obrazów i odczytywania skryptów z usługi Azure Storage, musisz utworzyć tożsamość przypisaną przez użytkownika platformy Azure, która ma uprawnienia do poszczególnych zasobów. Aby uzyskać szczegółowe informacje na temat działania uprawnień narzędzia Image Builder i odpowiednich kroków, zobacz Tworzenie obrazu i używanie tożsamości zarządzanej przypisanej przez użytkownika do uzyskiwania dostępu do plików na koncie usługi Azure Storage.

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

Tożsamość przypisana przez użytkownika usługi Image Builder:

  • Obsługuje tylko jedną tożsamość.
  • Nie obsługuje niestandardowych nazw domen.

Aby dowiedzieć się więcej, zobacz Co to są tożsamości zarządzane dla zasobów platformy Azure?. Aby uzyskać więcej informacji na temat wdrażania tej funkcji, zobacz Konfigurowanie tożsamości zarządzanych dla zasobów platformy Azure na maszynie wirtualnej platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

Tożsamość przypisana przez użytkownika dla maszyny wirtualnej kompilacji konstruktora obrazów

Ta właściwość jest dostępna tylko w wersjach interfejsu API lub nowszych 2021-10-01 wersjach.

Opcjonalnie — maszyna wirtualna kompilacji konstruktora obrazów utworzona przez usługę Image Builder w ramach subskrypcji służy do kompilowania i dostosowywania obrazu. Aby maszyna wirtualna kompilacji konstruktora obrazów miała uprawnienia do uwierzytelniania w innych usługach, takich jak usługa Azure Key Vault w ramach subskrypcji, musisz utworzyć co najmniej jedną tożsamość przypisaną przez użytkownika platformy Azure, która ma uprawnienia do poszczególnych zasobów. Narzędzie Azure Image Builder może następnie skojarzyć te tożsamości przypisane przez użytkownika z maszyną wirtualną kompilacji. Skrypty konfiguratora działające wewnątrz maszyny wirtualnej kompilacji mogą pobierać tokeny dla tych tożsamości i w razie potrzeby korzystać z innych zasobów platformy Azure. Należy pamiętać, że tożsamość przypisana przez użytkownika dla narzędzia Azure Image Builder musi mieć przypisanie roli "Operator tożsamości zarządzanej" dla wszystkich tożsamości przypisanych przez użytkownika dla narzędzia Azure Image Builder, aby móc skojarzyć je z maszyną wirtualną kompilacji.

Note

Należy pamiętać, że dla maszyny wirtualnej kompilacji konstruktora obrazów można określić wiele tożsamości, w tym tożsamość utworzoną dla zasobu szablonu obrazu. Domyślnie tożsamość utworzona dla zasobu szablonu obrazu nie zostanie automatycznie dodana do maszyny wirtualnej kompilacji.

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

Tożsamość przypisana przez użytkownika maszyny wirtualnej kompilacji konstruktora obrazów:

  • Obsługuje listę co najmniej jednej tożsamości zarządzanej przypisanej przez użytkownika do skonfigurowania na maszynie wirtualnej.
  • Obsługuje scenariusze między subskrypcjami (tożsamość utworzona w jednej subskrypcji podczas tworzenia szablonu obrazu w innej subskrypcji w ramach tej samej dzierżawy).
  • Nie obsługuje scenariuszy między dzierżawami (tożsamość utworzona w jednej dzierżawie podczas tworzenia szablonu obrazu w innej dzierżawie).

Aby dowiedzieć się więcej, zobacz:

Properties: buildTimeoutInMinutes

Maksymalny czas trwania oczekiwania podczas kompilowania szablonu obrazu (obejmuje wszystkie dostosowania, walidacje i dystrybucje).

Jeśli nie określisz właściwości lub ustawisz wartość 0, zostanie użyta wartość domyślna, czyli 240 minut lub cztery godziny. Wartość minimalna to 6 minut, a maksymalna wartość to 960 minut lub 16 godzin. Po osiągnięciu wartości limitu czasu (bez względu na to, czy kompilacja obrazu została ukończona), zostanie wyświetlony błąd podobny do następującego:

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

W przypadku systemu Windows nie zalecamy ustawienia buildTimeoutInMinutes poniżej 60 minut. If you find you're hitting the timeout, review the logs to see if the customization step is waiting on something like user input. Jeśli okaże się, że potrzebujesz więcej czasu na ukończenie dostosowań, zwiększ buildTimeoutInMinutes wartość. Ale nie ustawiaj go zbyt wysoko, ponieważ może być konieczne poczekanie na przekroczenie limitu czasu przed wyświetleniem błędu.

Properties: customize

Narzędzie Image Builder obsługuje wiele "konfiguratorów", które są funkcjami używanymi do dostosowywania obrazu, takich jak uruchamianie skryptów lub ponowne uruchamianie serwerów.

W przypadku korzystania z polecenia customize:

  • Można użyć wielu konfiguratorów.
  • Konfiguratory są wykonywane w kolejności określonej w szablonie.
  • Jeśli jeden konfigurator ulegnie awarii, cały składnik dostosowywania zakończy się niepowodzeniem i zgłosi błąd.
  • Dokładnie przetestuj skrypty przed użyciem ich w szablonie. Samodzielne debugowanie skryptów jest łatwiejsze.
  • Nie umieszczaj poufnych danych w skryptach. Polecenia wbudowane można wyświetlić w definicji szablonu obrazu. Jeśli masz poufne informacje (w tym hasła, token SAS, tokeny uwierzytelniania itp.), powinny zostać przeniesione do skryptów w usłudze Azure Storage, gdzie dostęp wymaga uwierzytelniania.
  • Lokalizacje skryptów muszą być publicznie dostępne, chyba że używasz tożsamości przypisanej przez użytkownika.

Sekcja customize jest tablicą. Obsługiwane typy konfiguratora to: File, PowerShell, Shell, WindowsRestart i 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"
  }
]

Shell customizer

Konfigurator Shell obsługuje uruchamianie skryptów powłoki w systemie Linux. The shell scripts must be publicly accessible or you must have configured an MSI for Image Builder to access them.

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

Customize properties:

  • type – Shell.

  • name - name for tracking the customization.

  • scriptUri - URI to the location of the file.

  • inline - array of shell commands, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this value locally, and then Image Builder will checksum and validate.

    Aby wygenerować sha256Checksum, użyj terminalu na komputerze Mac/Linux uruchom polecenie: sha256sum <fileName>

Note

Polecenia wbudowane są przechowywane jako część definicji szablonu obrazu, które można zobaczyć podczas zrzutu definicji obrazu. Jeśli masz poufne polecenia lub wartości (w tym hasła, token SAS, tokeny uwierzytelniania itp.), zalecane jest przeniesienie ich do skryptów i użycie tożsamości użytkownika do uwierzytelniania w usłudze Azure Storage.

Uprawnienia administratora

Prefiks poleceń z sudo poleceniem , aby uruchomić je z uprawnieniami administratora. Możesz dodać polecenia do skryptów lub użyć ich wbudowanych poleceń, na przykład:

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

Przykład skryptu używającego polecenia sudo, do którego można się odwołać przy użyciu identyfikatora scriptUri:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

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

Konfigurator ponownego uruchamiania systemu Windows

Konfigurator umożliwia ponowne uruchomienie maszyny wirtualnej z systemem Windows i oczekiwanie na powrót maszyny wirtualnej do trybu online. Ten WindowsRestart konfigurator umożliwia zainstalowanie oprogramowania wymagającego ponownego uruchomienia.

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

Customize properties:

  • Type: WindowsRestart.
  • restartCommand - Command to execute the restart (optional). Wartość domyślna to 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand – Command to check if restart succeeded (optional).
  • restartTimeout - Restart time out specified as a string of magnitude and unit. Na przykład 5m (5 minut) lub 2h (2 godziny). Wartość domyślna to: 5m.

Note

Nie ma konfiguratora ponownego uruchamiania systemu Linux.

PowerShell customizer

Konfigurator PowerShell obsługuje uruchamianie skryptów programu PowerShell i poleceń wbudowanych w systemie Windows, skrypty muszą być publicznie dostępne, aby usługa mogła uzyskać do nich dostęp.

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

Customize properties:

  • type – PowerShell.

  • scriptUri - URI to the location of the PowerShell script file.

  • inline – Inline commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command. Właściwość pozwala uniknąć zgłoszonego błędu skryptu/polecenia wbudowanego.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • runAsSystem - Optional, boolean, determines whether the PowerShell script should be run as the System user.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

File customizer

Konfigurator File umożliwia konstruktorowi obrazów pobranie pliku z repozytorium GitHub lub usługi Azure Storage. Konfigurator obsługuje zarówno systemy Linux, jak i Windows. Jeśli masz potok kompilacji obrazu, który opiera się na artefaktach kompilacji, możesz ustawić konfigurator pliku do pobrania z udziału kompilacji i przenieść artefakty do obrazu.

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

Właściwości konfiguratora plików:

  • sourceUri - an accessible storage endpoint, this endpoint can be GitHub or Azure storage. Można pobrać tylko jeden plik, a nie cały katalog. Jeśli musisz pobrać katalog, użyj skompresowanego pliku, a następnie usuń jego kompresję przy użyciu konfiguratorów powłoki lub programu PowerShell.

    Note

    Jeśli identyfikator sourceUri jest kontem usługi Azure Storage, niezależnie od tego, czy obiekt blob jest oznaczony jako publiczny, musisz przyznać uprawnienia tożsamości użytkownika zarządzanego w celu odczytu w obiekcie blob. See this example to set the storage permissions.

  • destination – the full destination path and file name. Wszystkie przywoływalne ścieżki i podkatalogi muszą istnieć, użyć konfiguratorów powłoki lub programu PowerShell, aby skonfigurować te ścieżki wcześniej. Możesz użyć konfiguratorów skryptów, aby utworzyć ścieżkę.

Ten konfigurator jest obsługiwany przez katalogi systemu Windows i ścieżki systemu Linux, ale istnieją pewne różnice:

  • Linux — jedyną ścieżką Konstruktor obrazów może zapisywać w pliku to /tmp.
  • Windows — brak ograniczenia ścieżki, ale ścieżka musi istnieć.

Jeśli wystąpił błąd podczas próby pobrania pliku lub umieścić go w określonym katalogu, dostosowywanie kroku zakończy się niepowodzeniem, a ten błąd będzie znajdować się w customization.log.

Note

Konfigurator plików jest odpowiedni tylko dla małych plików do pobrania, < 20 MB. W przypadku większych plików do pobrania użyj skryptu lub wbudowanego polecenia, a następnie użyj kodu do pobierania plików, takich jak, Linux wget lub curl, Windows, Invoke-WebRequest. W przypadku plików, które znajdują się w usłudze Azure Storage, upewnij się, że przypisano tożsamość z uprawnieniami do wyświetlania tego pliku na maszynie wirtualnej kompilacji, postępując zgodnie z dokumentacją tutaj: Tożsamość przypisana przez użytkownika dla maszyny wirtualnej kompilacji programu Image Builder. Każdy plik, który nie jest przechowywany na platformie Azure, musi być publicznie dostępny, aby program Azure Image Builder mógł go pobrać.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

Konfigurator aktualizacji systemu Windows

Konfigurator WindowsUpdate jest oparty na społeczności programu Windows Update Provisioner for Packer, który jest projektem open source obsługiwanym przez społeczność packer. Firma Microsoft testuje i weryfikuje dostawcę obsługi administracyjnej za pomocą usługi Image Builder oraz będzie obsługiwać badanie problemów i pracować nad rozwiązaniem problemów, jednak projekt open source nie jest oficjalnie obsługiwany przez firmę Microsoft. Aby uzyskać szczegółową dokumentację dotyczącą usługi Windows Update Provisioner i pomoc, zobacz repozytorium projektu.

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

Customizer properties:

  • type – WindowsUpdate.
  • searchCriteria - Optional, defines which type of updates are installed (like Recommended or Important), BrowseOnly=0 and IsInstalled=0 (Recommended) is the default.
  • filters – Optional, allows you to specify a filter to include or exclude updates.
  • updateLimit – Optional, defines how many updates can be installed, default 1000.

Note

Konfigurator usługi Windows Update może zakończyć się niepowodzeniem, jeśli istnieją zaległe ponowne uruchomienia systemu Windows lub instalacje aplikacji nadal działają, zazwyczaj ten błąd może zostać wyświetlony w customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. We strongly advise you consider adding in a Windows Restart, and/or allowing applications enough time to complete their installations using sleep or wait commands in the inline commands or scripts before running Windows Update.

Generalize

Domyślnie narzędzie Azure Image Builder uruchamia deprovision również kod na końcu każdej fazy dostosowywania obrazu, aby uogólnić obraz. Uogólnienie to proces, w którym obraz jest skonfigurowany, dzięki czemu można go ponownie użyć do tworzenia wielu maszyn wirtualnych. W przypadku maszyn wirtualnych z systemem Windows narzędzie Azure Image Builder używa narzędzia Sysprep. W przypadku systemu Linux narzędzie Azure Image Builder uruchamia polecenie waagent -deprovision.

Polecenia konstruktora obrazów umożliwiające uogólnienie mogą nie być odpowiednie dla każdej sytuacji, więc narzędzie Azure Image Builder umożliwia dostosowanie tego polecenia, jeśli jest to konieczne.

Jeśli migrujesz istniejące dostosowania i używasz różnych poleceń narzędzia Sysprep/waagent, możesz użyć ogólnych poleceń narzędzia Image Builder, a jeśli tworzenie maszyny wirtualnej zakończy się niepowodzeniem, użyj własnych poleceń narzędzia Sysprep lub waagent.

Jeśli narzędzie Azure Image Builder pomyślnie utworzy obraz niestandardowy systemu Windows i utworzysz z niego maszynę wirtualną, okaże się, że tworzenie maszyny wirtualnej kończy się niepowodzeniem lub nie zostanie ukończone pomyślnie, należy przejrzeć dokumentację narzędzia Sysprep systemu Windows Server lub zgłosić wniosek o pomoc techniczną z zespołem pomocy technicznej ds. obsługi systemu Windows Server Sysprep, który może rozwiązywać problemy i doradzać w sprawie poprawnego użycia narzędzia Sysprep.

Domyślne polecenie Sysprep

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

Domyślne polecenie anulowania aprowizacji systemu 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

Zastępowanie poleceń

Aby zastąpić polecenia, użyj aprowizatorów skryptów programu PowerShell lub powłoki, aby utworzyć pliki poleceń z dokładną nazwą pliku i umieścić je w odpowiednich katalogach:

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

Program Image Builder odczytuje te polecenia. Te polecenia są zapisywane w dziennikach usługi AIB. customization.log See troubleshooting on how to collect logs.

Properties: errorHandling

Właściwość errorHandling umożliwia skonfigurowanie sposobu obsługi błędów podczas tworzenia obrazu.

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

Właściwość errorHandling umożliwia skonfigurowanie sposobu obsługi błędów podczas tworzenia obrazu. Ma dwie właściwości:

  • onCustomizerError - Specifies the action to take when an error occurs during the customizer phase of image creation.
  • onValidationError - Specifies the action to take when an error occurs during validation of the image template.

Właściwość errorHandling ma również dwie możliwe wartości do obsługi błędów podczas tworzenia obrazu:

  • cleanup - Ensures that temporary resources created by Packer are cleaned up even if Packer or one of the customizations/validations encounters an error. Zapewnia to zgodność z poprzednimi wersjami z istniejącym zachowaniem.
  • abort - In case Packer encounters an error, the Azure Image Builder (AIB) service skips the clean up of temporary resources. Jako właściciel szablonu AIB odpowiadasz za wyczyszczenie tych zasobów z subskrypcji. Te zasoby mogą zawierać przydatne informacje, takie jak dzienniki i pliki pozostawione w tymczasowej maszynie wirtualnej, co może pomóc w badaniu błędu napotkanego przez program Packer.

Properties: distribute

Narzędzie Azure Image Builder obsługuje trzy cele dystrybucji:

  • ManagedImage - Managed image.
  • sharedImage - Azure Compute Gallery.
  • VHD - VHD in a storage account.

Obraz można dystrybuować do obu typów docelowych w tej samej konfiguracji.

Note

Domyślne polecenie AIB sysprep nie zawiera "/mode:vm", jednak ta właściwość może być wymagana podczas tworzenia obrazów, które będą miały zainstalowaną rolę HyperV. Jeśli musisz dodać ten argument polecenia, musisz zastąpić polecenie sysprep.

Ponieważ może istnieć więcej niż jeden element docelowy do dystrybucji, konstruktor obrazów zachowuje stan dla każdego obiektu docelowego dystrybucji, do którego można uzyskać dostęp, wysyłając zapytanie do obiektu runOutputName. Obiekt runOutputName jest obiektem, który można wysyłać zapytania po dystrybucji, aby uzyskać informacje o tej dystrybucji. Możesz na przykład wykonać zapytanie dotyczące lokalizacji dysku VHD lub regionów, w których wersja obrazu została zreplikowana do lub do wersji obrazu SIG. Jest to właściwość każdego obiektu docelowego dystrybucji. Element runOutputName musi być unikatowy dla każdego miejsca docelowego dystrybucji. Oto przykład wykonywania zapytań dotyczących dystrybucji galerii obliczeniowej platformy 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=2023-07-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

Dane wyjściowe obrazu to zasób obrazu zarządzanego.

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

Distribute properties:

  • type – ManagedImage
  • imageId – Resource ID of the destination image, expected format: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location - location of the managed image.
  • runOutputName – unique name for identifying the distribution.
  • artifactTags - Optional user specified key\value tags.

Note

Docelowa grupa zasobów musi istnieć. Jeśli chcesz, aby obraz był dystrybuowany do innego regionu, zwiększy to czas wdrożenia.

Distribute: sharedImage

Galeria zasobów obliczeniowych platformy Azure to nowa usługa zarządzania obrazami, która umożliwia zarządzanie replikacją regionów obrazów, przechowywanie wersji i udostępnianie obrazów niestandardowych. Narzędzie Azure Image Builder obsługuje dystrybucję za pomocą tej usługi, dzięki czemu można dystrybuować obrazy do regionów obsługiwanych przez galerie obliczeniowe platformy Azure.

Galeria zasobów obliczeniowych platformy Azure składa się z:

  • Gallery - Container for multiple images. Galeria jest wdrażana w jednym regionie.
  • Image definitions - a conceptual grouping for images.
  • Image versions - an image type used for deploying a VM or scale set. Wersje obrazów można replikować do innych regionów, w których należy wdrożyć maszyny wirtualne.

Zanim będzie można rozpowszechnić w galerii, musisz utworzyć galerię i definicję obrazu, zobacz Tworzenie galerii.

Note

Identyfikator wersji obrazu musi być odrębny lub inny niż wszystkie wersje obrazów, które znajdują się w istniejącej galerii obliczeniowej platformy Azure.

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

Poniższy kod JSON to przykład użycia replicationRegions pola do dystrybucji do galerii obliczeń platformy Azure.

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

Note

replicationRegions jest przestarzały w przypadku dystrybucji galerii, ponieważ targetRegions jest aktualizowana właściwość. For more information, see targetRegions.

Distribute: targetRegions

Poniższy kod JSON to przykład użycia pola targetRegions do dystrybucji do galerii obliczeń platformy 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"
             }
          ]
       },
    ]

Dystrybuuj właściwości dla galerii:

  • type - sharedImage

  • galleryImageId – ID of the Azure Compute Gallery, this property can be specified in two formats:

    • Automatyczne przechowywanie wersji — konstruktor obrazów generuje monotoniczny numer wersji. Ta właściwość jest przydatna, gdy chcesz zachować ponowne kompilowanie obrazów z tego samego szablonu: Format: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Jawne przechowywanie wersji — możesz przekazać numer wersji, który ma być używany przez konstruktora obrazów. Format to: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>

  • runOutputName – unique name for identifying the distribution.

  • artifactTags - optional user specified key\value tags.

  • replicationRegions - array of regions for replication. Jednym z regionów musi być region, w którym wdrożono galerię. Dodanie regionów oznacza wzrost czasu kompilacji, ponieważ kompilacja nie zostanie ukończona, dopóki replikacja nie zostanie ukończona. To pole jest przestarzałe w wersji 2022-07-01 interfejsu API, należy użyć targetRegions podczas dystrybucji typu "SharedImage".

  • targetRegions - an array of regions for replication. It's newly introduced as part of the 2022-07-01 API and applies only to the SharedImage type distribute.

  • excludeFromLatest (optional) - allows you to mark the image version you create not be used as the latest version in the gallery definition, the default is 'false'.

  • storageAccountType (optional) - AIB supports specifying these types of storage for the image version that is to be created:

    • "Standard_LRS"
    • "Standard_ZRS","

Note

Jeśli szablon obrazu i odwołania image definition nie znajdują się w tej samej lokalizacji, zobaczysz dodatkowy czas na utworzenie obrazów. Konstruktor obrazów obecnie nie ma location parametru dla zasobu wersji obrazu. Bierzemy go z nadrzędnego image definitionelementu . Jeśli na przykład definicja obrazu znajduje się i westus chcesz, aby wersja obrazu została zreplikowana do eastuselementu , obiekt blob zostanie skopiowany do westuselementu , zostanie utworzony zasób westus wersji obrazu, a następnie zreplikowany do eastuselementu . Aby uniknąć dodatkowego czasu replikacji, upewnij się, że image definition szablon i obrazu znajduje się w tej samej lokalizacji.

przechowywanie wersji

The versioning property is for the sharedImage distribute type only. Jest to wyliczenie z dwiema możliwymi wartościami:

  • latest - New strictly increasing schema per design
  • source - Schema based upon the version number of the source image.

Domyślny schemat numerowania wersji to latest. Najnowszy schemat ma dodatkową właściwość "główna", która określa wersję główną, w ramach której ma być generowana najnowsza wersja.

Note

Istniejąca logika generowania wersji dla sharedImage dystrybucji jest przestarzała. Dostępne są dwie nowe opcje: monotonicznie rosnące wersje, które są zawsze najnowszą wersją w galerii, i wersje generowane na podstawie numeru wersji obrazu źródłowego. Wyliczenie określające schemat generowania wersji umożliwia rozszerzenie w przyszłości przy użyciu dodatkowych schematów generowania wersji.

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

versioning properties:

  • scheme - Generate new version number for distribution. Latest lub Source są dwiema możliwymi wartościami.
  • major - Specifies the major version under which to generate the latest version. Dotyczy tylko wtedy, gdy scheme parametr ma wartość Latest. Na przykład w galerii z następującymi wersjami opublikowanymi: 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
    • W przypadku ustawienia głównego nie ustawiono wartości 2 Latest lub głównej schemat generuje wersję 2.1.1
    • W przypadku ustawienia głównego na 1 schemat Najnowszy generuje wersję 1.2.1
    • W przypadku ustawienia głównego na wartość 0 schemat Najnowszy generuje wersję 0.1.3

Distribute: VHD

Dane wyjściowe można uzyskać do wirtualnego dysku twardego. Następnie możesz skopiować dysk VHD i użyć go do opublikowania w usłudze Azure MarketPlace lub użyć go w usłudze Azure Stack.

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

Obsługa systemu operacyjnego: Windows i Linux

Dystrybuowanie parametrów wirtualnego dysku twardego:

  • type - VHD.
  • runOutputName – unique name for identifying the distribution.
  • tags - Optional user specified key value pair tags.

Narzędzie Azure Image Builder nie zezwala użytkownikowi na określenie lokalizacji konta magazynu, ale możesz wykonać zapytanie o stan runOutputs , aby uzyskać lokalizację.

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

Note

Po utworzeniu wirtualnego dysku twardego skopiuj go do innej lokalizacji tak szybko, jak to możliwe. Wirtualny dysk twardy jest przechowywany na koncie magazynu w tymczasowej grupie zasobów utworzonej podczas przesyłania szablonu obrazu do usługi Azure Image Builder. Jeśli usuniesz szablon obrazu, utracisz dysk VHD.

Poniższy kod JSON dystrybuuje obraz jako wirtualny dysk twardy do niestandardowego konta magazynu.

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

Właściwości dystrybucji dysku VHD:

uri - Optional Azure Storage URI for the distributed VHD blob. Pomiń użycie domyślnego (pustego ciągu), w którym przypadku dysk VHD zostanie opublikowany na koncie magazynu w przejściowej grupie zasobów.

Properties: optimize

Właściwość optimize można włączyć podczas tworzenia obrazu maszyny wirtualnej i umożliwia optymalizację maszyny wirtualnej w celu poprawy czasu tworzenia obrazu.

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: A configuration related to the booting process of the virtual machine (VM), used to control optimizations that can improve boot time or other performance aspects.
  • state: stan funkcji optymalizacji rozruchu w programie vmBootz wartością Enabled wskazującą, że funkcja jest włączona, aby poprawić czas tworzenia obrazu.

Aby dowiedzieć się więcej, zobacz Optymalizacja maszyn wirtualnych dla obrazów galerii za pomocą narzędzia Azure VM Image Builder.

Properties: source

Sekcja source zawiera informacje o obrazie źródłowym, który będzie używany przez konstruktora obrazów. Narzędzie Azure Image Builder obsługuje tylko uogólnione obrazy jako obrazy źródłowe, wyspecjalizowane obrazy nie są obecnie obsługiwane.

Interfejs API wymaga elementu SourceType definiującego źródło kompilacji obrazu, obecnie istnieją trzy typy:

  • PlatformImage — wskazuje, że obraz źródłowy jest obrazem witryny Marketplace.
  • ManagedImage — używany podczas uruchamiania z zwykłego obrazu zarządzanego.
  • SharedImageVersion — używana podczas korzystania z wersji obrazu w galerii obliczeniowej platformy Azure jako źródła.

Note

When using existing Windows custom images, you can run the Sysprep command up to three times on a single Windows 7 or Windows Server 2008 R2 image, or 1001 times on a single Windows image for later versions; for more information, see the sysprep documentation.

PlatformImage source

Narzędzie Azure Image Builder obsługuje obrazy systemu Windows Server i klienta oraz obrazy z witryny Azure Marketplace dla systemu Linux, zobacz Informacje o narzędziu Azure Image Builder , aby uzyskać pełną listę.

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

Właściwości są takie same, które są używane do tworzenia maszyn wirtualnych przy użyciu interfejsu wiersza polecenia AZ, uruchom poniższe polecenie, aby uzyskać właściwości:

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

Można użyć latest w wersji, wersja jest oceniana podczas kompilacji obrazu, a nie podczas przesyłania szablonu. Jeśli używasz tej funkcji z miejscem docelowym usługi Azure Compute Gallery, możesz uniknąć ponownego ponownego tworzenia szablonu i ponownego uruchamiania kompilacji obrazu w odstępach czasu, aby obrazy zostały ponownie utworzone na podstawie najnowszych obrazów.

Pomoc techniczna dotycząca informacji o planie rynku

Możesz również określić informacje o planie, na przykład:

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

ManagedImage source

Ustawia obraz źródłowy jako istniejący zarządzany obraz uogólnionego wirtualnego dysku twardego lub maszyny wirtualnej.

Note

Źródłowy obraz zarządzany musi być obsługiwanym systemem operacyjnym, a obraz musi znajdować się w tej samej subskrypcji i regionie co szablon narzędzia Azure Image Builder.

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

Element imageId powinien być identyfikatorem ResourceId obrazu zarządzanego. Użyj az image list polecenia , aby wyświetlić listę dostępnych obrazów.

SharedImageVersion source

Ustawia obraz źródłowy jako istniejącą wersję obrazu w galerii obliczeń platformy Azure.

Note

Wersja źródłowego udostępnionego obrazu musi być obsługiwaną wersją systemu operacyjnego, a wersja obrazu musi znajdować się w tym samym regionie co szablon narzędzia Azure Image Builder, jeśli nie, zreplikuj wersję obrazu do regionu szablonu narzędzia Image Builder.

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId — identyfikator zasobu szablonu usługi ARM wersji obrazu. Gdy nazwa wersji obrazu to "latest", wersja jest oceniana podczas kompilacji obrazu. Element imageVersionId powinien być ResourceId wersją obrazu. Użyj polecenia az sig image-version list , aby wyświetlić listę wersji obrazów.

Poniższy kod JSON ustawia obraz źródłowy jako obraz przechowywany w bezpośredniej galerii udostępnionej.

Note

Bezpośrednia galeria udostępniona jest obecnie dostępna w wersji zapoznawczej.

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

Poniższy kod JSON ustawia obraz źródłowy jako najnowszą wersję obrazu przechowywanego w galerii obliczeń platformy Azure.

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

SharedImageVersion properties:

imageVersionId - ARM template resource ID of the image version. Gdy nazwa wersji obrazu to "latest", wersja jest oceniana podczas kompilacji obrazu.

Properties: stagingResourceGroup

Właściwość stagingResourceGroup zawiera informacje o przejściowej grupie zasobów tworzonej przez usługę Image Builder do użycia podczas procesu kompilacji obrazu. Jest stagingResourceGroup to opcjonalna właściwość dla każdego, kto chce mieć większą kontrolę nad grupą zasobów utworzoną przez program Image Builder podczas procesu kompilacji obrazu. Możesz utworzyć własną grupę zasobów i określić ją w sekcji lub utworzyć ją w stagingResourceGroup twoim imieniu.

Important

Określona grupa zasobów przemieszczania nie może być skojarzona z innym szablonem obrazu, musi być pusta (brak zasobów wewnątrz), w tym samym regionie co szablon obrazu, a kontrola dostępu oparta na rolach "Współautor" lub "Właściciel" została zastosowana do tożsamości przypisanej do zasobu szablonu obrazu narzędzia Azure Image Builder. Konstruktor obrazów sprawdza tagi w przejściowej grupie zasobów przy użyciu kluczy imageTemplateResourceGroupName i imageTemplateName określa, czy dowolny szablon obrazu używa przejściowej grupy zasobów. Jeśli te tagi istnieją przed przesłaniem szablonu obrazu lub nie są zgodne z uruchomionym szablonem obrazu podczas kompilacji obrazu, operacja zakończy się niepowodzeniem.

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

Scenariusze tworzenia szablonów

  • Właściwość stagingResourceGroup jest pozostawiona pusta

    stagingResourceGroup Jeśli właściwość nie jest określona lub określona z pustym ciągiem, usługa Image Builder tworzy tymczasową grupę zasobów z domyślną konwencją nazw "IT_***". Grupa zasobów przejściowych ma zastosowane domyślne tagi: createdBy, , imageTemplateNameimageTemplateResourceGroupName. Ponadto domyślna kontrola dostępu oparta na rolach jest stosowana do tożsamości przypisanej do zasobu szablonu narzędzia Azure Image Builder, czyli "Współautor".

  • Właściwość stagingResourceGroup jest określona z grupą zasobów, która istnieje

    stagingResourceGroup Jeśli właściwość jest określona z grupą zasobów, która istnieje, usługa Image Builder sprawdza, czy grupa zasobów nie jest skojarzona z innym szablonem obrazu, jest pusta (brak zasobów wewnątrz), w tym samym regionie co szablon obrazu i ma RBAC "Współautor" lub "Właściciel" zastosowaną do tożsamości przypisanej do zasobu szablonu obrazu programu Azure Image Builder. Jeśli którekolwiek z wyżej wymienionych wymagań nie zostaną spełnione, zostanie zgłoszony błąd. Grupa zasobów przejściowych ma dodane do niej następujące tagi: usedBy, imageTemplateName, imageTemplateResourceGroupName. Istniejące tagi nie są usuwane.

Important

Podczas próby określenia istniejącej grupy zasobów i sieci wirtualnej do usługi Azure Image Builder z obrazem źródłowym systemu Windows musisz przypisać rolę współautora do grupy zasobów dla jednostki usługi odpowiadającej pierwszej aplikacji usługi Azure Image Builder. Aby uzyskać instrukcje dotyczące przypisywania roli współautora do grupy zasobów za pomocą polecenia interfejsu wiersza polecenia i portalu, zobacz następującą dokumentację Rozwiązywanie problemów z maszyną wirtualną Azure Image Builder: Błąd autoryzacji podczas tworzenia dysku

  • Właściwość stagingResourceGroup jest określona z grupą zasobów, która nie istnieje

    stagingResourceGroup Jeśli właściwość jest określona z grupą zasobów, która nie istnieje, usługa Image Builder tworzy tymczasową grupę zasobów o nazwie podanej stagingResourceGroup we właściwości . Jeśli dana nazwa nie spełnia wymagań dotyczących nazewnictwa platformy Azure dla grup zasobów, wystąpi błąd. Grupa zasobów przejściowych ma zastosowane domyślne tagi: createdBy, , imageTemplateNameimageTemplateResourceGroupName. Domyślnie tożsamość przypisana do zasobu szablonu obrazu narzędzia Azure Image Builder ma zastosowaną kontrolę dostępu opartą na rolach "Współautor" w grupie zasobów.

Template deletion

Każda tymczasowa grupa zasobów utworzona przez usługę Image Builder zostanie usunięta po usunięciu szablonu obrazu. Usunięcie obejmuje przejściowe grupy zasobów, które zostały określone we stagingResourceGroup właściwości, ale nie istniały przed kompilacją obrazu.

Jeśli konstruktor obrazów nie utworzył przejściowej grupy zasobów, ale zasoby w grupie zasobów, te zasoby zostaną usunięte po usunięciu szablonu obrazu, biorąc pod uwagę, że usługa Image Builder ma odpowiednie uprawnienia lub rolę wymaganą do usunięcia zasobów.

Properties: validate

Za pomocą validate właściwości można weryfikować obrazy platformy i wszystkie niestandardowe obrazy tworzone niezależnie od tego, czy użyto narzędzia Azure Image Builder do ich utworzenia.

Narzędzie Azure Image Builder obsługuje tryb "Tylko weryfikacja źródła", który można ustawić przy użyciu sourceValidationOnly właściwości . sourceValidationOnly Jeśli właściwość ma wartość true, obraz określony w source sekcji zostanie zweryfikowany bezpośrednio. W celu wygenerowania nie zostanie uruchomiona żadna oddzielna kompilacja, a następnie zweryfikuj dostosowany obraz.

Właściwość inVMValidations przyjmuje listę modułów sprawdzania poprawności, które zostaną wykonane na obrazie. Narzędzie Azure Image Builder obsługuje moduły sprawdzania poprawności plików, programu PowerShell i powłoki.

Właściwość continueDistributeOnFailure jest odpowiedzialna za to, czy obrazy wyjściowe będą dystrybuowane w przypadku niepowodzenia walidacji. Domyślnie jeśli walidacja nie powiedzie się i ta właściwość ma wartość false, obrazy wyjściowe nie będą dystrybuowane. Jeśli walidacja nie powiedzie się i ta właściwość ma wartość true, obrazy wyjściowe będą nadal dystrybuowane. Użyj tej opcji z ostrożnością, ponieważ może to spowodować rozpowszechnianie nieudanych obrazów do użycia. W obu przypadkach (prawda lub fałsz) uruchomienie obrazu końcowego zostanie zgłoszone jako niepowodzenie w przypadku niepowodzenia weryfikacji. Ta właściwość nie ma wpływu na to, czy walidacja zakończy się powodzeniem, czy nie.

W przypadku korzystania z polecenia validate:

  • Można użyć wielu modułów sprawdzania poprawności.
  • Moduły sprawdzania poprawności są wykonywane w kolejności określonej w szablonie.
  • Jeśli jeden moduł sprawdzania poprawności zakończy się niepowodzeniem, cały składnik sprawdzania poprawności zakończy się niepowodzeniem i zgłosi błąd.
  • Zaleca się dokładne przetestowanie skryptu przed użyciem go w szablonie. Debugowanie skryptu na własnej maszynie wirtualnej będzie łatwiejsze.
  • Nie umieszczaj poufnych danych w skryptach.
  • The script locations need to be publicly accessible, unless you're using MSI.

Jak używać validate właściwości do weryfikowania obrazów systemu 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 Właściwości:

  • type – PowerShell.

  • name - name of the validator

  • scriptUri - URI of the PowerShell script file.

  • inline – array of commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command, this avoids reported failure of the script/inline command.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    To generate the sha256Checksum, using a PowerShell on Windows Get-Hash

Jak używać właściwości do sprawdzania validate poprawności obrazów systemu 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 Właściwości:

  • type – Shell or File specified as the validation type to be performed.

  • name - name of the validator

  • scriptUri - URI of the script file

  • inline - array of commands to be run, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    Aby wygenerować sha256Checksum, użyj terminalu na komputerze Mac/Linux uruchom polecenie: sha256sum <fileName>

  • destination - Destination of the file.

  • sha256Checksum - Specifies the SHA256 checksum of the file.

  • sourceUri - The source URI of the file.

Properties: vmProfile

vmSize (optional)

Konstruktor obrazów używa domyślnego rozmiaru Standard_D1_v2 jednostki SKU dla obrazów gen1 i Standard_D2ds_v4 obrazów gen2. Generowanie jest definiowane przez obraz określony w elemecie source. Możesz zastąpić rozmiar vmSize z następujących powodów:

  • Wykonywanie dostosowań wymagających zwiększonej ilości pamięci, procesora CPU i obsługi dużych plików (GB).
  • Uruchamianie kompilacji systemu Windows, należy użyć "Standard_D2_v2" lub równoważnego rozmiaru maszyny wirtualnej.
  • Require VM isolation.
  • Dostosuj obraz, który wymaga określonego sprzętu. Na przykład w przypadku maszyny wirtualnej z procesorem GPU potrzebny jest rozmiar maszyny wirtualnej procesora GPU.
  • Require end to end encryption at rest of the build VM, you need to specify the support build VM size that doesn't use local temporary disks.

osDiskSizeGB

Domyślnie konstruktor obrazów nie zmienia rozmiaru obrazu, używa rozmiaru obrazu źródłowego. You can optionally only increase the size of the OS Disk (Win and Linux), and a value of 0 means leaving the same size as the source image. Nie można zmniejszyć rozmiaru dysku systemu operacyjnego do mniejszego niż rozmiar obrazu źródłowego.

{
  "osDiskSizeGB": 100
}

vnetConfig (optional)

Jeśli nie określisz żadnych właściwości sieci wirtualnej, narzędzie Image Builder utworzy własną sieć wirtualną, publiczny adres IP i sieciową grupę zabezpieczeń. Publiczny adres IP jest używany do komunikacji usługi z maszyną wirtualną kompilacji. Jeśli nie chcesz mieć publicznego adresu IP lub chcesz, aby konstruktor obrazów miał dostęp do istniejących zasobów sieci wirtualnej, takich jak serwery konfiguracji (DSC, Chef, Puppet, Ansible), udziały plików, możesz określić sieć wirtualną. For more information, review the networking documentation.

"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

Identyfikator zasobu istniejącej podsieci, w której wdrożono maszynę wirtualną kompilacji i walidowaną maszynę wirtualną.

containerInstanceSubnetId (optional)

Resource ID of a pre-existing subnet on which Azure Container Instance (ACI) is deployed for Isolated Builds. Jeśli to pole nie zostanie określone, tymczasowa sieć wirtualna wraz z podsieciami i sieciowymi grupami zabezpieczeń zostanie wdrożona w przejściowej grupie zasobów oprócz innych zasobów sieciowych (prywatnego punktu końcowego, usługi Private Link, usługi Azure Load Balancer i maszyny wirtualnej serwera proxy), aby umożliwić komunikację między usługą ACI a kompilowaną maszyną wirtualną.

[Ta właściwość jest dostępna tylko w wersjach 2024-02-01 interfejsu API lub nowszych, chociaż istniejące szablony utworzone przy użyciu wcześniejszych wersji interfejsu API można zaktualizować, aby określić tę właściwość.

To pole można określić tylko wtedy, gdy subnetId jest również określone i musi spełniać następujące wymagania:

  • Ta podsieć musi znajdować się w tej samej sieci wirtualnej co podsieć określona w elem subnetId.
  • Ta podsieć nie może być tą samą podsiecią co podsieć określona w elem subnetId.
  • Ta podsieć musi być delegowana do usługi ACI, aby można było jej użyć do wdrożenia zasobów usługi ACI. You can read more about subnet delegation for Azure services here. ACI specific subnet delegation information is available here.
  • Ta podsieć musi zezwalać na dostęp wychodzący do Internetu i do podsieci określonej w pliku subnetId. Te dostępy są wymagane, aby można było aprowizować usługę ACI i komunikować się z maszyną wirtualną kompilacji w celu wykonania dostosowań/weryfikacji. Na drugim końcu podsieć określona w subnetId pliku musi zezwalać na dostęp przychodzący z tej podsieci. Ogólnie rzecz biorąc, domyślne reguły zabezpieczeń sieciowych grup zabezpieczeń platformy Azure zezwalają na dostęp. Jeśli jednak do sieciowych grup zabezpieczeń zostanie dodanych więcej reguł zabezpieczeń, nadal muszą być dozwolone następujące prawa dostępu:
    1. Dostęp wychodzący z podsieci określonej w containerInstanceSubnetId pliku do:
      1. Do Internetu na porcie 443 (w celu aprowizacji obrazu kontenera).
      2. Do Internetu na porcie 445 (na potrzeby instalowania udziału plików z usługi Azure Storage).
      3. Do podsieci określonej w subnetId porcie 22 (dla ssh/Linux) i portu 5986 (dla winRM/Windows) (na potrzeby nawiązywania połączenia z maszyną wirtualną kompilacji).
    2. Dostęp przychodzący do podsieci określonej w pliku subnetId:
      1. Do portu 22 (dla protokołu ssh/Linux) i portu 5986 (dla usługi WinRM/Windows) z podsieci określonej w (containerInstanceSubnetIdw przypadku usługi ACI do nawiązania połączenia z maszyną wirtualną kompilacji).
  • The template identity must have permission to perform 'Microsoft.Network/virtualNetworks/subnets/join/action' action on this subnet's scope. You can read more about Azure permissions for Networking here.

proxyVmSize (optional)

Rozmiar maszyny wirtualnej serwera proxy używanej do przekazywania ruchu do maszyny wirtualnej kompilacji i maszyny wirtualnej weryfikacji. To pole nie może zostać określone, jeśli containerInstanceSubnetId zostanie określone, ponieważ w takim przypadku nie wdrożono żadnej maszyny wirtualnej serwera proxy. Pomiń lub określ pusty ciąg, aby użyć wartości domyślnej (Standard_A1_v2).

Properties: autoRun

Za pomocą autoRun właściwości można kontrolować, czy proces kompilacji szablonu obrazu powinien zostać automatycznie uruchomiony po utworzeniu szablonu. Jest to wyliczenie z dwiema możliwymi wartościami:

  • Enabled - Auto run is enabled, so your image template build process will automatically start when the template is created.
  • Disabled - Auto run is disabled, so you will have to manually start the image build process after the template is created.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Note

When you set autoRun to "Enabled," the image build process runs once upon template creation. Gwarantuje to, że początkowa kompilacja obrazu będzie bezproblemowo wykonywana. Jednak nie zapewnia spójnych i ciągłych kompilacji obrazów. Aby uzyskać spójne i ciągłe kompilacje obrazów uruchamiane po zaktualizowaniu szablonu obrazu, zobacz How to use Azure Image Builder triggers to set up an automatic image build (Jak używać wyzwalaczy narzędzia Azure Image Builder do konfigurowania automatycznej kompilacji obrazu).

W przeciwieństwie do autoRunmetody automatyczne tworzenie obrazów za pośrednictwem zasobu wyzwalacza narzędzia Azure Image Builder gwarantuje, że kompilacje obrazów będą wykonywane spójnie. Za każdym razem, gdy w szablonie zostaną wprowadzone zmiany, usługa Azure Image Builder automatycznie wyzwoli proces kompilacji obrazu.

Wybierz autoRun dla obrazu natychmiastowego kompilacji podczas tworzenia szablonu. Wybierz automatyczne tworzenie obrazów, gdy potrzebujesz ciągłej spójności w kompilacjach obrazu. Weź pod uwagę określone wymagania i użyj odpowiedniej opcji na podstawie przepływu pracy.

Properties: managedResourceTags

Za pomocą właściwości można zastosować managedResourceTags tagi do zasobów tworzonych przez usługę Azure Image Builder w przejściowej grupie zasobów podczas kompilacji obrazu. Aby uzyskać więcej informacji na temat przejściowej grupy zasobów, zobacz Omówienie narzędzia Azure Image Builder

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

Operacje szablonu obrazu

Uruchamianie kompilacji obrazu

Aby uruchomić kompilację, musisz wywołać polecenie "Uruchom" w zasobie szablonu obrazu, przykłady run poleceń:

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

Anulowanie kompilacji obrazu

Jeśli uruchamiasz kompilację obrazu, która uważasz, że jest niepoprawna, oczekiwanie na wprowadzenie danych przez użytkownika lub nigdy nie zakończy się pomyślnie, możesz anulować kompilację.

Kompilację można anulować w dowolnym momencie. Jeśli faza dystrybucji została uruchomiona, nadal możesz anulować, ale musisz wyczyścić wszystkie obrazy, które mogą nie zostać ukończone. The cancel command doesn't wait for cancel to complete, monitor lastrunstatus.runstate for canceling progress, using these status commands.

cancel Przykłady poleceń:

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

Next steps

Istnieją przykładowe pliki .json dla różnych scenariuszy w usłudze GitHub narzędzia Azure Image Builder.

  • Last updated on