Руководство по установке#

В руководстве приведены инструкции по установке программного компонента Build Tools (CIJE) программного продукта Platform V DevOps Tools (DOT).

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

Настройки безопасности окружения и перечень платформенных (дополнительных внешних) продуктов, используемых для установки, настройки и контроля в конечной информационной системе (далее — ИС), выбираются при разработке конечной ИС, исходя из характера обрабатываемой в ней информации и иных требований информационной безопасности (далее — ИБ), предъявляемых к ней.

Системное программное обеспечение#

Ниже представлены категории системного программного обеспечения, которые обязательны для установки, настройки, контроля и функционирования программного компонента. В каждой категории перечислены все поддерживаемые продукты сторонних правообладателей. Отдельно обозначены варианты, которые рекомендует АО «СберТех» (маркировка «Рекомендовано» в столбце «Продукт, функциональная совместимость с которым подтверждена»). Клиенту необходимо выбрать один из продуктов в каждой категории, исходя из условий использования конечной ИС.

Категории системного программного обеспечения, представленные ниже, обязательны для установки, настройки, контроля и функционирования компонента. В рамках каждой категории перечислены все поддерживаемые системные программы сторонних правообладателей, в том числе рекомендованные АО «СберТех». Выбор системной программы в каждой категории остается на стороне клиента (пользователя):

Примечание:

*

• Да — категория ПО обязательна для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данной категории ПО).

• Нет — категория ПО необязательна для функционирования сервиса (это означает, что сервис может выполнять свои основные функции без установки данной категории ПО).

**

• Рекомендовано — рекомендованный правообладателем АО «СберТех» продукт.

• Опционально — альтернативный по отношению к рекомендованному правообладателем АО «СберТех» продукт.

***

Должно быть установлено на узлах (nodes) Jenkins. Пути до бинарных файлов утилит должны быть добавлены в системную переменную PATH.

Платформенные зависимости#

Для настройки, контроля и функционирования компонента реализована интеграция с программными продуктами, правообладателем которых является АО «СберТех»:

Примечание:

***

• Да — компонент или продукт необходим для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данного компонента).

• Нет — необязательный для функционирования сервиса компонент или продукт (это означает, что сервис может выполнять свои основные функции без установки данного компонента).

Информация по установке и настройке компонента DTDS приведена в разделе: Документация на программный продукт Platform V DevOps Tools (DOT) Документация на компонент DTDS → Руководство по установке.

Состав дистрибутива#

Подготовка окружения#

1. Перед началом работы с программным компонентом Build Tools необходимо обеспечить:

   • Наличие у рабочего проекта области в Bitbucket и прав доступа пользователя (в данном случае – разработчика) на создание репозиториев.

   • Наличие у проекта области (папки) в Jenkins.

   • Наличие следующих учетных записей:

     • USER/PASS – с правами доступа на чтение из репозитория nexus-ci и записью в репозитории nexus-cd и docker registry;

     • SSH – ТУЗ с возможностью подключения сборочных библиотек из Bitbucket.

   • Возможность сборки Docker образов.

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

   • Загрузка артефактов в репозиторий Nexus_prod repo (обязательно).

   • Загрузка вложений со страниц Confluence (если документация к инсталляционному пакету находится в Confluence).

   Для добавления Credentials (данных учетных записей) в Jenkins необходимо:

   1. Открыть страницу проектной области Jenkins.

   2. В меню слева выбрать Credentials.

   3. В открывшейся странице в списке credentials в колонке Domain выбрать домен – global.

   4. После чего нажать на «Добавить учетные данные».

   5. Среди полей параметров из выпадающего списка выбрать «SSH Username with private key».

   6. Ввести имя пользователя git_ssh_tech.

   7. Выбрать пункт «Enter directly» и ввести приватный ключ технологической учетной записи.

   8. В качестве id указать – git_ssh_tech.

   9. В Description ввести – git_ssh_tech.

   10. Подтвердить введенные параметры – «OK».

   11. Добавить git_ssh_tech в файл environment.json в блок соответствующей среды в параметр «SshKeyCreds».

   ⚠️ Важно! Библиотека NexusLib не поддерживает следующие спецсимволы в пароле - $ и ', это связано с ограничениями самой библиотеки. Рекомендуется сменить пароль.

3. Для сборки Docker-файлов c инструментом BuildKit необходимо создать сущность сборщика (buildkit builder), указывающего на адрес Docker-сокета и установить следующие параметры - название сборщика и образ интрумента BuildKit: docker buildx create --use --name=builder --driver-opt image=$BUILDER_IMAGE, где BUILDER_IMAGE - путь до базового образа BuildKit (например, образ buildkit:buildx-stable-1). Созданный сборщик необходимо установить по умолчанию. Для этого экспортируйте переменную окружения с ключом BUILDX_BUILDER и значением, соответствующим названию вашего сборщика (BUILDX_BUILDER=builder).

⚠️ Важно! Необходимо установить переменную окружения с ключом DOCKER_CONFIG и значением, которое соответствует абсолютному пути вашего конфигурационного Docker-файла с настройками Buildx (/full/path/to/.docker).

4. Для установки настроек по умолчанию рекомендуется создать в проектной области Bitbucket репозиторий common. В корне репозитория common должен располагаться конфигурационный файл - common.yml. Данный файл должен декларировать настройки по умолчанию для конфигурационных файлов пользователей (далее pipeline.yml). При необходимости пользователь может переопределить координаты common-репозитория через переменные окружения в Jenkins job:

• COMMON_REPO - SSH-ссылка на репозиторий конфигураций common.

• COMMON_REPO_BRANCH - ветка репозитория конфигураций common.

• COMMON_FILE_PATH - путь до конфигурационного файла common.yml, относительно корня репозитория конфигураций common.

Перед сборкой будет выполнено слияние конфигурационных файлов common.yml и pipeline.yml по следующим правилам:

1. Объекты типа словарь (key: "value") будут рекурсивно объединены по ключам.

2. Скалярные объекты и списки будут перезаписаны. Например, список в common.yml перезапишется списком из pipeline.yml.

3. Элементы списка extensions должны объединяться так же как объекты типа словарь, в качестве ключа должно использоваться значение поля name. В случае отсутствия поля name объекты должны добавляться в конец списка extensions, полученного из pipeline.yml.

Пример common.yml:

extensions:
  - name: commonTest
    repo: common/common-test.git  # Можно указать также и полную ссылку SSH на репозиторий
    branch: develop
    script_path: extensions/commonTest.groovy
  - name: commonRewriteTest
    some_parameter: 'parameter from common'
    additional_common_parameter: 2
docker:
  builder: docker

Пример pipeline.yml:

...

docker:
  builder_token: "<credential>"  # ID ТУЗа с доступ на запись в Nexus
  registry_address: "<registry address>"
  nexus_url: "<path>" # путь к вашей области с образами

extensions:
  - customTestExtension
  - name: commonRewriteTest
    some_parameter: "SPECIFIC VALUE"
    additional_parameter: 1

...

Пример результирующего конфигурационного файла:

...

docker:
  builder_token: "<credential>"  # ID ТУЗа с доступ на запись в Nexus
  registry_address: "<registry address>"
  nexus_url: "<path>" # путь к вашей области с образами
  builder: docker

extensions:
  - customTestExtension
  - name: commonRewriteTest
    some_parameter: "SPECIFIC VALUE"
    additional_parameter: 1
  - name: commonTest
    repo: common/common-test.git
    branch: develop
    script_path: extensions/commonTest.groovy

...

Установка#

Поскольку сам программный компонент представляет собой библиотеку в Jenkins для работы с ним потребуется наличие библиотеки в git-репозитории. Загрузка репозитория выполняется стандартными средствами git.

Ручная установка#

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

В созданной области (папке) Jenkins в меню слева необходимо выбрать New Item, ввести имя и выбрать тип Pipeline.

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

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

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

• В качестве Repository URL указать ssh://<git>/bootcamp-devopstools/ufs-pipeline.git.

• Credentials – ID этой учетной записи.

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

• Если требуется зафиксировать версию библиотеки, то в поле Branches to build указать тэг нужной версии tags/<version>, где - нужная версия, например, 1.4.4.

• Затем – необходимо отметить опцию (чекбокс) Эта параметризованная сборка/This project is parameterized.

• Следующим шагом – ввести обязательные String параметры:

  • CONFIG_REPO = ufs_ci/test.app.configs.git - проект/репозиторий с файлом pipeline.yml .

  • CONFIG_BRANCH = develop - ветка с актуальным pipeline.yml .

  • CONFIG_FILE = pipeline.yml - относительный путь до файла, если в корне репы - оставить как есть.

  • JENKINS_NODE = docker - название сборочного агента.

  • SONAR_DISABLED = true - отключение security проверок.

Обновление#

Обновление может быть осуществлено через:

1. Распаковку новой версии в репозиторий компонента.

2. Смену тега в настройках Jenkins job.

Удаление#

Jenkins jobs по работе с предоставляемой библиотекой могут быть удалены с использованием UI Jenkins.

Для удаления необходимо зайти в интерфейс Jenkins, перейти в созданный job и в меню слева нажать на Удалить Pipeline.

Git репозиторий, содержащий некоторые config-файлы, удаляется вручную из файловой системы или через интерфейс используемого платформенного сервиса.

Проверка работоспособности#

Корректность настройки компонента Build Tools осуществляется путем сборки приложения, параметры которого указаны в соответствующей ветке репозитория в файле pipeline.yml, с последующим запуском Jenkins job и публикацией в хранилище Nexus.

Откат#

Возможен через установку новой версии (или посредством выполнения операции rollback к конкретной commit-версии внутри git).

Альтернативно откат на предыдущую версию можно осуществить с помощью Jenkins job.

Для этого в параметрах Jenkins job и в разделе SCM, в поле Branch Specifier указать нужную для перехода версию – tag и нажать Сохранить.

Таким образом, при следующем запуске Jenkins job будет запущена на указанной в параметрах версии.

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

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

• ТУЗ для работы с репозиториями или хранилищами артефактов заблокирован или истек срок действия прав доступа.

  Необходимо обратиться к владельцу/администратору инсталляции.

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

  Необходимо обратиться к владельцу/администратору инсталляции.

• Формирование файлов конфигураций .yaml было совершено с ошибками или пользователем были допущены ошибки в синтаксисе при заполнении или же не были указаны все необходимые параметры.

  Провести ревизию заполненных параметров .yaml файла конфигурации.

Отдельно возникающие ошибки исправляются командой с выпуском новой версии (commit) библиотеки в git.

Чек-лист валидации установки#

Валидация установки выполняется путем запуска Jenkins job Build tools. Чек-лист валидации установки:

• Jenkins job завершен со статусом success;

• Дистрибутив приложения, параметры которого были указаны в Jenkins file, опубликован в хранилище Nexus.