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

Процедура

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

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

    • nodejs
    • python2
    • python3
    • shell

    Если ничего не указано, по умолчанию используется shell.

    code Настраиваемая бизнес-логика для выполнения в рамках настраиваемой задачи.
    inputProperties Массив входных свойств для сбора данных в ходе определения параметров настраиваемой задачи. Эти свойства обычно используются в коде.
    outputProperties Массив выходных свойств, которые можно экспортировать из настраиваемой задачи для передачи в конвейер.
  2. Объявите входные свойства в сценарии, используя доступные типы данных и метаданных.
    Входные свойства передаются в качестве контекста для сценария в разделе 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
    
  3. Объявите выходные свойства в сценарии.
    Сценарий получает выходные свойства из раздела бизнес-логики code: сценария, в котором объявлен контекст для выходных данных.
    В ходе работы конвейера можно ввести код отклика для выходных данных задачи. Например: 200.
    Ключи, поддерживаемые Code Stream для каждого параметра outputProperty.
    key Описание
    type В настоящее время доступно одно значение — label.
    name Ключ, передаваемый блоком кода YAML настраиваемой интеграции.
    title Метка в пользовательском интерфейсе, которая отображает параметр outputProperty.
    Например:
    outputProperties:
      - name: statusCode
        type: label
        title: Status Code
  4. Для взаимодействия с входными и выходными данными настраиваемого сценария используйте оператор 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
    
  5. В разделе 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();
    
  6. Прежде чем присвоить сценарию настраиваемой интеграции версию и опубликовать его, загрузите файл контекста для Python или Node.js и проверьте бизнес-логику, включенную в сценарий.
    1. а. Переместите указатель в верхнюю часть холста и нажмите кнопку файла контекста. Например, если сценарий написан на языке Python, нажмите CONTEXT.PY.
    2. б. Внесите изменения в файл и сохраните его.
    3. в. Запустите и протестируйте настраиваемый сценарий в системе разработки, используя файл контекста.
  7. Назначьте сценарию настраиваемой интеграции версию.
    1. а. Нажмите Версия.
    2. б. Введите сведения о версии.
    3. в. Нажмите Версия выпуска, чтобы сценарий можно было выбрать в настраиваемой задаче.
    4. г. Чтобы создать версию, нажмите Создать.
      Вы назначаете версию сценарию настраиваемой интеграции и выбираете версию в настраиваемой задаче в конвейере.
  8. (Необязательно) В качестве последней можно задать любую опубликованную версию сценария настраиваемой интеграции, чтобы она отображалась на холсте конвейера с меткой latest -->.
    1. а. Переместите указатель в верхнюю часть холста и нажмите Журнал версий.
    2. б. Щелкните многоточие рядом с нужной версией, чтобы увидеть доступные действия, и выберите Сделать последней.
      Примечание: Действие Сделать последней отображается только для опубликованных версий.
      После создания версии и выпуска сценария настраиваемой интеграции эту версию можно назначить последней, чтобы пользователь знал, какая версия актуальная, и мог выбрать ее в конвейере.
    3. в. Чтобы подтвердить выбор версии, щелкните Сделать последней.
    4. г. Чтобы выйти из Журнала версий и вернуться на холст редактора сценариев, нажмите стрелку «Назад».
  9. Чтобы сохранить сценарий, нажмите Сохранить.
    Чтобы экспортировать сценарий как файл YAML для использования в другом экземпляре Code Stream, в карточке настраиваемой интеграции щелкните Действия > Экспорт и выберите версии для экспорта.
  10. Настройте рабочую область в конвейере.
    В этом примере используется рабочая область Docker.
    1. а. Откройте вкладку Рабочая область.
    2. б. Выберите узел Docker и URL-адрес образа построителя.
      При создании настраиваемой интеграции необходимо указать адрес узла, URL-адрес образа построителя и реестр образов.
  11. Добавьте в конвейер настраиваемую задачу и настройте ее параметры.
    1. а. Откройте вкладку Модель.
    2. б. Добавьте задачу, выберите Настраиваемый в качестве типа и введите соответствующее имя.
    3. в. Выберите сценарий настраиваемой интеграции и его версию. Если версия сценария назначена последней, перед ее названием отображается метка latest -->.
    4. г. Введите текст настраиваемого сообщения, которое требуется отобразить в Slack.
      Введенный текст заменит defaultValue в сценарии настраиваемой интеграции.
      При добавлении настраиваемой задачи в конвейер необходимо выбрать версию настраиваемого сценария.
  12. Сохраните и включите конвейер.
    1. а. Нажмите Сохранить.
    2. б. В карточке конвейера выберите пункт Действия > Включить.
  13. Запустите конвейер.
    1. а. Щелкните Запустить.
    2. б. Проверьте выполнение конвейера.
    3. в. Убедитесь, что данные, полученные на выходе, включают в себя ожидаемый код состояния, код отклика, состояние и объявленные выходные данные.
      Компонент statusCode был определен как выходное свойство. Например, statusCode со значением 200 может указывать на успешную отправку сообщения в Slack, а responseCode со значением 0 — на выполнение сценария без ошибок.
    4. г. Чтобы проверить выходные данные, зафиксированные в журналах выполнения, нажмите Выполняемые элементы, щелкните ссылку на конвейер, выберите задачу и просмотрите данные журнала. Например:
      После того как конвейер выполнит настраиваемую задачу, можно просмотреть выходные данные задачи для настраиваемой интеграции в разделе циклов выполнения конвейера.
  14. При возникновении ошибки устраните проблему и повторно запустите конвейер.
    Например, если в базовом образе отсутствует файл или модуль, необходимо создать другой базовый образ, который будет включать отсутствующий файл. Затем укажите файл Docker и запустите обработку образа в конвейере.

Результаты

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

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

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