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

Статья
08/24/2024

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

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

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

JSON
Bicep

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

resource azureImageBuilder 'Microsoft.VirtualMachineImages/imageTemplates@2022-02-14' = {
  name: azureImageBuilderName
  location: '<region>'
  tags:{
    <name>: '<value>'
    <name>: '<value>'
  }
  identity:{}
  properties:{
    buildTimeoutInMinutes: <minutes>
    customize: []
    distribute: []
    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 — это тип ресурса, который должен быть Microsoft.VirtualMachineImages/imageTemplates.

JSON
Bicep

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

resource azureImageBuilder 'Microsoft.VirtualMachineImages/imageTemplates@2022-02-14' = {}

Расположение

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

Восточная часть США
Восточная часть США 2
Центрально-западная часть США
Западная часть США
западная часть США 2
Западная часть США — 3
Центрально-южная часть США
Северная Европа
Западная Европа
Юго-Восточная Азия
Юго-Восточная часть Австралии
Восточная Австралия
южная часть Соединенного Королевства
западная часть Соединенного Королевства
Южная Бразилия
Центральная Канада
Центральная Индия
Центральная часть США
Центральная Франция
Центрально-Западная Германия
Восточная Япония
Центрально-северная часть США
Восточная Норвегия;
Северная Швейцария
Западная Индия Jio
Северная часть ОАЭ;
Восточная Азия
Республика Корея, центральный регион
Северная часть ЮАР
Центральный Катар
USGov Аризона (общедоступная предварительная версия);
USGov Вирджиния (общедоступная предварительная версия).
Китай Северная 3 (общедоступная предварительная версия)
Центральная Швеция
Центральная Польша
Северная Италия
Израиль, центральный регион

Внимание

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

Внимание

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

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

Azure PowerShell
Azure CLI

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

az feature register --namespace Microsoft.VirtualMachineImages --name FairfaxPublicPreview

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

Azure PowerShell
Azure CLI

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

az feature register --namespace Microsoft.VirtualMachineImages --name MooncakePublicPreview

JSON
Bicep

"location": "<region>"

location: '<region>'

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

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

Избыточность между зонами

Дистрибутив поддерживает избыточность между зонами, виртуальные жесткие диски распределяются в учетную запись хранения с избыточностью между зонами по умолчанию, а версия Коллекции вычислений Azure (прежнее название — Общая коллекция образов) будет поддерживать тип хранилища ZRS, если он указан.

Идентификация

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

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

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

JSON
Bicep

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

identity:{
  type:'UserAssigned'
  userAssignedIdentities:{
    '<imgBuilderId>': {}
  }
}

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

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

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

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

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

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

Примечание.

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

JSON
Bicep

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

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

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

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

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

Раздел customize — это массив. Поддерживаемые типы настройщика: File, PowerShell, Shell, WindowsRestart и WindowsUpdate.

JSON
Bicep

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

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

Настройщик Shell поддерживает выполнение скриптов оболочки в Linux. Скрипты оболочки должны быть общедоступными или необходимо настроить MSI, чтобы Конструктор образов виртуальных машин Azure мог получить к ним доступ.

JSON
Bicep

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

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

Свойства раздела customize:

type — Shell.
name — имя для отслеживания настройки.
scriptUri — универсальный код ресурса (URI) для расположения файла.
inline — массив команд оболочки, разделенных запятыми.
sha256Checksum — значение контрольной суммы sha256 файла; вы формируете его локально, а Конструктор образов затем проверяет его.

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

Примечание.

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

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

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

JSON
Bicep

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

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 и дождаться, пока она снова будет подключена. Этот настройщик позволит вам установить программное обеспечение, требующее перезагрузки.

JSON
Bicep

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

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

Свойства раздела customize:

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

Примечание.

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

Настройщик PowerShell

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

JSON
Bicep

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

type — PowerShell.
scriptUri — универсальный код ресурса (URI) для расположения файла скрипта PowerShell.
inline — встроенные команды, разделенные запятыми.
validExitCodes — необязательные допустимые коды, которые можно возвращать из скрипта или встроенной команды. Свойство позволяет избежать сбоя скрипта или встроенной команды.
runElevated — необязательное логическое значение для поддержки выполнения команд и скриптов с повышенными привилегиями.
runAsSystem — необязательный, логический, определяет, должен ли скрипт PowerShell выполняться от имени системного пользователя.
sha256Checksum — создайте контрольную сумму SHA256 локально, укажите значение контрольной суммы в символах нижнего регистра, и конструктор образов проверит контрольную сумму во время развертывания шаблона образа.

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

Настройщик File

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

JSON
Bicep

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

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

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

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

Примечание.

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

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

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

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

Примечание.

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

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

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

Настройщик WindowsUpdate

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

JSON
Bicep

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

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

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

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

Примечание.

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

Обобщение

По умолчанию Конструктор образов виртуальных машин 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 позволяет настроить способ обработки ошибок во время создания образа.

JSON
Bicep

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

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

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

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

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

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

Свойства: distribute

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

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

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

Примечание.

Стандартная команда Конструктора образов 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

Выходные данные:

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

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

JSON
Bicep

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

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

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

type — ManagedImage
imageId — идентификатор ресурса целевого образа; ожидаемый формат: /subscriptions/<ИД_подписки>/resourceGroups/<имя_целевой_группы_ресурсов>/providers/Microsoft.Compute/images/<имя_образа>.
location — расположение управляемого образа.
runOutputName — уникальное имя для идентификации распространения.
artifactTags — необязательные задаваемые пользователем теги "ключ — значение".

Примечание.

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

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

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

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

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

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

Примечание.

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

JSON
Bicep

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

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

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

JSON
Bicep

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

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

Примечание.

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

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

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

JSON
Bicep

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

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 — необязательные задаваемые пользователем теги "ключ — значение".
replicationRegions — массив регионов для репликации. Один из регионов должен быть регионом, в котором развернута коллекция. Добавление регионов означает увеличение времени сборки, так как сборка не завершится до завершения репликации. Это поле устарело по состоянию на API версии 2022-07-01, используйте targetRegions при распространении типа SharedImage.
targetRegions — массив регионов для репликации. Он недавно появился в рамках API 2022-07-01 и применяется только к распространению SharedImage типов.
excludeFromLatest (необязательный) — позволяет пометить созданную версию образа как последнюю версию в определении коллекции; значение по умолчанию — false.
storageAccountType (необязательный) — Конструктор образов Azure позволяет указывать следующие типы хранилища для создаваемой версии образа:
- "Standard_LRS"
- "Standard_ZRS",

Примечание.

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

управление версиями

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

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

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

Примечание.

Существующая логика создания версий для 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.

JSON
Bicep

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

{
  type: 'VHD'
  runOutputName: '<VHD name>'
  artifactTags: {
      <name>: '<value>'
      <name>: '<value>'
  }
}

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

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

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

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

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

Примечание.

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

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

JSON
Bicep

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

resource distribute 'Microsoft.Compute/galleries/images/runOutputs' = {
  name: '<VHD name>'
  properties: {
    type: 'VHD'
    artifactTags: {
      '<name>': '<value>'
      '<name>': '<value>'
    }
    uri: '<replace with Azure storage URI>'
  }
}

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

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

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

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

JSON
Bicep

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }

optimize: {
      vmBoot: {
        state: 'Enabled'
      }
    }

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

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

Свойства: source

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

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

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

Примечание.

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

Источник PlatformImage

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

JSON
Bicep

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

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", можно не отправлять шаблон повторно, а перезапускать сборку образа через определенные интервалы, чтобы ваши образы воссоздавались из самых последних образов.

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

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

JSON
Bicep

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

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

Источник ManagedImage

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

Примечание.

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

JSON
Bicep

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

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

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

Источник SharedImageVersion

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

Примечание.

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

JSON
Bicep

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}

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.

Примечание.

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

JSON
Bicep

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

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

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

JSON
Bicep

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

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 или задать Конструктору образов задачу создать ее от вашего имени.

Внимание

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

JSON
Bicep

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

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

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

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

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

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

Внимание

Вам потребуется назначить роль участника группе ресурсов для субъекта-службы, соответствующего первому приложению Конструктора образов 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:

JSON
Bicep

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

{
  properties: {
    validate: {
      continueDistributeOnFailure: false
      sourceValidationOnly: false
      inVMValidations: [
        {
          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:

JSON
Bicep

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

{
  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>'
        }
      ]
    }
  }
}

inVMValidations свойства:

тип — оболочка или файл, указанные в качестве типа проверки для выполнения.
name — имя проверяющего элемента управления
scriptUri — URI файла сценария
inline — массив подлежащих выполнению команд, разделенных запятыми.
sha256Checksum — значение контрольной суммы sha256 файла; вы формируете ее локально, а Конструктор образов затем проверяет ее.

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

Свойства: vmProfile

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

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

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

osDiskSizeGB

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

JSON
Bicep

{
  "osDiskSizeGB": 100
}

  osDiskSizeGB: 100

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

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

JSON
Bicep

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

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

Примечание.

Если задано значение 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

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

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

Сборку можно отменить в любое время. Если этап распространения запущен, вы все равно можете отменить, но вам нужно очистить все образы, которые могут не быть завершены. Команда Cancel не ждет, когда завершится отмена. Для этого отслеживайте ход отмены в 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-файлов для разных сценариев.

Поделиться через

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

Версия API

Тип

Расположение

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

Избыточность между зонами

Теги

Идентификация

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

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

Свойства: buildTimeoutInMinutes

Свойства: customize

Настройщик Shell

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

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

Настройщик PowerShell

Настройщик File

Настройщик WindowsUpdate

Обобщение

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

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

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

Свойства: errorHandling

Свойства: distribute

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

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

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

управление версиями

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

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

Свойства: source

Источник PlatformImage

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

Источник ManagedImage

Источник SharedImageVersion

Свойства: stagingResourceGroup

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

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

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

Свойства: vmProfile

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

osDiskSizeGB

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

subnetId

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

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

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

Свойства: managedResourceTags

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

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

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

Следующие шаги

Обратная связь

Дополнительные ресурсы