Интеграция собственных средств сборки, тестирования и развертывания со службой Code Stream

Пользователь с правами разработчика или администратора DevOps может создавать настраиваемые сценарии, расширяющие возможности Code Stream.

С помощью таких сценариев службу Code Stream можно интегрировать с собственными средствами непрерывной интеграции (Continuous Integration, CI) и непрерывного предоставления (Continuous Delivery, CD), а также API-интерфейсами для сборки, тестирования и развертывания приложений. Настраиваемые сценарии особенно полезны в случаях, когда API-интерфейсы приложений не размещаются в общем доступе.

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

Рабочая область конвейера Code Stream поддерживает Docker и Kubernetes для выполнения задач непрерывной интеграции и настраиваемых задач.

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

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

Созданные сценарии хранятся в экземпляре Code Stream. Можно импортировать код YAML для создания настраиваемой интеграции или экспортировать сценарий в виде файла YAML, чтобы использовать его в другом экземпляре Code Stream.

Опубликованная версия сценария выполняется в рамках настраиваемой задачи конвейера. Если опубликованных версий несколько, можно указать, что одна из них является последней, чтобы при выборе настраиваемой задачи она отображалась как latest -->.

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

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

Табл. 1. После написания настраиваемого сценария
Действия...	Сведения о действии...
Добавьте настраиваемую задачу в конвейер.	Настраиваемая задача: выполняется в том же контейнере, что и другие задачи CI в конвейере; содержит входные и выходные переменные, значения которых заполняются сценарием перед тем, как конвейер запустит выполнение настраиваемой задачи; поддерживает несколько типов данных и различные типы метаданных, определяемых в качестве входных и выходных данных в сценарии.
Выберите сценарий в настраиваемой задаче.	Объявите входные и выходные свойства в сценарии.
Сохраните конвейер, затем включите и запустите его.	В ходе работы конвейера настраиваемая задача вызывает указанную версию сценария и запускает его бизнес-логику. В результате ваше средство сборки, тестирования и развертывания интегрируется со службой Code Stream.
После завершения работы конвейера просмотрите сведения о выполнении задач и этапов.	Убедитесь, что результаты работы конвейера соответствуют ожиданиям.

При использовании настраиваемой задачи, которая вызывает версию настраиваемой интеграции, можно добавить настраиваемые переменные среды в качестве пар «имя — значение» на вкладке Рабочая область конвейера. Когда образ построителя создает контейнер рабочей области, который выполняет задачу непрерывной интеграции (CI) и развертывает образ, Code Stream передает переменные среды в этот контейнер.

Например, если для экземпляра Code Stream требуется веб-прокси, а для создания контейнера для настраиваемой интеграции используется узел Docker, Code Stream запускает конвейер и передает переменные настроек веб-прокси в этот контейнер.

Табл. 2. Пример пар «имя — значение» для переменных среды
Имя	Значение
HTTPS_PROXY	http://10.0.0.255:1234
https_proxy	http://10.0.0.255:1234
NO_PROXY	10.0.0.32, *.dept.vsphere.local
no_proxy	10.0.0.32, *.dept.vsphere.local
HTTP_PROXY	http://10.0.0.254:1234
http_proxy	http://10.0.0.254:1234
PATH	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

В пользовательском интерфейсе отобразятся пары «имя — значение», например следующие.

Code Stream передает переменные среды в контейнер, созданный образом построителя.

В этом примере создается настраиваемая интеграция, которая связывает службу Code Stream с экземпляром Slack и публикует сообщения в канале Slack.

Необходимые условия

Чтобы написать настраиваемый сценарий, необходимо использовать язык Python 2, Python 3 или Node.js либо один из языков командных оболочек (Bash, sh или zsh).
Создайте образ контейнера с помощью установленного файла Node.js или среды выполнения Python.

Процедура

Создайте настраиваемую интеграцию.

а. Выберите пункт Настраиваемые интеграции > Создать и введите соответствующее имя.
б. Выберите предпочитаемую среду выполнения.
в. Щелкните Создать.
Сценарий откроется, и в нем отобразится код, включая нужную среду выполнения. Например, runtime: "nodejs". Сценарий должен включать в себя среду выполнения, которую использует образ построителя, чтобы добавленная в конвейер настраиваемая задача была успешно выполнена в ходе работы конвейера. В противном случае настраиваемая задача завершится сбоем.

Основные области файла YAML настраиваемой интеграции включают в себя среду выполнения, код, входные и выходные свойства. В этой процедуре описываются различные типы и синтаксис.


Ключи YAML настраиваемой интеграции	Описание
runtime	Среда выполнения задач, где Code Stream выполняет код, который может представлять собой одну из следующих строк, нечувствительных к регистру. nodejs python2 python3 shell Если ничего не указано, по умолчанию используется shell.
code	Настраиваемая бизнес-логика для выполнения в рамках настраиваемой задачи.
inputProperties	Массив входных свойств для сбора данных в ходе определения параметров настраиваемой задачи. Эти свойства обычно используются в коде.
outputProperties	Массив выходных свойств, которые можно экспортировать из настраиваемой задачи для передачи в конвейер.

Объявите входные свойства в сценарии, используя доступные типы данных и метаданных.

Входные свойства передаются в качестве контекста для сценария в разделе code: файла YAML.


Входные ключи YAML настраиваемых задач	Описание	Обязательный
`type`	Типы входных данных для отображения: `text` `textarea` `number` `checkbox` `password` `select`	Да
`name`	Имя или строка входных данных для настраиваемой задачи, которые будут вставлены в код YAML настраиваемой интеграции. Значение должно быть уникальным для каждого входного свойства, определенного для настраиваемой интеграции.	Да
`title`	Метка текстовых строк входного свойства для настраиваемой задачи на холсте модели конвейера. Если оставить это поле пустым, по умолчанию используется `name`.	Нет
`required`	Определяет, должен ли пользователь вводить входное свойство при настройке задачи. Задайте значение true или false. Если задано значение true и пользователь не вводит значение при настройке задачи на холсте конвейера, задача остается в состоянии «Не настроено».	Нет
`placeHolder`	Текст по умолчанию для области ввода входного свойства, если значение отсутствует. Сопоставляется с атрибутом html-заполнителя. Поддерживается только для некоторых типов входных свойств.	Нет
`defaultValue`	Значение по умолчанию, подставляемое в область ввода входного свойства при отображении настраиваемой задачи на странице модели конвейера.	Нет
`bindable`	Определяет, принимает ли входное свойство переменные со знаком доллара при моделировании настраиваемой задачи на холсте конвейера. Добавляется индикатор $ рядом с заголовком. Поддерживается только для некоторых типов входных свойств.	Нет
`labelMessage`	Строка, которая выступает в качестве всплывающей подсказки для пользователей. Добавляет значок всплывающей подсказки i рядом с заголовком входных данных.	Нет
`enum`	Принимает массив значений, который отображает параметры входного свойства select. Поддерживается только для некоторых типов входных свойств. Если пользователь выбирает параметр и сохраняет его для настраиваемой задачи, значение inputProperty соответствует данному значению и отображается при моделировании настраиваемых задач. Например, значение 2015. 2015 2016 2017 2018 2019 2020 г.	Нет
`options`	Принимает массив объектов с использованием параметров optionKey и optionValue. optionKey. Значение, передаваемое в раздел кода задачи. optionValue. Строка, которая отображает параметр в пользовательском интерфейсе. Поддерживается только для некоторых типов входных свойств. Параметры optionKey: key1. В случае выбора и сохранения для настраиваемой задачи значение свойства inputProperty соответствует значению key1 в разделе кода. optionValue: «метка значения 1». Отображаемое значение для key1 в пользовательском интерфейсе, не отображается в других местах для настраиваемой задачи. optionKey: key2 optionValue: «метка значения 2» optionKey: key3 optionValue: «метка значения 3»	Нет
`minimum`	Принимает число, которое является минимальным допустимым значением данного входного свойства. Поддерживается только для числовых входных свойств.	Нет
`maximum`	Принимает число, которое является максимальным допустимым значением данного входного свойства. Поддерживается только для числовых входных свойств.	Нет

Табл. 3. Поддерживаемые типы данных и метаданных для настраиваемых сценариев
Поддерживаемые типы данных	Поддерживаемые метаданные для входных данных
Строка Text (текст) List: список любого типа Map: сопоставление в формате map[string]any Secure: отображается как текстовое поле для ввода пароля; при сохранении настраиваемой задачи к данным этого типа применяется шифрование Number (число) Boolean: (логический) отображается в виде текстовых полей URL: аналогично String, с дополнительной проверкой Selection, radio button (выбор значения, переключатель)	type: (тип) либо String, либо Text default: значение по умолчанию options: список или сопоставление параметров, которые будут использоваться для выбора значения или переключателя min: минимальное значение или размер max: максимальное значение или размер title: подробное имя текстового поля placeHolder: заполнитель для пользовательского интерфейса description: (описание) отображается в виде всплывающей подсказки

Например:

inputProperties:
        - name: message
          type: text
          title: Message
          placeHolder: Message for Slack Channel
          defaultValue: Hello Slack
          bindable: true
          labelInfo: true
          labelMessage: This message is posted to the Slack channel link provided in the code

Объявите выходные свойства в сценарии.

Сценарий получает выходные свойства из раздела бизнес-логики code: сценария, в котором объявлен контекст для выходных данных.

В ходе работы конвейера можно ввести код отклика для выходных данных задачи. Например: 200.

Ключи, поддерживаемые Code Stream для каждого параметра outputProperty.


key	Описание
type	В настоящее время доступно одно значение — `label`.
name	Ключ, передаваемый блоком кода YAML настраиваемой интеграции.
title	Метка в пользовательском интерфейсе, которая отображает параметр outputProperty.

Например:

outputProperties:
  - name: statusCode
    type: label
    title: Status Code

Для взаимодействия с входными и выходными данными настраиваемого сценария используйте оператор context для получения входного или настройки выходного свойства.
Для входного свойства: (context.getInput("key"))

Для выходного свойства: (context.setOutput("key", "value"))
Для Node.js:
```
var context = require("./context.js")
var message = context.getInput("message");
//Your Business logic
context.setOutput("statusCode", 200);
```
Для Python:
```
from context import getInput, setOutput
message = getInput('message')
//Your Business logic
setOutput('statusCode', '200')
```
Для оболочки:
```
# Input, Output properties are environment variables
echo ${message} # Prints the input message
//Your Business logic
export statusCode=200 # Sets output property statusCode
```

В разделе code: объявите всю бизнес-логику настраиваемой интеграции.

Пример для среды выполнения Node.js:

code: |
    var https = require('https');
    var context = require("./context.js")
    
    //Get the entered message from task config page and assign it to message var
    var message = context.getInput("message");
    var slackPayload = JSON.stringify(
        {
            text: message
        });

    const options = {
        hostname: 'hooks.slack.com',
        port: 443,
        path: '/YOUR_SLACK_WEBHOOK_PATH',
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': Buffer.byteLength(slackPayload)
        }
    };
    
    // Makes a https request and sets the output with statusCode which 
    // will be displayed in task result page after execution
    const req = https.request(options, (res) => {
        context.setOutput("statusCode", res.statusCode);
    });

    req.on('error', (e) => {
        console.error(e);
    });
    req.write(slackPayload);
    req.end();

Прежде чем присвоить сценарию настраиваемой интеграции версию и опубликовать его, загрузите файл контекста для Python или Node.js и проверьте бизнес-логику, включенную в сценарий.
1. а. Переместите указатель в верхнюю часть холста и нажмите кнопку файла контекста. Например, если сценарий написан на языке Python, нажмите CONTEXT.PY.
2. б. Внесите изменения в файл и сохраните его.
3. в. Запустите и протестируйте настраиваемый сценарий в системе разработки, используя файл контекста.
Назначьте сценарию настраиваемой интеграции версию.
1. а. Нажмите Версия.
2. б. Введите сведения о версии.
3. в. Нажмите Версия выпуска, чтобы сценарий можно было выбрать в настраиваемой задаче.
4. г. Чтобы создать версию, нажмите Создать.
(Необязательно) В качестве последней можно задать любую опубликованную версию сценария настраиваемой интеграции, чтобы она отображалась на холсте конвейера с меткой latest -->.
1. а. Переместите указатель в верхнюю часть холста и нажмите Журнал версий.
2. б. Щелкните многоточие рядом с нужной версией, чтобы увидеть доступные действия, и выберите Сделать последней.
  
  Примечание: Действие Сделать последней отображается только для опубликованных версий.
3. в. Чтобы подтвердить выбор версии, щелкните Сделать последней.
4. г. Чтобы выйти из Журнала версий и вернуться на холст редактора сценариев, нажмите стрелку «Назад».
Чтобы сохранить сценарий, нажмите Сохранить.
Чтобы экспортировать сценарий как файл YAML для использования в другом экземпляре Code Stream, в карточке настраиваемой интеграции щелкните Действия > Экспорт и выберите версии для экспорта.
Настройте рабочую область в конвейере.
В этом примере используется рабочая область Docker.
1. а. Откройте вкладку Рабочая область.
2. б. Выберите узел Docker и URL-адрес образа построителя.
Добавьте в конвейер настраиваемую задачу и настройте ее параметры.
1. а. Откройте вкладку Модель.
2. б. Добавьте задачу, выберите Настраиваемый в качестве типа и введите соответствующее имя.
3. в. Выберите сценарий настраиваемой интеграции и его версию. Если версия сценария назначена последней, перед ее названием отображается метка latest -->.
4. г. Введите текст настраиваемого сообщения, которое требуется отобразить в Slack.
  Введенный текст заменит defaultValue в сценарии настраиваемой интеграции.
Сохраните и включите конвейер.
1. а. Нажмите Сохранить.
2. б. В карточке конвейера выберите пункт Действия > Включить.
Запустите конвейер.
1. а. Щелкните Запустить.
2. б. Проверьте выполнение конвейера.
3. в. Убедитесь, что данные, полученные на выходе, включают в себя ожидаемый код состояния, код отклика, состояние и объявленные выходные данные.
  Компонент statusCode был определен как выходное свойство. Например, statusCode со значением 200 может указывать на успешную отправку сообщения в Slack, а responseCode со значением 0 — на выполнение сценария без ошибок.
4. г. Чтобы проверить выходные данные, зафиксированные в журналах выполнения, нажмите Выполняемые элементы, щелкните ссылку на конвейер, выберите задачу и просмотрите данные журнала. Например:
При возникновении ошибки устраните проблему и повторно запустите конвейер.
Например, если в базовом образе отсутствует файл или модуль, необходимо создать другой базовый образ, который будет включать отсутствующий файл. Затем укажите файл Docker и запустите обработку образа в конвейере.

Результаты

Поздравляем! Создан сценарий настраиваемой интеграции, который связывает службу Code Stream с экземпляром Slack и публикует сообщения в канале Slack.

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

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