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

В данном руководстве прикладного разработчика описана настройка процесса сборки и передачи дистрибутива Solution внешним заказчикам. Весь процесс можно поделить на 5 частей. Для каждой из частей настраивается Jenkins job с подключением своей библиотеки.

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

Для работы Jenkins jobs сборки и передачи Solution необходимо:

  • Наличие проектной области в Jenkins-ci.

  • Наличие ТУЗ для загрузки компонентов и загрузки Solution в Nexus-cd.

    • Оформляется в Jenkins в виде credentials c типом username with password.

  • Наличие ТУЗ для скачивания сборочных библиотек из Bitbucket.

    • Оформляется в Jenkins в виде credentials c типом SSH Username with private key.

  • Наличие коммунального ТУЗ (на текущий момент) для доступа на сервер подписания дистрибутивов.

    • Оформляется в Jenkins в виде credentials c типом username with password.

  • Наличие зарегистрированного КЭ используемого Solution.

    Для Solution, зарегистрированных в банке. Необходим при передаче Solution в банк.

  • Наличие УЗ для чтения конфигурационных файлов из репозитория.

    • Оформляется в Jenkins в виде credentials c типом SSH Username with private key.

  • Наличие УЗ для загрузки в целевое хранилище дистрибутивов.

    • Оформляется в Jenkins в виде credentials c типом username with password.

  • Наличие УЗ для загрузки в целевое хранилище дистрибутивов типа "репозиторий".

    • Оформляется в Jenkins в виде credentials c типом SSH Username with private key.

Допускается использование одинаковых УЗ для нескольких целей одновременно (при совпадении типа).

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

Создание Jenkins job сборки Solution#

Solution packer job:

  1. Создать pipeline (New Item → Pipeline).

  2. Перейти в конфигурацию Jenkins job и подключить библиотеку:

    • В разделе Pipeline в поле Definition выбрать из выпадающего списка Pipeline script from SCM.

    • Для SCM выбрать Git.

    • В качестве Repository URL указать ssh://git@solution-packer.git.

    • Credentials – ID credentials в Jenkins c типом SSH Username with private key.

    • В поле Script path ввести packer.groovy.

При первом запуске Jenkins job появятся параметры с описанием. Часть параметров имеют значения по-умолчанию (при необходимости можно переопределить), некоторые необходимо будет заполнить самостоятельно.

Параметры Jenkins Job для заполнения#

  • COMPONENTS = GroupId:ArtifactId:Type:Classifier:Version используемого дистрибутива, для его заполнения необходимо выбрать в Nexus необходимый дистрибутив и справа, в разделе Usage, выбрать Apache Buildr.

    Далее для каждого компонента копировать полученное значение в столбик.

    Пример:

    'Nexus_PROD:CI02676597_TSK:zip:distrib:D-4.5.0-82-bin'
'Nexus_PROD:CI02676597_TSK:zip:distrib:D-4.5.0-82-cfg'

  • NEXUS_CRED = ID credentials в Jenkins c типом username with password.

  • ARTIFACT_ID = Solution ARTIFACT_ID.

  • VERSION = Версия Solution. При желании можно добавить номер сборки в версию с помощью переменной ${BUILD_NUMBER}.

    Например, 1.3.0-${BUILD_NUMBER}.

  • JAVA_TOOL = версия JDK, необязательный параметр; если для используемого агента требуется указать JAVA_HOME – можно создать в job как строковый параметр.

  • EXCLUDE = Файлы, исключаемые из распаковки.

  • GROOVY_VERSION = используемая версия Groovy.

  • MAVEN_VERSION = используемая версия Maven.

  • SOLUTION_COMPONENTS_DIR = имя директории, в которую будут скачиваться компоненты на агенте.

  • DEPENDENCY_RESOLVER_CONFIGS_DIR = имя директории, в которую будет скачен файл конфигурации для Dependency Resolver.

  • DEPENDENCY_RESOLVER_DIR = имя директории, в которую будет скачена библиотека Dependency Reslover.

Создание Jenkins job сборки пакета Solution и получения для него цифровой подписи#

Solution publisher job:

  1. Создать pipeline (New Item → Pipeline).

  2. Перейти в конфигурацию Jenkins job и подключить библиотеку:

  • В разделе Pipeline в поле Definition выбрать из выпадающего списка Pipeline script from SCM.

  • Для SCM выбрать Git.

  • В качестве Repository URL указать ssh://git@solution-packer.git.

  • Credentials – ID credentials в Jenkins c типом SSH Username with private key.

  • В поле Script path ввести publisher.groovy.

При первом запуске Jenkins job появятся параметры с описанием. Часть параметров имеют значения по-умолчанию (при необходимости можно переопределить), некоторые необходимо будет заполнить самостоятельно.

Параметры Jenkins Job для заполнения#

  • COMPONENTS = 'GroupId:ArtifactId:Type:Classifier:Version' дистрибутива, для его заполнения необходимо выбрать в Nexus необходимый дистрибутив и справа, в разделе Usage, выбрать Apache Buildr. Далее для каждого компонента копировать полученное значение в столбик.

    Пример:

    'Nexus_PROD:CI02676597_TSK:zip:distrib:D-4.5.0-82-bin'
'Nexus_PROD:CI02676597_TSK:zip:distrib:D-4.5.0-82-cfg'

  • NEXUS_CRED = ID credentials в Jenkins c типом username with password.

  • SBERSIGN_CRED - ID credentials в Jenkins c типом username with password.

  • ARTIFACT_ID = Solution ARTIFACT_ID.

  • VERSION = Версия Solution. При желании можно добавить номер сборки в версию с помощью переменной ${BUILD_NUMBER}.

    Например: 1.3.0-${BUILD_NUMBER}.

  • SOLUTION_DIR = имя директории, в которой будет собираться пакет Solution.

  • MAVEN_VERSION = используемая версия Maven.

Создание Jenkins job передачи информации о Solution в стороннюю организацию#

Notifier job:

  1. Создать pipeline (New Item → Pipeline).

  2. Перейти в конфигурацию Jenkins job и подключить библиотеку:

    • В разделе Pipeline в поле Definition выбрать из выпадающего списка Pipeline script from SCM.

    • Для SCM выбрать Git.

    • В качестве Repository URL указать ssh://git@solution-packer.git.

    • Credentials – ID credentials в Jenkins c типом SSH Username with private key.

    • В поле Script path ввести notifier.groovy.

При первом запуске Jenkins job появятся параметры с описанием. Часть параметров имеют значения по-умолчанию (при необходимости можно переопределить), некоторые необходимо будет заполнить самостоятельно.

Параметры Jenkins Job для заполнения#

  • NEXUS_CRED = ID credentials в Jenkins c типом username with password.

  • ARTIFACT_ID = Solution ARTIFACT_ID.

  • VERSION = Версия Solution. При желании можно добавить номер сборки в версию с помощью переменной ${BUILD_NUMBER}. Например: 1.3.0-${BUILD_NUMBER}.

  • SOLUTION_ID = Зарегистрированный КЭ Solution.

    Для Solution, зарегистрированных в банке. Необходим при передаче Solution в банк.

  • JAVA_TOOL = версия JDK, необязательный параметр; если для используемого агента требуется указать JAVA_HOME – можно создать в job как строковый параметр

  • MAVEN_VERSION = используемая версия Maven.

Создание Jenkins job пересборки Docker образов, обновления конфигураций и SDK для компонентов Solution#

Solution merger job:

  1. Создать pipeline (New Item → Pipeline).

  2. Перейти в конфигурацию Jenkins job и подключить библиотеку:

    • В разделе Pipeline в поле Definition выбрать из выпадающего списка Pipeline script from SCM.

    • Для SCM выбрать Git.

    • В качестве Repository URL указать ssh://git@solution-merger.git.

    • Credentials – ID credentials в Jenkins c типом SSH Username with private key.

    • В поле Script path ввести merge.groovy.

При первом запуске Jenkins job появятся параметры с описанием. Часть параметров имеют значения по умолчанию (при необходимости можно переопределить), некоторые необходимо будет заполнить самостоятельно.

Параметры Jenkins Job для заполнения#

  • JENKINS_NODE = Метка агента Jenkins, на котором будет выполняться job.

  • CONFIG_REPO = Адрес репозитория (SSH ссылка), в котором находится файл конфигурации.

  • CONFIG_BRANCH = Ветка репозитория с файлом конфигурации, по-умолчанию используется ветка master.

  • GROUP_ID = GroupId Solution, merge которого необходимо осуществить.

  • ARTIFACT_ID = ArtifactId Solution, merge которого необходимо осуществить.

  • VERSION = Версия Solution для merge. При желании можно добавить номер сборки в версию с помощью переменной ${BUILD_NUMBER}.

    Например: 1.3.0-${BUILD_NUMBER}.

  • EXCLUDE = Файлы, исключаемые из распаковки.

  • dpmPhaseID = параметр, позволяющий запускать Jenkins job из конвейеров DPM.

  • SOLUTION_DIR = имя директории, в которую будет скачиваться пакет Solution.

Создание конфигурационного файла#

В репозитории с конфигурацией должен лежать файл merger.yml, заполненный следующим образом:

build_history:
  builds:
    days: 100 # сколько дней хранить сборки
    num: 30 # количество сборок для хранения

tooling:                     # какие конкретно утилиты использовать из инструментария Jenkins
  jdk: openjdk-11.0.11_linux # версия JDK, которую будет использовать Maven для скачивания и загрузки компонентов
  maven: Maven 3.6.3         # версия Maven, используемая для скачивания и загрузки архивов
  npm: v7.5.0-linux-x64      # версия NPM
  groovy: Groovy-3.0.7       # версия Groovy, которой будет объединяться дистрибутив (из owned и party), версия Groovy должна быть 3.x и выше

repositories:
  solution:
    download: # адрес репозитория и ID credentials в Jenkins для скачивания Solution
      url: https://<...>/nexus/content/repositories/Nexus_PROD_OUT/
      creds: demoCD
    upload:   # адрес репозитория и ID credentials в Jenkins для загрузки объединенного Solution
      url: https://<...>/nexus/content/repositories/Nexus_PROD_OUT/
      creds: demoCD
  maven:      # 
    download: # адрес репозитория и ID credentials в Jenkins для загрузки Maven плагинов
      url: http://<...>/nexus/content/repositories/central
      creds: demoCD
    upload:   # адрес репозитория и ID credentials в Jenkins для загрузки Maven артефактов (SDK)
      url: http://<...>/nexus/content/repositories/efs_release
      creds: demoCD
  npm:        # адрес репозитория и ID credentials в Jenkins для загрузки NPM артефактов (SDK)
    url: https://<...>/nexus/content/repositories/some-npm-repo
    creds: demoCD
docker:
  registry:   # адрес репозитория и ID credentials в Jenkins для сборки и загрузки Docker образов
    url: https://registry.<...>.ru
    creds: 4627c8e5-ab42-4e76-a816-ce2ec6e718fc
  # путь для загрузки Docker образов
  registry_path: efs-dev/ci01976100/ci02210881_as_efs_devops_pipeline_dev
  # маппинг базовых образов
  base_image_mapping:
    - from: .*some/regex.*
      to: registry.<...>.ru/some_path/base_url
    - from: .*openjdk11.*
      to: registry.<...>.ru/efs/base/rhel7openjdk11:7.6-252.1561619826-86
  # маппинг ссылок на образы (применяется, чтобы заменить ссылки на Sidecar)
  image_link_mapping:
    "mona/agent@sha256:[0-9a-f]{64}" : "mona/agent@sha256:cbd08dc4877d5b1b0cb81fd35b02c482737e12e1860ab6117962eef3075a6aa5"
    "supa/client@sha256:[0-9a-f]{64}" : "supa/client@sha256:7c42e54a4d3b3175b4912781fcfcfd0709d7f6bd3169c9f5a8b69ce7cfc75e3f"

️ Указывая ссылки на образы, можно воспользоваться функциональностью подмены путей к образам по регулярному выражению и указать в качестве значения требуемые переменные. Или, если это Sidecar, который находится в другом КЭ и {{ registry_path }} продукта к нему не подходит, можно вместо {{ registry_path }} указать сразу правильный путь. Например:

image_link_mapping:
"\\$\\{some.custom.registry.path.parameter\\}/<host>/xxx_xxxx/xxxx/some-component-app": "{{ registry }}/{{ registry_path }}/cixxxxxxxx/xxxxxxxx/some-component-app"
"/<host>/yyy_yyyy/yyyy/some-sidecar": "/ciyyyyyyy/yyyyyyy/some-sidecar"

Создание Jenkins job распаковки Solution#

Solution unpacker job:

  1. Создать pipeline (New Item → Pipeline).

  2. Перейти в конфигурацию Jenkins job и подключить библиотеку:

    • В разделе Pipeline в поле Definition выбрать из выпадающего списка Pipeline script from SCM.

    • Для SCM выбрать Git.

    • В качестве Repository URL указать ssh://git@solution-unpacker.git.

    • Credentials – ID credentials в Jenkins c типом SSH Username with private key.

    • В поле Script path ввести unpackSolution.groovy.

При первом запуске Jenkins job появятся параметры с описанием. Часть параметров имеют значения по умолчанию (при необходимости можно переопределить), некоторые необходимо будет заполнить самостоятельно.

Параметры Jenkins Job для заполнения#

  • JENKINS_NODE = Метка агента Jenkins, на котором будет выполняться job.

  • CONFIG_REPO = Адрес репозитория (SSH ссылка), в котором находится файл конфигурации.

  • CONFIG_BRANCH = Ветка репозитория с файлом конфигурации, по-умолчанию используется ветка master.

  • GROUP_ID = GroupId Solution.

  • ARTIFACT_ID = ArtifactId Solution.

  • VERSION = Версия Solution для merge. При желании можно добавить номер сборки в версию с помощью переменной ${BUILD_NUMBER}.

    Например: 1.3.0-${BUILD_NUMBER}.

  • SOLUTION_DIR = имя директории, в которую будет скачиваться пакет Solution.

Создание конфигурационных файлов#

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

  • environment.yml – конфигурационный файл, описывающий используемые репозитории и настройки окружения.

  • artifactRenameRules.csv – таблица соответствия координат groupId/artifactId артефактов Solution координатам groupId/artifactId в репозиториях целевого хранилища.

artifactRenameRules.csv необязателен для размещения. Он создается и заполняется в процессе работы самой Jenkins job.

Пример заполнения файла environment.yml:

build_history:
days: 100             # сколько дней хранить сборки
num: 3                # сколько сборок хранить
repositories:
  central:            # адрес репозитория-зеркала central, УЗ по умолчанию - ci
    src: http://<...>/nexus/content/repositories/central
    creds: demoCD     # для репозиториев можно указывать УЗ по отдельности
  solution:           # адрес репозитория, где лежат Solution
    src: https://<...>/nexus/content/repositories/Nexus_PROD_OUT/
  cd:                 # адрес репозитория, куда раскладывать дистрибутивы
    src: https://<...>/nexus/content/repositories/Nexus_PROD
gitRepositories:      # перечень репозиториев, для загрузки дистрибутивов, состоящих из git-репозиториев
  repoId1:            # реквизиты для загрузки каждого из репозиториев, взятых из свойства <repoId> pom.xml
    src: ssh://git-server/project/repo.git
    creds: demoCD_ssh
credentials:
  ci: demoCD          # УЗ для доступа к Maven-репозиторию, для скачивания плагинов Maven (для взаимодействия с репозиториями)
  cd: demoCD          # УЗ для загрузки дистрибутивов в Nexus
  solution: demoCD    # УЗ для загрузки Solution
  ssh: demoCD_ssh     # УЗ типа SSH, под которой будут пушиться дистрибутивы с репозиторияими
java:                 # настройка инструментария
  jdk: openjdk-11.0.11_linux
  maven: Maven 3.6.3
extensions:           # Блок для подключения точек расширения (подробнее см. "Инструменты трансформации дистрибутива в процессе распаковки")

При первичной распаковке Solution репозитории, созданные в GitLab/Bitbucket для распаковки дистрибутива Solution, должны быть пустыми. При обновлении Solution (когда в распаковываемых репозиториях уже есть предыдущая версия Solution) очищать репозитории нет необходимости.

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

Для управления версией программного компонента Delivery Tools необходимо:

  • Указать непосредственно в Jenkins jobs для каждой из сборочных библиотек tag необходимого релиза. Соответствие тега релизу можно узнать из файла ReleaseNotes.json, находящегося в корне репозитория каждой из библиотек.

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

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

Для работы Delivery Tools необходимо:

  1. Создать 5 Jenkins jobs по количеству сборочных библиотек в программном компоненте.

  2. Подключить сборочные библиотеки и запустить Jenkins jobs без параметров.

  3. Заполнить параметры значениями для последующих запусков Jenkins jobs.

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

Программный компонент Delivery Tools используется для сборки и передачи дистрибутива Solution внешним заказчикам. Далее дано краткое описание каждой и сборочных библиотек, входящих в Delivery Tools.

Сборка Solution и получения для него цифровой подписи#

Является частью процесса Передачи дистрибутива ППО внешней разработки в Nexus.

Основные этапы:

  • Сборка Solution из дистрибутивов его компонентов.

  • Разделение Solution на owned, party и vendor части.

  • Загрузка этих частей Solution в Nexus.

Результат:

  • Solution, разделенный на составные owned, party и vendor части, имеющий classifier 'distrib' и расширение '.zip', загружен в Nexus.

Дополнительная информация#

Сборка Solution включает в себя разделение его компонентов на owned, party и vendor части. Этот функционал реализует подключаемая библиотека Dependency Resolver. Для ее работы нужны переменные окружения, которые при необходимости можно переопределить, добавив в Jenkins job следующие параметры:

  • DEPENDENCY_RESOLVER_CONFIGS = Ссылка на репозиторий с конфигурациями для библиотеки Dependency Resolver, значение по-умолчанию: ssh://git@dependency-resolver-configs.git.

  • DEPENDENCY_RESOLVER_CONFIGS_BRANCH = Ветка в репозитории с конфигурациями для библиотеки Dependency Resolver, значение по-умолчанию: master.

  • DEPENDENCY_RESOLVER_BRANCH = Ветка скриптов библиотеки Dependency Resolver, значение по-умолчанию: master.

Создание и получение цифровой подписи пакета Solution#

Pipeline является частью процесса Передачи дистрибутива ППО внешней разработки в Nexus.

Основные этапы:

  • Создание пакета, содержащего составные части Solution.

  • Получение цифровой подписи для этого пакета.

  • Загрузка пакета Solution в Nexus.

  • Загрузка подписей и хешей для пакета Solution в Nexus.

Результат:

  • Пакет, содержащий составные части Solution, подписанный цифровой подписью, имеющий classifier 'distrib' и расширение '.zip', загружен в Nexus.

  • Архив с подписями и хешами для пакета Solution, имеющий classifier 'distrib' и расширение '.zip', загружен в Nexus.

Передача информации о пакете Solution в стороннюю организацию#

Pipeline является частью процесса Передачи дистрибутива ППО внешней разработки в Nexus.

Основные этапы:

  • Загрузка архива с подписями и хешами для пакета Solution из Nexus.

  • Передача данных о пакете Solution в стороннюю организацию.

Результат:

  • Данные о пакете Solution успешно переданы в стороннюю организацию.

Пересборка Docker образов, обновление конфигураций и SDK для компонентов Solution#

Основные этапы:

  • Скачивание пакета, содержащего составные части Solution, и merge одного архива.

  • Распаковка архива. Выделение компонентов Solution.

  • Пересборка Docker образов и обновление хэшей в конфигурациях для компонентов Solution.

  • Обновление SDK в дистрибутивах компонентов.

  • Перепаковка архива Solution и загрузка его в Nexus.

Результат:

  • Архив Solution, имеющий classifier 'distrib' и расширение '.zip', загружен в Nexus.

Распаковка Solution#

Основные этапы:

  • Скачивание архива Solution.

  • Распаковка архива Solution и загрузка его компонентов в Nexus сторонней организации для последующей их установки.

Результат:

  • Архив Solution успешно распакован и его компоненты загружены в Nexus сторонней организации. В составе Solution могут быть компоненты следующих типов:

    • "обычный" дистрибутив, содержит и исполняемый код, и конфигурации.

    • бинарный дистрибутив, содержит исполняемый код какой-либо подсистемы, и не содержит конфигураций. Такой дистрибутив не может быть установлен на какие-нибудь стенды.

    • дистрибутив конфигураций, состоит из конфигурации и не содержит исполняемого кода. В таком дистрибутиве обязательно должна быть ссылка на какую-либо версию бинарного дистрибутива.

    • репозиторий - специальный дистрибутив, состоит из git репозитория, который выгружается не в Maven-хранилище, а в соответствующий целевой git-репозиторий (целевое расположение).

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

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

Отсутствие GAV-параметров Solution для заполнения соответствующих параметров Jenkins jobs#

GAV-параметры собираемого Solution следует уточнять у соответствующего Solution-owner.

В переданном дистрибутиве в манифестах не параметризованы пути к образам через переменные и #

В настройках Jenkins job пересборки Docker образов (solution-merger) при указании путей к образам использовать подмену путей по регулярному выражению и указать в качестве значения требуемые переменные. Или, если это Sidecar, который находится в другом КЭ и {{ registry_path }} продукта к нему не подходит, указать вместо {{ registry_path }} сразу правильный путь. Например:

image_link_mapping:
"\\$\\{some.custom.registry.path.parameter\\}/<host>/xxx_xxxx/xxxx/some-component-app": "{{ registry }}/{{ registry_path }}/cixxxxxxxx/xxxxxxxx/some-component-app"
"/<host>/yyy_yyyy/yyyy/some-sidecar": "/yyyyyyy/yyyyyyy/some-sidecar"