Создание пользовательских артефактов для виртуальной машины DevTest Labs

Статья
09/30/2023

В этой статье описывается создание пользовательских файлов артефактов для виртуальных машин Azure DevTest Labs. Артефакты DevTest Labs указывают действия, которые необходимо выполнить для инициализации виртуальной машины. Артефакт состоит из файла определения артефакта и других файлов скриптов, которые хранятся в папке в репозитории Git.

Сведения о добавлении репозиториев артефактов в лаборатории см. в статье Добавление репозитория артефактов в лабораторию.
Дополнительные сведения о добавлении артефактов, создаваемых на виртуальных машинах, см. в статье Добавление артефактов в виртуальные машины DevTest Labs.
Сведения об указании обязательных артефактов для добавления во все виртуальные машины лаборатории см. в разделе Указание обязательных артефактов для виртуальных машин DevTest Labs.

Файлы определения артефактов

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

В следующем примере показаны разделы, составляющие базовую структуру файла определения артефакта artifactfile.json:

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "",
    "description": "",
    "iconUri": "",
    "targetOsType": "",
    "parameters": {
      "<parameterName>": {
        "type": "",
        "displayName": "",
        "description": ""
      }
    },
    "runCommand": {
      "commandToExecute": ""
    }
  }

Имя элемента	Описание
`$schema`	Расположение файла схемы JSON, позволяющего проверять подлинность файла определения.
`title`	Имя артефакта, которое нужно отобразить в лаборатории. Обязательный.
`description`	Описание артефакта, которое нужно отобразить в лаборатории. Обязательный.
`iconUri`	Универсальный код ресурса (URI) значка артефакта, отображаемого в лаборатории.
`targetOsType`	Операционная система виртуальной машины, на которой необходимо установить артефакт. Поддерживаемые значения: `Windows`, `Linux`. Обязательный.
`parameters`	Значения для настройки артефакта при установке на виртуальной машине.
`runCommand`	Команда установки артефакта для выполнения на виртуальной машине. Обязательный.

Параметры артефакта

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

Параметры определяются с помощью следующей структуры.

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

Имя элемента	Описание
`type`	Тип значения параметра. Обязательный.
`displayName`	Название параметра, отображаемого для пользователя лаборатории. Обязательный.
`description`	Описание параметра, отображаемого для пользователя лаборатории. Обязательный.

Допустимые типы значений параметров:

Тип	Описание
`string`	Любая допустимая строка JSON
`int`	Любое допустимое целое число JSON
`bool`	Любое допустимое логическое значение JSON
`array`	Любой допустимый массив JSON

Секреты в качестве защищенных строк

Чтобы объявить секреты как защищенные строковые параметры с маскированными символами в пользовательском интерфейсе, используйте этот синтаксис в разделе parameters файла artifactfile.json:


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

команда установки артефакта для выполнения скрипта PowerShell, который принимает защищенную строку, созданную с помощью команды ConvertTo-SecureString.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

Не записывайте секреты в консоль, так как скрипт фиксирует выходные данные для отладки пользователей.

Выражения и функции артефактов

Для ограничения команды установки артефактов можно использовать выражения и функции. Выражения оцениваются при установке артефакта. Выражения могут встречаться в любом месте строкового значения JSON и всегда возвращают другое значение JSON. Заключите выражения в квадратные скобки []. Если нужно использовать строковый литерал, который начинается с квадратной скобки, необходимо указать две квадратные скобки: [[.

Как правило, для составления значения используются выражения с функциями. Вызовы функций форматируются как functionName(arg1, arg2, arg3).

К общим функциям относятся:

Функция	Описание
`parameters(parameterName)`	Возвращает значение параметра, которое необходимо указать при выполнении команды артефакта.
`concat(arg1, arg2, arg3, ...)`	объединяет несколько строковых значений. Эта функция может принимать различные аргументы.

В примере ниже для создания значения используются выражения и функции:

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

Создание пользовательского артефакта

Для создания пользовательского артефакта:

Установите редактор JSON для работы с файлами определения артефакта. Visual Studio Code доступен для Windows, Linux и macOS.
Начните с примера файла определения artifactfile.json.

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

В этой статье используется файл определения artifactfile.json и сценарий artifact.ps1 PowerShell в https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.
Используйте технологию IntelliSense для просмотра допустимых элементов и вариантов значений, которые можно применять для создания файла определения артефакта. Например, при редактировании элемента targetOsType IntelliSense предлагает два варианта: Windows или Linux.
Сохраняйте артефакты в общедоступных или частных репозиториях артефактов Git.
- Сохраните каждый файл определения артефакта artifactfile.json в отдельном каталоге, имя которого совпадает с именем артефакта.
- Сохраните скрипты, на которые команда установки ссылается в том же каталоге, что и файл определения артефакта.
На следующем снимке экрана показан пример папки артефактов:
Чтобы сохранить пользовательские артефакты в общедоступном репозитории артефактов DevTest Labs, откройте запрос на вытягивание для репозитория.
Сведения о добавлении частного репозитория артефактов в лабораторию см. в статье Добавление репозитория артефактов в лабораторию в DevTest Labs.

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

Создание пользовательских артефактов для виртуальной машины DevTest Labs

Файлы определения артефактов

Параметры артефакта

Секреты в качестве защищенных строк

Выражения и функции артефактов

Создание пользовательского артефакта

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

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

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