Руководство прикладного разработчика#

Системные требования#

Основные требования к используемым системам при работе с программным компонентом представлены в Руководстве по установке → глава Системные требования.

Для работы pipeline необходимо, чтобы в проектной области Jenkins были настроены данные для авторизации (логин/пароль) под учетной записью со следующими правами:

  • Чтение артефактов из репозитория в Nexus (обязательно).

  • Чтение файлов из git-репозитория.

Подключение и конфигурирование#

Для использования Installer необходимо создание и конфигурирование Jenkins job. При этом указывается репозиторий с исполняемым скриптом, а также заполняется раздел:
Prepare an environment for the run → Properties Content
настроек Jenkins job:

  • параметры CHANNEL и ENVIR – если используется common-репозиторий;

  • pipelineSchedulerDistrVersion – в случае, если версия Installer указывается непосредственно через Jenkins job;

  • NODE, указывается при желании;

А также указываются используемые credentials, настраиваемые в файле параметров сценария формата .properties / .yml (подробнее см. Разработка сценариев → раздел Структура Installer)).

В частности, необходимы credentials для доступа к Nexus (или git), в котором располагается дистрибутив Installer. Данные credentials необходимо также указать в файле параметров в переменной installer.jenkins.nexus.jenkinsCred.

После настройки следует произвести первичный запуск, во время которого произойдет автоматическая реконфигурация, и у Jenkins job появятся необходимые параметры запуска. С этого момента Job считается готовым к работе.

В настройках Jenkins job в разделе Properties Content опционально можно указать параметр readFilePeriod для изменения частоты считывания служебного файла (перерисовка таблицы и интерактивное взаимодействие). По умолчанию это значение составляет 2 секунды. Этот параметр можно также изменять в файле параметров (параметр installer.read.period).

Миграция на текущую версию#

Installer версионируется отдельно от Jenkins job.

Для управления версией Jenkins job существует два способа:

  1. Указать непосредственно в Jenkins job репозиторий скрипта и ветку по имени необходимого релиза. В этом случае должен быть обеспечен доступ к репозиторию.

  2. Настроить Jenkins job на релизный репозиторий Pipeline (ветка master, файл deploy-fpi-scheduler.groovy) и указать необходимые для доступа к common-репозиторию переменные (CHANNEL и ENVIR в Prepare an environment for the run → Properties Content настроек Jenkins job). При этом в файле version.conf корня common-репозитория указывается переменная pipelineSchedulerVersion.
    Саму же версию в данный репозиторий можно подгрузить с помощью Service job, выбрав в качестве артефакта PIPELINE_SCHEDULER.

В любом случае после обновления версии Jenkins job, рекомендуется выполнить реконфигурацию: для этого нужно запустить Jenkins job с пустыми значениями параметров запуска.

Для выбора версии дистрибутива Installer, также существует два способа:

  1. В настройках Jenkins job – Properties Content необходимо указать переменную pipelineSchedulerDistrVersion.

  2. Либо прописать эту же переменную в файле version.conf аналогично тому, как это настраивается для версии Jenkins job.

Быстрый старт#

Для запуска Jenkins job установщика необходимо указать следующие параметры, доступные на текущий момент:

  • scenarioGitUrl – SSH-адрес с репозиторием сценария (будет использоваться те же credentials, что указаны для pipeline-скрипта Jenkins job);

  • scenarioGitBranch – ветка данного скрипта, из которого берется сценарий;

  • scenarioFile – путь к запускаемому сценарию внутри выбранного репозитория.

Использование программного компонента#

В процессе использования Installer job происходит запуск pipeline скрипта, который выполняет следующие задачи:

  • Запуск инсталляции в контексте Jenkins.

  • Получение версии дистрибутива Installer из переменных окружения Jenkins, либо файла common-репозитория version.conf.

  • Скачивание указанных пользователем артефактов установки (сценарий или набор сценариев, файлы параметров, и пр.). А также скачивание и распаковка дистрибутива Installer указанной версии.

  • Обработка источников данных для secret-файла из интерактивного ввода в Jenkins job и Jenkins credentials + шифрование последних при необходимости.

  • Push служебного файла обратно в репозиторий сценария.

  • Прорисовка в близком к реальному времени таблицы с результатами выполнения сценария и пр.

Таблица статусов#

В процессе выполнения сценария, параллельно нему отрисовывается таблица статуса выполнения. Эта таблица перерисовывается каждые 2 секунды и служит для отображения структуры сценария, параметров с которыми выполняется тот, или иной шаг, URL Jenkins job, если данный шаг является Jenkins job, а также текущий статус шага, окрашивая его соответствующим цветом.

Всего на текущий момент есть следующие отображаемые статусы:

  • queue – в очереди: сценарий еще не добрался до данного шага.

  • running – запущен: шаг выполняется в данный момент.

  • skipped – шаг был пропущен: данный статус выводится лишь для отключенных шагов.

  • not running – шаг не запускался: статус присваивается лишь в самой последней итерации отрисовки и говорит о том, что шаг не выполнялся (обычно по причине того, что один из предшествующих шагов завершился с ошибкой).

  • error – шаг завершился с ошибкой: в соответствующем поле будет отображено детальное сообщение.

  • success – шаг выполнен успешно.

  • прочие статусы, которые может вернуть Jenkins (например unstable).

Выполнение сценария#

Для управления процессом установки используется заранее заготовленный сценарий – см. Разработка сценариев установки.

Часто встречающиеся проблемы и пути их устранения#

  1. Настройка JDK:

    Если на запускаемом Node по умолчанию указана версия JDK, несовместимая с Installer (рекомендуемая версия 1.8+), то существует возможность указать произвольную версию. Для этого используется Jenkins tool, и выбранная версия JDK прописывается все в том же Properties Content в переменную jdkTool.