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

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

Артефакты — это инструменты, действия или программное обеспечение, которые можно добавить в виртуальные машины Azure DevTest Labs. Например, артефакты могут выполнять скрипты, устанавливать средства или выполнять такие действия, как присоединение к домену. Пользователи DevTest Labs могут добавлять артефакты на виртуальные машины, а администраторы лабораторий могут указывать обязательные артефакты, которые будут добавлены ко всем виртуальным машинам лаборатории.

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

Предпосылки

  • Чтобы создать и работать с файлами определения артефактов, вам потребуется редактор JSON. Visual Studio Code доступен для Windows, Linux и macOS.
  • Чтобы сохранить файлы определения артефактов и скриптов, требуется учетная запись GitHub.

Общие сведения о файлах определения артефактов

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

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

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

Определение содержит следующие обязательные и необязательные элементы:

Имя элемента Description
$schema Расположение файла схемы JSON, который поможет проверить допустимость файла определения.
title Необходимое имя артефакта для отображения.
description Обязательное описание артефакта.
iconUri URI значка артефакта для отображения.
targetOsType Требуется операционная система для установки. Поддерживаемые значения : Windows или Linux.
parameters Доступные настройки артефактов во время установки.
runCommand Требуется команда для установки артефакта на виртуальной машине.

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

В parameters разделе файла определения определяются параметры и значения, которые пользователи могут указать при установке артефакта. Можно обратиться к этим параметрам в разделе runCommand.

Следующая структура определяет параметр:

  "parameters": {
    "<name>": {
      "type": "<type>",
      "displayName": "<display name>",
      "description": "<description>"
    }
  }

Для каждого параметра требуется имя, и для определения параметра требуются следующие элементы:

Имя элемента Description
type Обязательный тип значения параметра. Тип может быть любым допустимым JSON string, целым числом int, логическим bool или array.
displayName Необходимое имя параметра для отображения пользователю.
description Обязательное описание параметра.

Безопасные параметры строки

Чтобы включить секреты в определение артефакта, объявите секреты как безопасные строки с помощью secureStringParam синтаксиса в parameters разделе файла определения. Элемент description разрешает любую текстовую строку, включая пробелы, и представляет строку в пользовательском интерфейсе как маскированные символы.


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "<any text string>",
      "allowEmpty": false
    },

В следующем runCommand примере используется сценарий 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).

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

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

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

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

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

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

  1. Скачайте скрипт PowerShell artifact.ps1 и файл определения artifactfile.json из https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  2. Измените файл определения артефакта, чтобы внести некоторые допустимые изменения в элементы и значения. В Visual Studio Code можно использовать IntelliSense для просмотра допустимых элементов и параметров значения. Например, при редактировании элемента targetOsType IntelliSense показывает Windows или Linux варианты.

  3. Сохраните артефакт в общедоступном или частном репозитории артефактов Git.

    • Сохраните каждый artifactfile.json файл определения артефакта в отдельном каталоге с именем артефакта.
    • Сохраните скрипты, ссылки на которые команда установки ссылается в том же каталоге, что и файл определения артефакта.

    На следующем снимка экрана показан пример папки артефактов:

    Снимок экрана: пример папки артефактов.

    Замечание

    Чтобы добавить пользовательские артефакты в общедоступный репозиторий артефактов DevTest Labs, откройте pull request для репозитория.

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

Связанный контент

  • Last updated on