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

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

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

Ниже приведен базовый формат шаблона.

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "apiVersion": "2021-10-01",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "vmProfile": {
      "vmSize": "<vmSize>",
      "proxyVmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
      },
"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>",
  ...
    ]
    },
    "source": {},
    "customize": [],
    "validate": {},
    "distribute": []
  }
}

Тип и версия API

type — это тип ресурса, который должен быть "Microsoft.VirtualMachineImages/imageTemplates". apiVersion со временем будет меняться по мере изменений API, но сейчас должно быть указано значение "2021-10-01".

"type": "Microsoft.VirtualMachineImages/imageTemplates",
"apiVersion": "2021-10-01",

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

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

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

Важно!

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

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

az feature register --namespace Microsoft.VirtualMachineImages --name FairfaxPublicPreview
"location": "<region>",

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

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

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

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

vmProfile

buildVM

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

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

Водить описание не обязательно.

osDiskSizeGB

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

{
  "osDiskSizeGB": 100
},

vnetConfig

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

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

Теги

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

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

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

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

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

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

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

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

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

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

Это поле доступно только в API 2021-10-01 и более поздних версий.

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

Примечание

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

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

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

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

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

Свойства: stagingResourceGroup

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

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

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

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

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

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

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

Поле stagingResourceGroup указывается с НЕСУЩЕСТВУЮЩЕЙ группой ресурсов

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

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

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

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

Свойства: source

В разделе source содержатся сведения об исходном образе, который будет использоваться Конструктором образов. В настоящее время Конструктор образов обеспечивает встроенную поддержку только для создания образов Hyper-V (поколение 1) 1 в Коллекции вычислений Azure (SIG) или управляемых образов. Если вы хотите создать образы 2-го поколения, необходимо использовать исходный образ 2-го поколения и распространить его на виртуальный жесткий диск. После этого потребуется создать управляемый образ из виртуального жесткого диска и вставить его в SIG в качестве образа 2-го поколения.

Для 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.

"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

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

Примечание

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

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

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

Источник SharedImageVersion

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

Примечание

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

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

Идентификатор imageVersionId должен быть идентификатором ResourceId версии образа. Для вывода списка версий образа используйте команду az sig image-version list.

Свойства: buildTimeoutInMinutes

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

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

Если вы не указали значение свойства buildTimeoutInMinutes или задали значение 0, будет использоваться значение по умолчанию. Это значение можно увеличивать или уменьшать; максимальное значение составляет 960 минут (16 часов). Для Windows не рекомендуется устанавливать значение меньше 60 минут. Если вы обнаружили, что возникла пауза, просмотрите журналы — возможно, на этом этапе настройки ожидается какое-нибудь действие, например ввод данных пользователем.

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

Примечание

Если не задать значение 0, минимальное поддерживаемое значение — 6 минут. Использование значений от 1 до 5 приведет к сбою.

Свойства: customize

Конструктор образов поддерживает несколько настройщиков (customizers). Настройщики — это функции, используемые для настройки образа. Это может быть, например, выполнение сценариев или перезагрузка серверов.

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

  • Можно использовать несколько различных настройщиков
  • Настройщики выполняются в порядке, указанном в шаблоне.
  • В случае сбоя одного из настройщиков происходит сбой всего компонента настройки и выводится сообщение об ошибке.
  • Рекомендуется тщательно протестировать скрипт, прежде чем использовать его в шаблоне. Гораздо проще отладить скрипт на собственной виртуальной машине.
  • Не помещайте в скрипты конфиденциальные данные.
  • Расположения скриптов должны быть общедоступными, если не используется MSI.
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<path to script>",
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "Shell",
    "name": "<name>",
    "inline": [
        "<command to run inline>",
    ]
  }
],

Раздел настройки представляет собой массив. Конструктор образов виртуальных машин Azure будет выполнять настройщики в последовательном порядке. Любой сбой в каком-либо из настройщиков приведет к сбою всего процесса сборки.

Примечание

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

Настройщик Shell

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

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

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

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

  • type — Shell.

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

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

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

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

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

Примечание

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

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

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

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

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

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

Перезапуск Linux

Настройщик перезапуска Linux отсутствует. Если вы устанавливаете драйверы или компоненты, требующие перезагрузки, вы можете установить их и вызвать перезагрузку с помощью настройщика оболочки. Время ожидания SSH для виртуальной машины сборки составляет 20 минут.

Настройщик PowerShell

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

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

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

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

  • type — PowerShell.

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

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

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

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

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

    Для формирования sha256Checksum используйте командлет PowerShell в Windows Get-Hash

Настройщик File

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

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

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

Свойства настройщика 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.

Настройщик WindowsUpdate

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

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

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

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

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

Generalize

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

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

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

Если Конструктор образов виртуальных машин Azure успешно создает пользовательский образ Windows, а вы создаете на его основе виртуальную машину и затем обнаруживаете, что произошла ошибка или создание завершилось неудачно, вам следует просмотреть документацию по Windows Server Sysprep или отправить запрос в группу поддержки клиентов Windows Server Sysprep, где вам помогут устранить неполадки и дадут рекомендации по правильному использованию 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 }
Write-Output '>>> Sysprepping VM ...'
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
& $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

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

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

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

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

Поле inVMValidations принимает список проверяющих элементов управления, которые будут выполняться на образе. Конструктор образов Azure поддерживает проверяющие элементы управления PowerShell и Оболочки.

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

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

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

Использование свойства validate для проверки изображений Windows

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

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

inVMValidations свойства:

  • type — Shell.

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

  • scriptUri — URI файла сценария

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

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

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

Свойства: distribute

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

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

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

Примечание

Стандартная команда AIB 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=2021-10-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

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

{
  "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 состоит из следующих компонентов:

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

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

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  },
  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]
}

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

  • 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 — массив регионов для репликации. Один из регионов должен быть регионом, в котором развернута коллекция. Добавление регионов приведет к увеличению времени сборки, так как сборка не завершится до окончания репликации.

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

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

    • "Standard_LRS"
    • "Standard_ZRS"

Примечание

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

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

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

{
  "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 будет утерян.

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

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

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

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Run -Force
az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

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

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

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

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

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Cancel -Force
az resource invoke-action \
     --resource-group $imageResourceGroup \
     --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
     -n helloImageTemplateLinux01 \
     --action Cancel

Дальнейшие действия

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