Создание шаблона JSON шаблона Bicep или шаблона ARM для построителя образов Azure

Применимо к: ✔️ Виртуальные машины Linux ✔️ Виртуальные машины Windows ✔️ Гибкие масштабируемые наборы

Azure Image Builder использует Bicep-файл или файл шаблона JSON шаблона ARM для передачи сведений в службу построителя образов. В этой статье мы рассмотрим разделы файлов, чтобы создать собственные. Сведения о последних версиях API см. в справочнике по шаблону. Примеры полных JSON-файлов см. в разделе GitHub, посвященном Конструктору образов виртуальных машин Azure.

Базовый формат:

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

Версия API будет меняться со временем по мере изменения API. См. статью Новые возможности Конструктора образов виртуальных машин Azure, чтобы узнать обо всех основных изменениях API и обновлениях функций для службы Конструктора образов виртуальных машин Azure

Type

type — это тип ресурса, который должен быть Microsoft.VirtualMachineImages/imageTemplates.

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

Location

Служба "Конструктор образов виртуальных машин" доступна в следующих регионах:

Note

Вы по-прежнему можете распределять образы вне этих регионов.

  • East US
  • Восточная часть США 2
  • Центрально-западная часть США
  • West US
  • западная часть США 2
  • Западная часть США — 3
  • Центрально-южная часть США
  • North Europe
  • West Europe
  • Юго-Восточная Азия
  • Australia Southeast
  • Australia East
  • UK South
  • UK West
  • Brazil South
  • Canada Central
  • Central India
  • Central US
  • France Central
  • Центрально-Западная Германия
  • Japan East
  • Центрально-северная часть США
  • Norway East
  • Switzerland North
  • Западная Индия Jio
  • UAE North
  • East Asia
  • Korea Central
  • Северная часть ЮАР
  • Qatar Central
  • USGov Аризона (общедоступная предварительная версия);
  • USGov Вирджиния (общедоступная предварительная версия).
  • Китай Северная 3 (общедоступная предварительная версия)
  • Sweden Central
  • Poland Central
  • Italy North
  • Israel Central
  • Северная часть Новой Зеландии
  • Тайвань Северо-Запад

Important

Зарегистрируйте возможность Microsoft.VirtualMachineImages/FairfaxPublicPreview, чтобы получить доступ к общедоступной предварительной версии Конструктора образов Azure в регионах Azure для государственных организаций (USGov Аризона и USGov Вирджиния).

Important

Зарегистрируйте функцию Microsoft.VirtualMachineImages/MooncakePublicPreview для доступа к общедоступной предварительной версии Конструктора образов Azure в регионе China North 3.

Чтобы получить доступ к общедоступной предварительной версии конструктора образов виртуальных машин Azure в регионах Azure для государственных организаций (USGov Аризона и USGov Вирджиния), необходимо зарегистрировать функцию Microsoft.VirtualMachineImages/FairfaxPublicPreview . Для этого выполните следующую команду в PowerShell или Azure CLI:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

Чтобы получить доступ к общедоступной предварительной версии конструктора образов виртуальных машин Azure в регионе China North 3, необходимо зарегистрировать функцию Microsoft.VirtualMachineImages/MooncakePublicPreview . Для этого выполните следующую команду в PowerShell или Azure CLI:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Место расположения данных

Служба Конструктора образов виртуальных машин Azure хранит данные клиентов в регионах со строгими правилами расположения данных. Если сбой службы для регионов с требованиями к месту расположения данных, необходимо создать файлы или шаблоны Bicep в другом регионе и географическом регионе.

Избыточность зон

Распространение поддерживает избыточность между зонами, виртуальные жесткие диски (VHD) по умолчанию распространяются по учетной записи хранилища, избыточного между зонами (ZRS), а версия Azure Compute Gallery (ранее известная как Shared Image Gallery) будет поддерживать тип хранилища ZRS , если он указан.

Tags

Теги — это пары "ключ — значение", которые вы можете указать для создаваемого образа.

Identity

Добавить назначаемые пользователем удостоверения можно двумя способами, описанными ниже.

Назначаемое пользователем удостоверение для ресурса шаблона образа Конструктора образов виртуальных машин Azure

Обязательно. Чтобы предоставить Конструктору образов Azure разрешения на чтение и запись образов, а также на чтение скриптов из службы хранилища Azure, вы должны создать назначаемое пользователем удостоверение Azure с разрешениями на доступ к отдельным ресурсам. Дополнительные сведения о том, как работают разрешения Image Builder, и описание соответствующих шагов см. в статье Создание образа и использование управляемого удостоверения, назначаемого пользователем, для доступа к файлам в учетной записи хранения Azure.

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

Назначаемое пользователем удостоверение для службы "Конструктор образов":

  • Поддерживает только одно удостоверение.
  • Не поддерживает пользовательские доменные имена.

Дополнительные сведения см. в разделе Что такое управляемые удостоверения для ресурсов Azure. Дополнительные сведения о развертывании этого компонента см. в разделе Настройка управляемых удостоверений для ресурсов Azure на виртуальной машине Azure с помощью Azure CLI.

Назначаемое пользователем удостоверение для виртуальной машины сборки Конструктора образов

Это поле доступно только в версиях API 2021-10-01 и выше.

Необязательно. Виртуальная машина сборки построителя образов, созданная службой построителя образов в подписке, используется для создания и настройки образа. Чтобы виртуальная машина сборки Конструктора образов имела разрешения на проверку подлинности в других службах, например Azure Key Vault, в вашей подписке, необходимо создать одно или несколько назначаемых пользователем Azure удостоверений, имеющих разрешения для отдельных ресурсов. После этого Конструктор образов виртуальных машин Azure сможет связать эти назначаемые пользователем удостоверения с виртуальной машиной сборки. Скрипты настройки, выполняемые на виртуальной машине сборки, затем смогут получать маркеры для этих удостоверений и взаимодействовать с другими ресурсами Azure по мере необходимости. Имейте в виду, что назначаемому пользователем удостоверению для Конструктора образов виртуальных машин Azure должна быть назначена роль "Оператор управляемого удостоверения" для всех назначаемых пользователем удостоверений в Конструкторе образов, чтобы их можно было связать с виртуальной машиной сборки.

Note

Обратите внимание, что для виртуальной машины сборки Конструктора образов можно указать несколько удостоверений, включая удостоверение, созданное для ресурса шаблона образа. По умолчанию удостоверение, созданное для ресурса шаблона образа, не будет добавлено автоматически в виртуальную машину сборки.

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

Назначаемое пользователем удостоверение для виртуальной машины сборки Конструктора образов:

  • Поддерживает список, состоящий из одного или нескольких управляемых удостоверений, назначаемых пользователем, для настройки на виртуальной машине.
  • Поддерживает сценарии с несколькими подписками (удостоверение создается в одной подписке, а шаблон образа — в другой подписке в том же арендаторе).
  • Не поддерживает сценарии с несколькими арендаторами (удостоверение создается в одном арендаторе, а шаблон образа — в другом).

Дополнительные сведения см. на следующих ресурсах:

Свойства: buildTimeoutInMinutes

Максимальная длительность ожидания при создании шаблона образа (включает настройки, проверки и распространение).

Если вы не укажете свойство или зададите значение 0, будет использоваться значение по умолчанию, которое составляет 240 минут или четыре часа. Минимальное значение — 6 минут, а максимальное — 960 минут или 16 часов. Когда значение времени ожидания достигается (если сборка образа завершена), вы увидите ошибку, аналогичную следующей:

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

Для Windows не рекомендуется задавать значение buildTimeoutInMinutes меньше 60 минут. Если вы обнаружите, что вы попадаете в время ожидания, просмотрите журналы , чтобы узнать, ожидается ли шаг настройки на что-то подобное вводу пользователем. Если вам потребуется больше времени для завершения настроек, увеличьте значение buildTimeoutInMinutes. Но не задавайте слишком высокое значение, так как, возможно, вам придется дожидаться, пока это время истечет, прежде чем появится сообщение об ошибке.

Свойства: настройка

Конструктор образов поддерживает несколько настройщиков, которые используются для настройки образа, например выполнения скриптов или перезагрузки серверов.

Применяя customize, помните следующие правила.

  • Вы можете использовать несколько настройщиков
  • Настройщики выполняются в порядке, указанном в шаблоне.
  • В случае сбоя одного из настройщиков происходит сбой всего компонента настройки и выводится сообщение об ошибке.
  • Тщательно протестируйте скрипты, прежде чем использовать их в шаблоне. Отладка скриптов — более простая операция.
  • Не включайте в скрипты конфиденциальные данные. Встроенные команды можно просмотреть в определении шаблона образа. Если у вас есть конфиденциальная информация (включая пароли, маркер SAS, маркеры проверки подлинности и т. д.), ее следует включить в скрипты в службе хранилища Azure, где для доступа требуется проверка подлинности.
  • Расположение скриптов должно быть общедоступным, если вы не используете удостоверение, назначенное пользователем.

Раздел customize — это массив. Поддерживаемые типы настройщика: File, PowerShell, Shell, WindowsRestart и 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 поддерживает выполнение скриптов оболочки в Linux. Скрипты оболочки должны быть общедоступными или необходимо настроить MSI для доступа к ним.

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

Настройка свойств:

  • тип — оболочка.

  • name — имя для отслеживания настройки.

  • scriptUri — универсальный код ресурса (URI) в расположение файла.

  • Inline — массив команд оболочки, разделенных запятыми.

  • sha256Checksum — значение контрольной суммы sha256 файла, вы создаете это значение локально, а затем построитель образов будет проверять и проверять.

    Чтобы сформировать sha256Checksum, откройте окно терминала в Mac/Linux и выполните следующую команду: sha256sum <fileName>

Note

Встроенные команды хранятся в определении шаблона образа, поэтому их можно увидеть при выгрузке определения образа. Если у вас есть важные команды или значения (включая пароли, маркер SAS, маркеры проверки подлинности и пр.), рекомендуется включить их в скрипты и использовать идентификатор пользователя для проверки подлинности в службе хранилища Azure.

Привилегии суперпользователя

Добавьте в команды префикс sudo для их выполнения с правами суперпользователя. Вы можете включить команды в скрипты или использовать встроенные команды, например:

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

Пример скрипта с использованием команды sudo, которую можно вызвать с помощью scriptUri:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

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

Настройщик перезапуска Windows

С помощью настройщика WindowsRestart вы можете перезапустить виртуальную машину Windows и дождаться, пока она снова будет подключена. Этот настройщик позволит вам установить программное обеспечение, требующее перезагрузки.

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

Настройка свойств:

  • Тип: WindowsRestart.
  • restartCommand — команда для выполнения перезапуска (необязательно). Значение по умолчанию — 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand — команда для проверки успешности перезапуска (необязательно).
  • restartTimeout — время ожидания перезапуска, указанное в виде строки величины и единицы. Например, 5m (5 минут) или 2h (2 часа). Значение по умолчанию — 5m.

Note

Настройщик перезапуска Linux отсутствует.

Настройщик PowerShell

Настройщик PowerShell поддерживает выполнение сценариев PowerShell и встроенных команд в Windows, скрипты должны быть общедоступными, чтобы служба могла получить к ним доступ.

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

Настройка свойств:

  • type — PowerShell.

  • scriptUri — универсальный код ресурса (URI) в расположение файла скрипта PowerShell.

  • inline — встроенные команды для выполнения, разделенные запятыми.

  • validExitCodes — необязательные допустимые коды, которые можно вернуть из команды script/inline. Свойство позволяет избежать сбоя скрипта или встроенной команды.

  • runElevated — необязательно, логическое значение, поддержка выполнения команд и сценариев с повышенными разрешениями.

  • runAsSystem — необязательный, логический, определяет, должен ли скрипт PowerShell выполняться от имени системного пользователя.

  • sha256Checksum — создайте контрольную сумму SHA256 файла локально, обновите значение контрольной суммы до нижнего регистра, а построитель образов проверит контрольную сумму во время развертывания шаблона образа.

    Чтобы создать sha256Checksum, используйте командлет Get-FileHash в PowerShell.

Настройщик файлов

Настройщик File позволяет Конструктору образов скачивать файлы из репозитория GitHub или службы хранилища Azure. Настройщик доступен как в Linux, так и в Windows. Если у вас есть конвейер сборки образа, который зависит от артефактов сборки, можно установить настройщик File для скачивания из общей папки сборки и переместить артефакты в образ.

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

Свойства настройщика File:

  • sourceUri — доступная конечная точка хранилища, эта конечная точка может быть GitHub или хранилище Azure. Вы можете загружать только один файл, а не весь каталог. Если необходимо загрузить каталог, используйте сжатый файл, а затем распакуйте его с помощью настройщиков Shell или PowerShell.

    Note

    Если sourceUri является учетной записью служба хранилища Azure, независимо от того, помечен ли большой двоичный объект общедоступным, необходимо предоставить разрешения управляемого удостоверения пользователя для чтения в большом двоичном объекте. См. этот пример , чтобы задать разрешения хранилища.

  • назначение — полный путь назначения и имя файла. Все указанные пути и подкаталоги должны существовать. Для их предварительной настройки используйте настройщики Shell или PowerShell. Вы можете использовать настройщики скриптов для создания пути.

Настройщик поддерживает каталоги Windows и пути Linux, но с некоторыми отличиями:

  • В Linux Конструктор образов может осуществлять запись только по пути /tmp.
  • В Windows нет ограничений на используемый путь, но этот путь должен существовать.

Если возникает ошибка при попытке скачать файл или поместить его в указанный каталог, настройка шага завершается ошибкой, и эта ошибка будет находиться в customization.log.

Note

Настройщик файлов подходит только для скачивания небольших файлов, размером <20 МБ. Для скачивания файлов большего размера используйте скрипт или встроенную команду с кодом для скачивания файлов, например wget или curl в Linux, Invoke-WebRequest в Windows. Для файлов, которые находятся в хранилище Azure, убедитесь, что вы назначите удостоверение с разрешениями для просмотра этого файла виртуальной машине сборки, следуя инструкциям в документации: назначаемое пользователем удостоверение для виртуальной машины сборки построителя образов. Любой файл, который не хранится в Azure, должен быть общедоступным, чтобы скачать его с помощью построителя образов Azure.

  • sha256Checksum — создайте контрольную сумму SHA256 файла локально, обновите значение контрольной суммы до нижнего регистра, а построитель образов проверит контрольную сумму во время развертывания шаблона образа.

    Чтобы создать sha256Checksum, используйте командлет Get-FileHash в PowerShell.

Настройщик WindowsUpdate

Настройщик WindowsUpdate создан на основе средства подготовки Центра обновления Windows для Packer. Это проект с открытым исходным кодом, поддерживаемый сообществом Packer. Корпорация Майкрософт тестирует и проверяет это средство подготовки с помощью службы Конструктора образов, планируя и дальше исследовать проблемы с этим средством и работать над их устранением. Но этот проект с открытым кодом официально не поддерживается корпорацией Майкрософт. Подробную документацию и справку по данному средству подготовки Центра обновления Windows см. в репозитории проекта.

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

Свойства настройщика:

  • type — WindowsUpdate.
  • searchCriteria — необязательно, определяет тип установленных обновлений (например, рекомендуемый или важный), BrowseOnly=0 и IsInstalled=0 (рекомендуется) по умолчанию.
  • фильтры — необязательно, позволяет указать фильтр для включения или исключения обновлений.
  • updateLimit — необязательно, определяет, сколько обновлений можно установить, значение по умолчанию — 1000.

Note

Настройка Центра обновления Windows может завершиться ошибкой при наличии невыполненных перезапусков Windows или при выполнении установки приложения. Обычно эта ошибка может появиться в customization.log, в System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. Мы настоятельно рекомендуем добавить в перезапуск Windows или разрешить приложениям достаточно времени, чтобы завершить установку с помощью команд спящего режима или ожидания в встроенных командах или сценариях перед запуском Центра обновления Windows.

Generalize

По умолчанию Конструктор образов виртуальных машин Azure также выполняет код deprovision в конце каждого этапа настройки образа, чтобы подготовить образ к использованию. Подготовка к использованию — это процесс, в котором образ настраивается для многократного использования в целях создания нескольких виртуальных машин. Для виртуальных машин Windows Конструктор образов виртуальных машин Azure использует команду Sysprep. Для Linux Конструктор образов выполняет код waagent -deprovision.

Команды построителя образов для обобщения могут не подходить для каждой ситуации, поэтому Конструктор образов Azure позволяет настроить эту команду при необходимости.

Если выполняется перенос существующей настройки и вы используете разные команды Sysprep и waagent, вы можете применять универсальные команды Конструктора образов, а в случае сбоя создания виртуальной машины — свои собственные команды Sysprep или waagent.

Если Построитель образов Azure успешно создает пользовательский образ Windows и создаете виртуальную машину из нее, найдите, что создание виртуальной машины завершается сбоем или не завершается успешно, необходимо просмотреть документацию по Sysprep Windows Server Sysprep или отправить запрос на поддержку с помощью группы поддержки служб поддержки служб клиентов Windows Server, которая может устранить неполадки и рекомендовать правильное использование Sysprep.

Команда 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 ...'

Команда Linux deprovision по умолчанию

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

Переопределение команд

Чтобы переопределить команды, с помощью средств подготовки скриптов PowerShell или Shell создайте файлы команд со строго соответствующими именами файлов и разместите их в правильных каталогах:

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

Построитель образов считывает эти команды, эти команды записываются в журналы AIB, customization.log. Сведения об устранении неполадок , связанных с сбором журналов.

Свойства: errorHandling

Свойство errorHandling позволяет настроить способ обработки ошибок во время создания образа.

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

Свойство errorHandling позволяет настроить способ обработки ошибок во время создания образа. Он имеет два свойства:

  • onCustomizerError — указывает действие, выполняемое при возникновении ошибки во время этапа создания образа настройщика.
  • onValidationError — указывает действие, выполняемое при возникновении ошибки во время проверки шаблона изображения.

Свойство errorHandling также имеет два возможных значения для обработки ошибок во время создания образа:

  • очистка — гарантирует, что временные ресурсы, созданные Packer, очищаются даже в том случае, если packer или одна из настроек или проверок сталкивается с ошибкой. Это обеспечивает обратную совместимость с существующим поведением.
  • прерывание . Если Packer сталкивается с ошибкой, служба Azure Image Builder (AIB) пропускает очистку временных ресурсов. Как владелец шаблона AIB, вы несете ответственность за очистку этих ресурсов из подписки. Эти ресурсы могут содержать полезные сведения, такие как журналы и файлы, оставленные на временной виртуальной машине, которая может помочь в расследовании ошибки, обнаруженной Packer.

Свойства: распространение

Конструктор образов Azure поддерживает три целевых объекта распространения:

  • ManagedImage — управляемый образ.
  • sharedImage — коллекция вычислений Azure.
  • VHD — VHD в учетной записи хранения.

Вы можете распространить образ в оба типа целевого объекта в рамках одной конфигурации.

Note

Стандартная команда Конструктора образов Azure sysprep не содержит /mode:vm, но это свойство может требоваться при создании образов, в которых будет установлена роль HyperV. Если необходимо добавить этот аргумент команды, необходимо переопределить команду sysprep.

Так как у вас может быть несколько целевых объектов для распространения образа, Конструктор образов поддерживает состояние для каждого целевого объекта распространения, которое можно получить, запросив runOutputName. runOutputName — объект, который можно запросить после распространения, чтобы получить сведения об этом распространении. Например, можно запросить расположение VHD, регионы, в которые была реплицирована версия образа, или версию созданного образа SIG. Это свойство имеет каждый целевой объект распространения. Имя runOutputName должно быть уникальным для каждого целевого объекта распространения. Ниже приведен пример с запрашиванием распространения Коллекции вычислений 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"
}

Распространение: managedImage

Выходные данные изображения — это ресурс управляемого образа.

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

Распространение свойств:

  • type — ManagedImage
  • imageId — идентификатор ресурса целевого образа, ожидаемый формат: /subscriptionId/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • расположение — расположение управляемого образа.
  • runOutputName — уникальное имя для идентификации дистрибутива.
  • artifactTags — необязательный пользователь, указанный тегами key\value.

Note

Целевая группа ресурсов должна существовать. Если вы хотите распространить образ в другой регион, это увеличит время развертывания.

Распространение: sharedImage

Коллекция вычислений Azure — это новая служба управления образами, которая обеспечивает управление репликацией региона образа, управление версиями и предоставление общего доступа к пользовательским образам. Конструктор образов Azure поддерживает распространение с помощью этой службы, так что вы можете распространять образы в регионы, поддерживаемые коллекциями вычислений Azure.

Коллекция вычислений Azure состоит из следующих компонентов:

  • Коллекция — контейнер для нескольких образов. Коллекция развертывается в одном регионе.
  • Определения изображений — концептуальная группировка изображений для изображений.
  • Версии образа — тип образа, используемый для развертывания виртуальной машины или масштабируемого набора. Версии образов можно реплицировать в другие регионы, где требуется развернуть виртуальные машины.

Перед распространением в коллекции необходимо создать коллекцию и определение образа (см. раздел Создание коллекции).

Note

Идентификатор версии образа должен отличаться от всех версий образов, которые находятся в существующей коллекции вычислений Azure.

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

Ниже приведен пример использования replicationRegions поля для распространения в коллекцию вычислений Azure.

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

Note

replicationRegions не рекомендуется использовать для дистрибутивов коллекций, так как targetRegions обновляется свойство. Дополнительные сведения см. в разделе targetRegions.

Распространение: targetRegions

Ниже приведен пример использования поля targetRegions для распространения в коллекцию вычислений 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"
             }
          ]
       },
    ]

Свойства распространения для коллекций:

  • type — sharedImage

  • galleryImageId — идентификатор коллекции вычислений Azure, это свойство можно указать в двух форматах:

    • Автоматическое управление версиями . Построитель образов создает монотонный номер версии для вас, это свойство полезно, если вы хотите сохранить перестроение образов из одного шаблона: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>
    • Явное управление версиями — вы можете передать номер версии, который должен использовать Конструктор образов. Формат: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>

  • runOutputName — уникальное имя для идентификации дистрибутива.

  • artifactTags — необязательный пользователь, указанный тегами key\value.

  • replicationRegions — массив регионов для репликации. Один из регионов должен быть регионом, в котором развернута коллекция. Добавление регионов означает увеличение времени сборки, так как сборка не завершится до завершения репликации. Это поле устарело по состоянию на API версии 2022-07-01, используйте targetRegions при распространении типа SharedImage.

  • targetRegions — массив регионов для репликации. Он недавно появился в рамках API 2022-07-01 и применяется только к распространению SharedImage типов.

  • excludeFromLatest (необязательно) — позволяет пометить созданную версию образа не в качестве последней версии в определении коллекции, значение по умолчанию — false.

  • storageAccountType (необязательно) — AIB поддерживает указание этих типов хранилища для создаваемой версии образа:

    • "Standard_LRS"
    • "Standard_ZRS","

Note

Если шаблон образа и указанное определение образа (image definition) находятся в разных расположениях, будет предоставлено дополнительное время для создания образов. В настоящее время Конструктор образов не содержит параметра location для ресурса версии образа, он будет взят из родительского объекта image definition. Например, если определение образа находится в регионе westus и требуется реплицировать версию образа в eastus, BLOB-объект будет скопирован в westus из этого региона, и в регионе westus будет создан ресурс версии образа с последующей репликацией в eastus. Чтобы избежать дополнительного времени репликации, убедитесь, что image definition и шаблон образа находятся в одном расположении.

versioning

Свойство управления версиями предназначено только для sharedImage типа распространения. Это перечисление с двумя возможными значениями:

  • latest — новая строго увеличивающаяся схема на каждую конструкцию
  • source — схема на основе номера версии исходного образа.

Схема нумерирования версий по умолчанию .latest Последняя схема имеет дополнительное свойство "основной", указывающее основную версию, в которой создается последняя версия.

Note

Существующая логика создания версий для sharedImage распространения устарела. Предоставляются два новых варианта: монотонно увеличивая версии, которые всегда являются последней версией в коллекции, и версии, созданные на основе номера версии исходного образа. Перечисление, указывающее схему создания версий, позволяет расширяться в будущем с дополнительными схемами создания версий.

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

Свойства управления версиями:

  • схема — создание нового номера версии для распространения. Latest или Source два возможных значения.
  • основной — указывает основную версию, в которой создается последняя версия. Применимо только в том случае, если scheme задано значение Latest. Например, в коллекции со следующими версиями: 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
    • При использовании основного не заданного или основного набора 2 Latest схема создает версию 2.1.1.
    • При использовании основного набора 1 последняя схема создает версию 1.2.1
    • При использовании основного набора 0 последняя схема создает версию 0.1.3.

Распространение: VHD

Вы можете записать результат на виртуальный жесткий диск. Затем этот виртуальный жесткий диск можно копировать, использовать для публикации в Azure MarketPlace или использовать с Azure Stack.

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

Поддержка ОС: Windows и Linux.

Параметры распространения на VHD:

  • type — VHD.
  • runOutputName — уникальное имя для идентификации дистрибутива.
  • теги — необязательные теги пары значений ключа пользователя.

Конструктор образов Azure не разрешает пользователю указывать расположение учетной записи хранения, но вы можете запросить состояние runOutputs, чтобы получить это расположение.

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

Note

После создания VHD необходимо как можно скорее скопировать его в другое расположение. VHD хранится в учетной записи хранения во временной группе ресурсов, созданной при отправке шаблона образа в службу "Конструктор образов виртуальных машин Azure". Если вы удалите этот шаблон образа, VHD будет утерян.

В следующем формате JSON образ передается в виде виртуального жесткого диска в пользовательскую учетную запись хранения.

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

VHD распределяет свойства:

URI — необязательный URI службы хранилища Azure для распределенного большого двоичного объекта VHD. Не следует использовать значение по умолчанию (пустая строка), в котором VHD будет опубликован в учетной записи хранения в промежуточной группе ресурсов.

Свойства: оптимизация

Это optimize свойство можно включить при создании образа виртуальной машины и позволяет оптимизации виртуальных машин повысить время создания образа.

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: конфигурация, связанная с процессом загрузки виртуальной машины, используемой для управления оптимизацией, которая может улучшить время загрузки или другие аспекты производительности.
  • состояние: состояние функции оптимизации загрузки в пределах vmBootзначения, Enabled указывающее, что функция включена для улучшения времени создания образа.

Дополнительные сведения см. в статье "Оптимизация виртуальных машин для образов коллекции" с помощью построителя образов виртуальных машин Azure.

Свойства: источник

В разделе source содержатся сведения об исходном образе, который будет использоваться Конструктором образов. Azure Image Builder поддерживает только обобщенные образы в качестве исходных образов, специализированные образы в настоящее время не поддерживаются.

Для API должно быть задано значение SourceType, определяющее источник для сборки образа. В настоящее время существует три типа:

  • PlatformImage — указывает, что источником является образ Marketplace;
  • ManagedImage — используется при запуске из обычного управляемого образа.
  • SharedImageVersion — указывается, когда в качестве источника используется версия образа из Коллекции вычислений Azure.

Note

При использовании существующих пользовательских образов Windows можно выполнять команду Sysprep до трех раз на одном образе Windows 7 или Windows Server 2008 R2 или 1001 раз в одном образе Windows для более поздних версий; Дополнительные сведения см. в документации sysprep .

Источник PlatformImage

Конструктор образов Azure поддерживает образы Windows Server, клиента Windows и Linux из Azure Marketplace. Полный список см. в статье Сведения о Конструкторе образов виртуальных машин Azure.

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

Здесь используются те же свойства, что и при создании виртуальных машин. Чтобы получить список свойств, выполните в интерфейсе командной строки Azure следующую команду.

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

В качестве значения версии можно указать latest, так как версия определяется при сборке образа, а не при отправке шаблона. Если эта функциональная возможность используется с назначением "Коллекция вычислений Azure", можно не отправлять шаблон повторно, а перезапускать сборку образа через определенные интервалы, чтобы ваши образы воссоздавались из самых последних образов.

Поддержка сведений о плане размещения на рынке

Можно также указать сведения о плане, например:

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

Источник ManagedImage

Задает в качестве исходного образа существующий управляемый образ универсального виртуального жесткого диска или виртуальной машины.

Note

Исходный управляемый образ должен иметь поддерживаемую ОС и находиться в той же подписке и регионе, что и ваш шаблон Конструктора образов виртуальных машин Azure.

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

Идентификатор imageId должен быть идентификатором ResourceId управляемого образа. Для получения списка доступных образов используйте команду az image list.

Источник SharedImageVersion

Задает в качестве исходного образа существующую версию образа в Коллекции вычислений Azure.

Note

Исходная версия общего образа должна иметь поддерживаемую ОС, а версия образа должна находиться в том же регионе, что и шаблон Конструктора образов виртуальных машин Azure. В противном случае следует реплицировать версию образа в регион шаблона Конструктора образов.

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId — идентификатор ресурса шаблона ARM версии образа. Если имя версии образа является "последней", версия вычисляется при сборке образа. Он imageVersionId должен быть ResourceId версией образа. Для вывода списка версий образа используйте команду az sig image-version list.

Следующий код JSON задает исходный образ как изображение, хранящееся в общей коллекции direct.

Note

В настоящее время общая коллекция direct находится в предварительной версии.

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

Следующий код JSON задает исходный образ как последнюю версию образа для образа, хранящегося в коллекции вычислений Azure.

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

Свойства SharedImageVersion:

imageVersionId — идентификатор ресурса шаблона ARM версии образа. Если имя версии образа имеет значение "последняя", версия вычисляется при выполнении сборки образа.

Свойства: stagingResourceGroup

Свойство stagingResourceGroup содержит сведения о промежуточной группе ресурсов, которую служба Image Builder создает для использования во время процесса сборки образа. stagingResourceGroup — необязательное свойство для тех, кому нужен более строгий контроль над группой ресурсов, созданной Конструктором образов при сборке образа. Вы можете создать собственную группу ресурсов и указать ее в разделе stagingResourceGroup или задать Конструктору образов задачу создать ее от вашего имени.

Important

Промежуточная группа ресурсов, указанная не может быть связана с другим шаблоном образа, должна быть пустой (без ресурсов внутри), в том же регионе, что и шаблон изображения, и иметь "Участник" или "Владелец" RBAC, примененный к удостоверению, назначенному ресурсу шаблона образа Azure Image Builder. Построитель образов проверяет теги промежуточной группы ресурсов с ключами imageTemplateResourceGroupName и imageTemplateName определяет, использует ли какой-либо шаблон образа промежуточную группу ресурсов. Если эти теги существуют до отправки шаблона изображения или они не соответствуют работающему шаблону образа во время сборки образа, операция завершится ошибкой.

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

Сценарии создания шаблонов

  • Поле stagingResourceGroup остается пустым

    stagingResourceGroup Если свойство не указано или не указано с пустой строкой, служба Image Builder создает промежуточную группу ресурсов с соглашением об имени по умолчанию "IT_**". Промежуточная группа ресурсов имеет теги по умолчанию, примененные к нему: createdBy, , imageTemplateNameimageTemplateResourceGroupName. Кроме того, RBAC по умолчанию применяется к удостоверению, назначенному ресурсу шаблона Конструктора образов Azure, который является участником.

  • Свойство stagingResourceGroup указывается с существующей группой ресурсов

    stagingResourceGroup Если свойство указано с группой ресурсов, которая существует, служба построителя образов проверяет, что группа ресурсов не связана с другим шаблоном изображения, пуста (без ресурсов внутри), в том же регионе, что и шаблон изображения, и имеет RBAC "Участник" или "Владелец", примененный к удостоверению, назначенному ресурсу шаблона образа Конструктора образов Azure. Если какие-либо из указанных выше требований не выполнены, возникает ошибка. В промежуточной группе ресурсов добавлены следующие теги: usedBy, imageTemplateName. imageTemplateResourceGroupName Существующие теги не удаляются.

Important

Вам потребуется назначить роль участника группе ресурсов для субъекта-службы, соответствующего первому приложению Конструктора образов Azure при попытке указать существующую группу ресурсов и виртуальную сеть в службе построителя образов Azure с исходным изображением Windows. Инструкции по назначению роли участника группе ресурсов см. в следующей документации по устранению неполадок построителя образов Azure: ошибка авторизации

  • Свойство stagingResourceGroup указывается с несуществующей группой ресурсов

    stagingResourceGroup Если свойство указано с группой ресурсов, которая не существует, служба Конструктора образов создает промежуточную группу ресурсов с именем, указанным в свойствеstagingResourceGroup. Если указанное имя не соответствует требованиям Azure к именованию групп ресурсов, система выдаст ошибку. Промежуточная группа ресурсов имеет теги по умолчанию, примененные к нему: createdBy, , imageTemplateNameimageTemplateResourceGroupName. По умолчанию удостоверение, назначенное ресурсу шаблона образа Конструктора образов Azure, применяет к нему RBAC участника в группе ресурсов.

Удаление шаблона

Все промежуточные группы ресурсов, созданные службой Конструктора образов, будут удалены после удаления шаблона образа. Будут удалены промежуточные группы ресурсов, указанные в свойстве stagingResourceGroup, но не существующие до сборки образа.

Если Конструктор образов не создал промежуточную группу ресурсов, но создал ресурсы в этой группе, такие ресурсы будут удалены после удаления шаблона образа, если у службы Конструктора образов есть соответствующие разрешения или роли, требуемые для удаления ресурсов.

Свойства: проверка

Свойство validate можно использовать для проверки образов платформы и любых настраиваемых образов, создаваемых независимо от того, использовали ли вы для их создания Конструктор образов Azure.

Конструктор образов Azure поддерживает режим "Только проверка источника", который можно задать с помощью свойства sourceValidationOnly. Если для свойства sourceValidationOnly задано значение true, образ, указанный в разделе source, будет проверено напрямую. Для создания и проверки настроенного образа отдельная сборка выполняться не будет.

Свойство inVMValidations принимает список проверяющих средств управления, которые будут выполняться в образе. Построитель образов Azure поддерживает проверки файлов, PowerShell и Shell.

Свойство continueDistributeOnFailure отвечает за распространение выходных образов при сбое проверки. По умолчанию, если проверка завершается ошибкой, а для этого свойства задано значение false, выходные образы не будут распространяться. Если проверка завершится сбоем, а для этого поля задано значение true, выходные образы будут распространяться. Используйте этот параметр с осторожностью, так как его использование может привести к распространению образов с ошибкой. При использовании любого из значений (true или false) запуск образа завершится сбоем при сбое проверки. Это свойство не влияет на успешность проверки.

Применяя validate, помните следующие правила.

  • Можно использовать несколько средств проверки
  • Проверяющие элементы управления выполняются в порядке, указанном в шаблоне.
  • В случае сбоя одного из проверяющих элементов управления происходит сбой всего компонента проверки и выводится сообщение об ошибке.
  • Рекомендуется тщательно протестировать скрипт, прежде чем использовать его в шаблоне. Гораздо проще отладить скрипт на собственной виртуальной машине.
  • Не включайте в скрипты конфиденциальные данные.
  • Расположения скриптов должны быть общедоступными, если вы не используете MSI.

Использование свойства validate для проверки образов 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 свойства:

  • type — PowerShell.

  • name — имя проверяющего элемента

  • scriptUri — URI файла скрипта PowerShell.

  • inline — массив команд для выполнения, разделенных запятыми.

  • validExitCodes — необязательные допустимые коды, которые можно вернуть из команды script/inline, это позволяет избежать сбоя скрипта или встроенной команды.

  • runElevated — необязательно, логическое значение, поддержка выполнения команд и сценариев с повышенными разрешениями.

  • sha256Checksum — значение контрольной суммы sha256 файла, создается локально, а затем построитель образов будет проверять и проверять.

    Создание sha256Checksum с помощью PowerShell в Windows Get-Hash

Использование свойства validate для проверки образов 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 свойства:

  • тип — оболочка или файл, указанные в качестве типа проверки для выполнения.

  • name — имя проверяющего элемента

  • scriptUri — URI файла скрипта

  • inline — массив команд для выполнения, разделенных запятыми.

  • sha256Checksum — значение контрольной суммы sha256 файла, создается локально, а затем построитель образов будет проверять и проверять.

    Чтобы сформировать sha256Checksum, откройте окно терминала в Mac/Linux и выполните следующую команду: sha256sum <fileName>

  • назначение — назначение файла.

  • sha256Checksum — указывает контрольную сумму SHA256 файла.

  • sourceUri — исходный URI файла.

Свойства: vmProfile

Дополнительные сведения о конфигурации, связанной с сетью, см. в разделе " Параметры сети" в Конструкторе образов виртуальных машин Azure.

vmSize (необязательно)

Конструктор образов будет по умолчанию использовать размер SKU Standard_D1_v2 для образов 1-го поколения и Standard_D2ds_v4 — для образов 2-го поколения. Поколение соответствует образу, указанному в source. Вы можете переопределить vmSize по следующим причинам:

  • Выполнение настроек, требующих большего объема памяти, ЦП и обработки больших файлов (ГБ).
  • При выполнении сборок Windows следует использовать "Standard_D2_v2" или эквивалентный размер виртуальной машины.
  • Требовать изоляцию виртуальной машины.
  • Настройте образ, для которого требуется определенное оборудование. Например, для виртуальной машины с GPU нужно указать размер виртуальной машины с GPU.
  • Требовать завершение шифрования неактивных виртуальных машин сборки, необходимо указать размер виртуальной машины сборки поддержки, которая не использует локальные временные диски.

osDiskSizeGB

По умолчанию Конструктор образов не будет изменять размер образа, а будет использовать размер исходного образа. При необходимости можно увеличить только размер диска ОС (Win и Linux), а значение 0 означает, что размер исходного образа совпадает с размером 0. Размер диска ОС нельзя уменьшить до размера, меньшего, чем у исходного образа.

{
  "osDiskSizeGB": 100
}

vnetConfig (необязательно)

Если свойства виртуальной сети не указаны, построитель образов создает собственную виртуальную сеть, общедоступный IP-адрес и группу безопасности сети (NSG). Общедоступный IP-адрес используется для обмена данными между службой и виртуальной машиной сборки. Если вы не хотите указывать общедоступный IP-адрес или хотите, чтобы Конструктор образов мог обращаться к существующим ресурсам вашей виртуальной сети, таким как серверы конфигурации (DSC, Chef, Puppet, Ansible) и общим папкам, вы можете указать виртуальную сеть. Дополнительные сведения см. в документации по сети.

"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

Идентификатор ресурса предварительно существующей подсети, в которой развернута виртуальная машина сборки и виртуальная машина проверки. Если какие-либо скрипты настройки или проверки, выполняемые на виртуальных машинах сборки или проверки, требуют исходящего доступа, эта подсеть также должна разрешить такой доступ.

containerInstanceSubnetId (необязательно)

Идентификатор ресурса предварительно существующей подсети, в которой развернут экземпляр контейнера Azure (ACI) для изолированных сборок. Если это поле не указано, то временный виртуальная сеть вместе с подсетями и группами безопасности сети развертывается в промежуточной группе ресурсов в дополнение к другим сетевым ресурсам (частная конечная точка, Приватный канал служба, Azure Load Balancer и виртуальная машина прокси-сервера) для включения связи между ACI и виртуальной машиной сборки.

[Это свойство доступно только в версиях API или более новых, хотя существующие шаблоны, созданные с использованием более ранних 2024-02-01 версий API, можно обновить, чтобы указать это свойство.]

Это поле можно указать только в том случае, если subnetId он также указан и должен соответствовать следующим требованиям:

  • Эта подсеть должна находиться в той же виртуальная сеть, что и подсеть, указанная в subnetId.
  • Эта подсеть не должна совпадать с подсетью, указанной в subnetId.
  • Эту подсеть необходимо делегировать службе ACI, чтобы ее можно было использовать для развертывания ресурсов ACI. Дополнительные сведения о делегировании подсети для служб Azure см. здесь. Сведения о делегировании конкретной подсети ACI доступны здесь.
  • Эта подсеть должна разрешать исходящий доступ к Интернету и подсети, указанной в subnetId. Эти доступы необходимы для подготовки ACI, и он может взаимодействовать с виртуальной машиной сборки для выполнения настроек или проверок. В другом конце подсеть, указанная в subnetId этой подсети, должна разрешать входящий доступ из этой подсети. Как правило, правила безопасности по умолчанию групп безопасности сети Azure (NSG) разрешают эти доступы. Однако при добавлении дополнительных правил безопасности в группы безопасности группы безопасности необходимо разрешить следующие доступы:
    1. Исходящий доступ из подсети, указанной в containerInstanceSubnetId :
      1. В Интернет через порт 443 (для подготовки образа контейнера).
      2. В Интернет через порт 445 (для подключения общей папки из служба хранилища Azure).
      3. Для подсети, указанной в subnetId порту 22 (для ssh/Linux) и порта 5986 (для WinRM/Windows) (для подключения к виртуальной машине сборки).
    2. Входящий доступ к подсети, указанной в subnetId:
      1. Для порта 22 (для ssh/Linux) и порта 5986 (для WinRM/Windows) из подсети, указанной в containerInstanceSubnetId (для ACI для подключения к виртуальной машине сборки).
  • Удостоверение шаблона должно иметь разрешение на выполнение действия Microsoft.Network/virtualNetworks/subnets/join/action в области этой подсети. Дополнительные сведения о разрешениях Azure для сети см. здесь.

proxyVmSize (необязательно)

Размер виртуальной машины прокси-сервера, используемой для передачи трафика на виртуальную машину сборки и проверку виртуальной машины. Это поле не должно быть указано, если containerInstanceSubnetId он указан, так как в этом случае виртуальная машина прокси-сервера не развертывается. Опустить или указать пустую строку, чтобы использовать значение по умолчанию (Standard_A1_v2).

Свойства: автозапуск

Свойство можно использовать autoRun для управления тем, должен ли процесс сборки шаблона образа автоматически запускаться при создании шаблона. Это перечисление с двумя возможными значениями:

  • Включена функция автоматического запуска, поэтому процесс сборки шаблона образа автоматически запускается при создании шаблона.
  • Отключен . Автоматическое выполнение отключено, поэтому после создания шаблона необходимо вручную запустить процесс сборки образа.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Note

Если задано значение autoRun "Включено", процесс сборки образа выполняется сразу после создания шаблона. Это гарантирует, что начальная сборка образа выполняется легко. Однако он не предоставляет согласованные и текущие сборки образов. Для согласованных и текущих сборок образов, выполняемых после обновления шаблона образа, см. инструкции по настройке автоматической сборки образа с помощью триггеров построителя образов Azure.

В отличие от autoRunавтоматического создания образа с помощью ресурса триггера построителя образов Azure, сборки образов выполняются согласованно. При изменении шаблона служба Конструктора образов Azure автоматически активирует процесс сборки образа.

Выберите autoRun немедленное создание образа при создании шаблона. Выберите автоматическое создание образа, если требуется постоянная согласованность в сборках образов. Рассмотрите конкретные требования и используйте соответствующий вариант на основе рабочего процесса.

Свойства: managedResourceTags

Свойство можно использовать managedResourceTags для применения тегов к ресурсам, создаваемым службой Azure Image Builder в промежуточной группе ресурсов во время сборки образа. Дополнительные сведения о промежуточной группе ресурсов см. в разделе "Обзор построителя образов Azure"

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

Операции с шаблонами образов

Запуск сборки образа

Чтобы запустить сборку, необходимо вызвать командлет Run в ресурсе шаблона образа, примеры команд run:

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

Отмена сборки образа

Если вы запускаете сборку образа, которая, по вашему мнению, некорректна, ожидает ввода пользователем данных или, по вашему мнению, никогда не завершится успешно, вы можете отменить сборку.

Сборку можно отменить в любое время. Если этап распространения запущен, вы все равно можете отменить, но вам нужно очистить все образы, которые могут не быть завершены. Команда отмены не ожидает завершения отмены, отслеживайте lastrunstatus.runstate ход отмены, используя эти команды состояния.

Примеры команд cancel могут выглядеть так:

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

Дальнейшие шаги

В библиотеке GitHub в разделе Конструктора образов Azure имеются примеры JSON-файлов для разных сценариев.

  • Last updated on