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

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

Термины и определения#

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

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

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

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

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

Примечание:

*

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

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

**

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

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

***

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

Существует опциональная возможность установки OpenJDK, kubectl, Ansible, yq, Helm, Apache Maven на узлы (nodes) Jenkins через функциональность гибкого инструментария Jenkins.

Опционально можно использовать сервер приложений WildFly. Про это написано в инструкции: Развертывание функциональных подсистем на сервер приложений WildFly

Информация по настройке интеграции с HashiCorp Vault приведена в разделе Интеграция с HashiCorp Vault (опционально).

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

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

Примечание:

***

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

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

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

Аппаратные требования#

Поскольку программный компонент представляет собой скрипты и конфигурации, хранящиеся (GitLab/BitBucket) и обрабатываемые (Jenkins) сторонними функциональными подсистемами, особых аппаратных требований к нему не предъявляется. Заказчиком самостоятельно определяются аппаратные мощности для развертывания и функционирования собственного решения, с помощью описываемого программного компонента CDJE, в зависимости от назначения приложения и требований к его архитектуре.

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

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

В соответствии с правилами, принятыми в вашей компании, должна быть создана проектная область в Jenkins c правами на создание Jenkins job у пользователя, производящего установку Deploy Tools.

Настройка стенда#

1. После распаковки дистрибутива артефакты должны быть размещены в репозиториях GitLab/BitBucket в соответствии с требованиями Руководства по установке продукта DOT. Перед началом установки DeployTools убедитесь, что вам известно правильное расположение артефактов по репозиториям GitLab/BitBucket.

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

3. Целевые репозитории для установки Deploy Tools должны располагаться в одной проектной области GitLab/BitBucket. В соответствии с правилами, принятыми в вашей компании, создайте пустой проект для выполнения работ по установке. Название проектной области может быть произвольное (например, exampleProjectName).

Формирование имен целевых репозиториев происходит по следующей формуле: <CE>_<SUBDIVISION>_<CHANNEL>_<REPO NAME>_<ENVIR>, где

CE – идентификатор продукта (необязательный параметр);

SUBDIVISION – идентификатор принадлежности к определенному подразделению (необязательный параметр);

CHANNEL – канал/сегмент/solution/monosolution, в топологии которого производится установка (данный параметр отвечает также за использование ряда глобальных настроек по умолчанию (environment.json, subsystems.json));

REPO_NAME – наименование репозитория конфигурации приложения (поле "fpi_name" в subsystems.json), невозможно использование зарезервированных имен для создания репозиториев конфигурации приложения: common, pipeline;

ENVIR – наименование стенда/среды, например: dev, mmv, ift, psi, prom.

Данные значения являются константами, которые будут необходимы при настройке Service job и Deploy job.

Подробнее с правилами наименования репозитория можно ознакомиться в разделе R1.1: Правила формирования имен репозиториев стенда.

4. В проектной области GitLab/BitBucket из п. 3 (например, exampleProjectName) должны быть созданы следующие целевые репозитории:

   a) Репозитории pipeline, например:

• <CHANNEL>_pipeline_<ENVIR> — репозиторий, который в процессе установки будет наполнен кодовой базой релизов pipeline (на каждый стенд свой репозиторий, например monosolution_pipeline_ift / monosolution_pipeline_psi);

• <CHANNEL>_common_<ENVIR> — репозиторий, который в процессе установки будет наполнен глобальными (одинаковыми для всех компонент в рамках одного стенда) переменными среды (на каждый стенд свой репозиторий, например monosolution_common_ift / monosolution_common_psi);

• <CHANNEL>_releases_<ENVIR> — репозиторий для версионирования версий приложения (один общий на все стенды).

  b) Репозитории с конфигурациями функциональных подсистем, например:

• indicator (на каждый стенд свой репозиторий);

• osiris (на каждый стенд свой репозиторий);

• unimon (на каждый стенд свой репозиторий).

5. В Nexus должны быть размещены дистрибутивы разворачиваемых функциональных подсистем.

6. В Nexus должны быть созданы следующие репозитории, в которые загружены дистрибутивы всех компонентов pipeline (Installer.Migration, Installer.Common):

   • Installer.Migration — дистрибутив утилиты миграции;

   • Installer.Common — базовый дистрибутив common — это глобальные параметры по умолчанию для pipeline.

7. Для ТУЗ необходимо обеспечить:

   • доступ по протоколам SSH + HTTP с правами на чтение репозиториев в GitLab/BitBucket из п. 3;

   • доступ по протоколам SSH + HTTP с правами на чтение/запись во все ветки, в т.ч. в ветку master репозиториев в GitLab/BitBucket из п. 4;

   • доступ с правами на чтение дистрибутивов в Nexus из п. 5 и 6;

   • доступ к дистрибутивам приложения, установка которых будет производиться с использованием Deploy Tools (один дистрибутив или более).

Создание и взаимодействие с реквизитами в Jenkins#

В Jenkins необходимо создать следующий набор credentials: Username with password, SSH with private key, Secret Text cred.

Подробнее о том, как создавать credentials и взаимодействовать с ними, можно прочитать в инструкции Jenkins.

Username with password#

Это Логин + Пароль реквизитов для работы с API Nexus, Bitbucket или Jenkins. Например, при получении списка веток или скачивании артефактов из Nexus.

В качестве ID необходимо указать user_pass_tech.
При указании ID отличного от user_pass_tech, необходимо будет произвести дополнительную настройку в Service job (CUSTOM_USER_PASS_CREDS) и в файле environment.json.

В качестве логина необходимо указать Логин используемого ТУЗ, а в качестве пароля – Пароль от ТУЗ (заполнение описания является опциональным).

SSH with private key#

Реквизиты для доступа к Bitbucket с помощью SSH ключа.

Для данного способа необходимо сгенерировать SSH ключ: приватный и публичный.

В качестве ID необходимо указать git_ssh_tech.
При указании ID отличного от git_ssh_tech, необходимо будет произвести дополнительную настройку в Service job (GIT_CRED) и в файле environment.json

В качестве логина необходимо указать Логин используемого ТУЗ, а для приватного ключа – содержимое файла id_rsa.ppk (приватный ключ), полученного в ходе генерации SSH ключа.

Если в ходе генерации SSH ключа вы указали пароль, его необходимо ввести в поле Passphrase (заполнение описания является опциональным).

Дополнительно необходимо добавить используемому ТУЗ публичную часть SSH ключа в Bitbucket (см. официальную инструкцию Bitbucket – Step 3.)

Secret Text cred#

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

В завершении в Bitbucket для используемого ТУЗ необходимо добавить публичную часть сгенерированного SSH ключа (см. пункт SSH with private key).

Установка#

Предусмотрены следующие инструменты развёртывания:

• Service job — Jenkins job обновления (первичная загрузка кода Deploy на полигон, обновление кода Deploy job при выпуске новых релизов Deploy job);

• Deploy job — Jenkins job развертывания дистрибутивов.

Данная инструкция описана для создания одного экземпляра набора Jenkins job. На каждый фрагмент контура платформы создается отдельный набор job.

Создание Service job#

Service job предназначен для миграции кодовой базы pipeline и общих параметров (common) из дистрибутива common на стенд.

В инсталляции Jenkins создайте новый Item с типом pipeline и произвольным названием (например, Service):

1. Нажмите на кнопку New Item ;

2. Выберите тип Pipeline.

3. Настройки секции General:

   Необходимо выбрать: Pipeline script from SCM → SCM → Git.
   

   Параметры:

   • Repository URL: SSH адрес релизного репозитория из п. 1 раздела Подготовка окружения (monosolution_pipeline.git)

   • Credentials: SSH with private key

   • Branch Specifier: service

   • Script Path: deploy-fpi-service.groovy

4. Настройки секции Property Content:

   Необходимо выбрать: General –> Prepare an environment for the run –> Property Content
   

   Параметры:

   • ENVIR=mmv — наименование стенда (условное название стенда, например mmv или ift — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения);

   • NODE=Linux_Default — Агент Jenkins, на котором будет произведен запуск (приведен пример значения);

   • CONFIG_DIR_LIST=main:main (здесь main — директория конфигурации стенда, директория конфигурации в общем случае может быть только одна).

   • CHANNEL=monosolution — используется для идентификации принадлежности к продукту (приведен пример значения — значение должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения);

   • GIT_URL=ssh://<SCM_address>/exampleProjectName — проектная область стенда в SCM системе

   • SCM_RELEASE_REPO_REPOSITORY_NAME=DeployTools_pipeline — наименование репозитория релизов pipeline (приведен пример значения - значение — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

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

   Расширенные настройки конфигурации описаны в разделе "Экспертное использование Service job".

5. Сохраните настройки и выполните реконфигурацию Jenkins job — запуск Service job без параметров. Это приведет к автоматической настройке Service job и отображения параметров на странице "Собрать с параметрами" Jenkins.

6. Чтобы убедиться, что реконфигурация выполнена успешно, попробуйте вновь открыть вкладку для запуска Service job. Должен отобразиться следующий список параметров, при помощи которых осуществляется управление Service job:

   • SERVICE_VERSION - версия Service job, запуск необходимо производить на релизе service, он содержит все последние доработки (при неработоспособности данной версии, необходимо выбрать service_stable)

   • CONFIG_DIR - директория конфигурации в которую будет произведена миграция / установка релиза

   • ARTIFACT_TYPE - тип обновляемого артефакта

   • ARTIFACT_VERSION - версия, до которой необходимо обновить компонент

   • PARAMS - сценарии использования, подробнее в разделе Выполнение последовательной миграции pipeline, subsystems, common.

Сценарии использования Service job#

1. PIPELINE:

   • MIGRATION — миграция кода/библиотек pipeline, а так же миграция основного файла конфигураций на стенд (environment.json_);

   • MIGRATE_DEPLOY_SCRIPTS — миграция скриптов запуска для Jenkins job;

   • JOBS_RECONF_ALL — реконфигурация Jenkins jobs, указанных в файле JenkinsJobs.conf.

2. COMMON:

   • MIGRATION — миграция файлов из дистрибутива common в репозиторий common;

   • MIGRATION_SUBSYSTEMS — миграция файлов конфигураций устанавливаемых компонентов subsystems_<segment>.json;

   • SOFT_COMMON_MIGRATION - "нежная" миграция конфигураций репозитория common через pull request (для данного сценария необходимо задать ревьюверов в environment.json в поле softMigrationReviewers: []);

   • UPDATE_PLATFORM_CONF - импорт параметров платформы в канальный сектор (необходима предварительная настройка environment.json);

   • MERGE_COMMON_REPO - миграция репозиториев common;

   • MIGRATION_CONFIGURATION - миграция конфигурации (environment.json).

3. PIPELINE_AT:

   • MIGRATION — миграция кода/библиотек pipeline AT (Job автотестов).

4. PIPELINE_ORCH:

   • MIGRATION — миграция кода/библиотек pipeline ORCH (Job оркестрации).

5. PIPELINE_SCHEDULER:

   • MIGRATION — миграция кода/библиотек pipeline scheduler (AutoInstaller job).

6. PIPELINE_EXTENSIONS:

   • MIGRATION — миграция кода/библиотек pipeline extensions (Точки расширения для pipeline).

Выполнение последовательной миграции pipeline, subsystems, common#

1. Pipeline:

   Запустите Service job со следующими параметрами для обновления версии pipeline:

   Входные параметры:

   • CONFIG_DIR : main (main — директория, в которой будет размещен репозиторий)

   • ARTIFACT_TYPE : PIPELINE

   • ARTIFACT_VERSION : release/D-01.038.172-11404 (например)

   • PARAMS : MIGRATION, MIGRATE_DEPLOY_SCRIPTS

   Поле SERVICE_VERSION предназначено для выбора версии Service job, при помощи которой будут производиться миграции. В общем случае нет необходимости в изменении значения SERVICE_VERSION, так как по умолчанию это всегда самая последняя версия Service job.
   Изменение значения данного параметра необходимо только при невозможности использовать последнюю версию (из-за неработоспособности кода последней версии). В таком случае в списке SERVICE_VERSION необходимо выбрать более раннюю версию (которая была передана в прошлом составе DOT) и производить требуемые запуски уже с выбранной версией.

   Результат:

   Репозиторий common содержит в заданной директории CONFIG_DIR набор файлов:

   • environment.json — основной конфигурационный файл Pipeline (создается, если ранее отсутствовал, или перезаписывается при помощи environment.json из релиза).

   • version.conf — версии pipeline, common, scripts (создается, если ранее перезаписывается, или перезаписывается).

   В репозитории pipeline:

   • Ветка master обновлена до состояния service ветки, в которой хранятся загрузчик разделяемой библиотеки для всех Jenkins jobs развертывания (deploy-fpi.\*.groovy).

   • Создана ветка release/D-01.038.172-11404 (номер ветки — это значение, которое было указано в ARTIFACT_VERSION).

   • Файл version.conf содержит корректную версию pipeline (номер ветки — то значение, которое было указано в ARTIFACT_VERSION, например release/D-01.038.172-11404);

   • В файле environment.json обновлены секции: _default и секция по названию стенда (ENVIR в настройках Jenkins job).

2. Subsystems:

   Запустите Service job со следующими параметрами:

   Входные параметры:

   • CONFIG_DIR : main

   • ARTIFACT_TYPE : COMMON

   • ARTIFACT_VERSION : D-01-001.00.313 (например)

   • PARAMS : MIGRATION_SUBSYSTEMS

   Результат:

   Репозиторий common содержит в заданной директории файлы:

   • subsystems.json — список конфигураций приложения для Deploy job (создается из релиза service ветки, если ранее отсутствовал, или перезаписывается);

   • subsystems_elk.json — список конфигураций приложения для ELK job (создается из релиза service ветки, если ранее отсутствовал, или перезаписывается);

   • subsystems_spo.json — список конфигураций приложения для SPO job (создается из релиза service ветки, если ранее отсутствовал, или перезаписывается).

3. Common:

   Запустите Service job со следующими параметрами:

   Входные параметры:

   • CONFIG_DIR : main

   • ARTIFACT_TYPE : COMMON

   • ARTIFACT_VERSION : D-01-001.00.313 (например)

   • PARAMS : MIGRATION

   Результат:

   В репозитории common в директории main появятся папки hosts, parameters и ansible.

Больше информации изложено в разделе Service job.

Настройка глобальных параметров#

Используемое имя monosolution — это пример наименование репозитория выбранного в примерах ранее.

a) в репозитории monosolution_common откройте файл environment.json в директории конфигурации main и переопределите параметры:

{
   "efsReleaseRepo": "https://<bitbucket_projects_address>/<наименование проектной области из п. 1 раздела Подготовка окружения>/repos
   /monosolution_releases", // это пример, здесь необходимо указать ссылку на свой репозиторий 
   с monosolution_releases
   "iag": "true",
   "openshiftMultiClusters": "true",
   "useMavenForDownload": "true",
   "openshiftRegistry": "http://<registry_address>/exampleProjectName/Channel"
   // это пример, здесь необходимо указать ссылку на свой проект в OSE.
}

С расширенным перечнем параметров настройки файла environment.json можно ознакомиться в разделе "Работа с файлом environment.json" документа "Руководство по системному администрированию".

b) в репозитории monosolution_common откройте файл subsystems.json и заполните параметры:

{  
   "__default":
    {   			        // Блок настроек по умолчанию.
      "classifier": "distrib",  	        // Классификатор дистрибутива приложения в хранилище Nexus
      "groupId": "Nexus_PROD",  	        // Group ID дистрибутива приложения в хранилище Nexus
      "packaging": "zip",  		        // Расширение файла с дистрибутивом приложения
      "strict": "false",  		        // Режим миграции настроек приложения (true - будут мигрировать только файлы, начинающиеся на <fpi_name>, false - все конфигурационные файлы)
      "sqlReport": "false",  
      "limit": 200,  				        // Ограничение кол-ва версий дистрибутива в меню Jenkins
      "deployType": "manual",  	        // Тип автоматического развертывания (parallel - 
       параллельный, consistently - последовательный)
      "fpType": "p69",  			        // Указываем тип приложения для фильтрации в job. 
      "openshiftProject": "",  
      "at": {  					        // Блок с реквизитами дистрибутива API-автотестов по умолчанию
         "groupId": "Nexus_PROD",  	        // Group ID дистрибутива API-автотестов
         "branch": "master",  		        // Ветка репозитория с настройками API-автотестов по умолчанию
         "classifier": "distrib",  	        // Классификатор дистрибутива API-автотестов по умолчанию
         "packaging": "zip"  		        // Расширение дистрибутива API-автотестов по умолчанию
      },  
      "at_ui": {  				        // Блок с реквизитами дистрибутива UI-автотестов по умолчанию
      "groupId": "Nexus_PROD",  	        // Group ID дистрибутива UI-автотестов
      "branch": "master",  		        // Ветка репозитория с настройками UI-автотестов по умолчанию
      "classifier": "distrib",  	        // Классификатор дистрибутива UI-автотестов по умолчанию
      "packaging": "zip"  		        // Расширение дистрибутива UI-автотестов по умолчанию
      }  
    },  
    "INDICATOR":
    {  
      "fpType": "bts",  					// Указываем тип приложения для фильтрации в Jenkins job. Для выбора нескольких вариантов указываем в настройках job FP_TYPE_FILTER=bts, bfs
      "fpi_name": "indicator",  			// Название приложения в AENG
      "artifactId": "PVM_Indicator",  
      "groupId": "Nexus_PROD.monosolution_new_main",  
      "versionFilter": "D-01"  
    }  
}

С расширенным перечнем параметров настройки файла subsystems.json можно ознакомиться в разделе "Работа с файлом subsystems.json" документа "Руководство по системному администрированию".

c) в репозитории monosolution_common откройте installer/system/efs/config/parameters файл _global.resources.conf и заполните параметры значениями host в соответствии с архитектурой развертываемого стенда, либо сделайте заглушки, например:

Пример с заглушками (dummy)
# mm — межмодульное взаимодействие
global.default.nlb_mm.host=dummy 
# ii — интеграционное взаимодействие (для импорта)
global.default.nlb_ii.host=dummy  
# bh — бизнес хаб
global.default.nlb_bh.host=dummy

пример с хостами
# адрес балансировщика  без протокола и порта
# mm — межмодульное взаимодействие
global.default.nlb_mm.host=tkli-efs11692.<domain_address>
# ii — интеграционное взаимодействие (для импорта)
global.default.nlb_ii.host=tkli-efs11693.<domain_address>
# bh — бизнес хаб
global.default.nlb_bh.host=tkli-efs11695.<domain_address>

d) в репозитории monosolution_common откройте файл multiClusters.json и заполните параметры:

Пример:

{  
 "datacenters":
 {  
   "megacod":
   {  
      "openshiftCluster": "[https://<api_dev_address>](https://<api_dev_address>/)",   		// Адрес вашего OSE кластера 1
      "openshiftSATokenCred": "ose_token_cred_ift",  										// Имя Jenkins credentials (тип - secret text), содержащего токен service учетной записи сервисного проекта OSE кластера 1. Используется для доступа к API OpenShift.
      "openshiftProjectName": "exampleProjectName-i-as-monosolution-solution",  							// Имя вашего проекта в OSE в кластере 1
      "openshiftAppsDomain": "[<sh1_dev_address>](http://<sh1_dev_address>/)",  				// Суффикс домена для сервисов вашего кластера. Значение этого параметра подставляется в параметр {{appsDomain}} в конфигурации развертывания OSE в процессе развертывания.
      "openshiftWebConsole": "<https://<console_openshift_address>/k8s/cluster/projects>", 	// Ссылка на кластер OpenShift для формирования корректной ссылки на проект в описании Deploy job 
      "openshiftRoutersFQDN": \[ '1.1.1.1' \]  												// Fully qualified domain name или ip адрес роутера/ов OpenShift. Этот адрес можно узнать у ЦИ. Либо, на средах до ПСИ, можно попробовать сделать ping любому routes в проекте. Все пути внутри проекта (скорее, кластера) по wildcards резолвятся в один или более адресов нод, на которых располагаются HAProxy OpenShift (или, возможно, в балансировщик перед этими nod'ами).
   }  
 }  
}

Дополнительная информация о заполнении multicluster.json размещена в разделе K8s: Развертывание в Kubernetes/OpenShift, блок "Заполнение настроек в файле multiclusters.json".

e) Отредактируйте файлы secret.yml (зашифрованный файл) и _password.conf (файлы размещены в директории/ansible):

• secret.yml (пароли от БД/WAS/Шлюзы) — зависит от диаграммы развертывания разворачиваемого сервиса;

• _password.conf (секреты для OSE);

Шифрование данных конфигурационных файлов необходимо производить на сервере с установленными openssl и ansible.

Шифрование _passwords.conf производится следующими командами:

• для шифрования используйте: openssl enc -aes-256-cbc -md md5 -salt -in _passwords_d.conf -out _passwords.conf

• для расшифровывания используйте: openssl enc -aes-256-cbc -md md5 -salt -in _passwords.conf -out _passwords_d.conf -d

Шифрование secret.yml производится следующими командами:

• для шифрования используйте: ansible-vault encrypt secret.yml

• для расшифровывания используйте: ansible-vault decrypt secret.yml

• "ansible_vault_id": "encrypt_secret" — ID данных credential с паролем, которым был зашифрован файл secret.yml (ID может быть любым, здесь в значении параметра приведен пример);

• "openshiftOpsPasswordsCred": "encrypt_pass" — ID данных credential с паролем, которым зашифрован файл passwords.conf (ID может быть любым, здесь в значении параметра приведен пример).

f) Создайте для ТУЗ credentials в проектной области, в которой производится настройка job, следующих типов:

• SSH Username with private key в нем укажите приватный ключ + Passphrase (если есть) от ТУЗ;

• Username with password в нем укажите логин/пароль от ТУЗ.

Чтобы создать credentials для входа:

1. После миграции в вашем файле присутствуют две секции: _default и секция по названию стенда (ENVIR в настройках Jenkins job). Подробнее про заполнение environment.json написано в разделе Заполнение конфигурационного файла для Service Job.

2. В файле environment.json переопределите для своей среды секцию credentials (скопируйте значение из блока default).

3. Для credentials SshKeyCreds и UserPassCreds переопределите id, которые были созданы ранее (SshKeyCreds = id от Jenkins credentials SSH Username with private key, UserPassCreds = id от Jenkins credentials Username with password).

Пример:

   "ift": {                               // Настройки среды "ift". 
   "credentials": {                       // Настройки Credential ID
   "SshKeyCreds": "pipeline_git_ssh",     // Credential ID для доступа в репозитории Git с использованием ssh-ключей (ssh ключ)
   "UserPassCreds": "697864ec-a6f8-40d7-a68c-9402566ecaa8",  	// Credential ID для доступа в хранилище Nexus с использованием base аутентификации (логин/пароль)
}

Создание Deploy job#

Deploy job предназначен для установки приложения на стенд.

В инсталляции Jenkins создайте Jenkins job с произвольным названием (например, Deploy):

1. Нажмите кнопку New item ;

2. Выберите тип Pipeline.

3. Настройки секции General:
   В области Definition выберите Pipeline scripts from SCM → в SCM выберите Git и заполните параметры:

   • Repositories — созданный ранее репозиторий monosolution_pipeline — репозиторий с кодовой базой релизов pipeline (см. раздел Подготовка окружения);

   • Credentials — созданный ранее credentials Jenkins SshKeyCreds (см. раздел Подготовка окружения);

   • Script Path — deploy-fpi.groovy.

     

     

4. Настройки секции Property Content:
   Необходимо выбрать: General –> Prepare an environment for the run –> Property Content

   Параметры:

   • NODE=Linux_Default || kubernetes || OpenShift (Jenkins slave, на которых будет выполняться операция развертывания)

   • ENVIR=mmv — наименование стенда (условное название стенда, например mmv или ift — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • CONFIG_DIR_LIST=main:main (блок стенда) — (здесь main — директория конфигурации стенда, директория конфигурации в общем случае может быть только одна)

   • CHANNEL=monosolution (сегмент) — приведен пример значения (значение должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • SCRIPTS_GIT_SSH_URL=<SSH путь до репозитория Ansible-скриптов (см. пункт 1. → раздела Подготовка окружения)>.

   

5. Сохраните настройки и выполните реконфигурацию Jenkins job — запуск Service job без параметров.

6. Чтобы обеспечить поддержку веток, необходимо выполнить шаги, описанные в разделе "1. Настройка веток (упрощенный вариант)" документа "Управление версиями репозиториев конфигураций".

Настройка закончена. Можно выполнять установку приложения.

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

Создание ELK job#

ELK job предназначен для установки компонентов Elastic Search (далее ELK).

В инсталляции Jenkins создайте Jenkins job с произвольным названием (например, ELK):

1. Нажмите кнопку New item ;

2. Выберите тип Pipeline.

3. Настройки секции General:
   В области Definition выберите Pipeline scripts from SCM → в SCM выберите Git и заполните параметры:

   • Repositories — созданный ранее репозиторий monosolution_pipeline — репозиторий с кодовой базой релизов pipeline (см. раздел Подготовка окружения);

   • Credentials — созданный ранее credentials jenkins SshKeyCreds (см. раздел Подготовка окружения);

   • Script Path — deploy-fpi-elasticsearch.groovy.

   

4. Настройки секции Property Content:
   Необходимо выбрать: General –> Prepare an environment for the run –> Property Content

   Параметры:

   • NODE=Linux_Default || kubernetes || OpenShift (Jenkins slave, на которых будет выполняться операция развертывания)

   • ENVIR=mmv — наименование стенда (условное название стенда, например mmv или ift — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • CONFIG_DIR_LIST=main:main (блок стенда) — (здесь main — директория конфигурации стенда, директория конфигурации в общем случае может быть только одна)

   • CHANNEL=monosolution (сегмент) — приведен пример значения (значение должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • SCRIPTS_GIT_SSH_URL=<SSH путь до репозитория Ansible-скриптов (см. пункт 1. → раздела Подготовка окружения)>.

   

5. Сохраните настройки и выполните реконфигурацию Jenkins job — запуск Service job без параметров.

Создание SPO job#

SPO job предназначен для установки компонентов SPO (специальное программное обеспечение).

В инсталляции Jenkins создайте Jenkins job с произвольным названием (например, SPO):

1. Нажмите кнопку New item ;

2. Выберите тип Pipeline.

3. Настройки секции General:
   В области Definition выберите Pipeline scripts from SCM → в SCM выберите Git и заполните параметры:

   • Repositories — созданный ранее репозиторий monosolution_pipeline — репозиторий с кодовой базой релизов pipeline (см. раздел Подготовка окружения);

   • Credentials — созданный ранее credentials Jenkins SshKeyCreds (см. раздел Подготовка окружения);

   • Script Path — deploy-fpi-spo.groovy.

   

4. Настройки секции Property Content:
   Необходимо выбрать: General –> Prepare an environment for the run –> Property Content

   Параметры:

   • NODE=Linux_Default || kubernetes || OpenShift (Jenkins slave, на которых будет выполняться операция развертывания)

   • ENVIR=mmv — наименование стенда (условное название стенда, например mmv или ift — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • CONFIG_DIR_LIST=main:main (блок стенда) — (здесь main — директория конфигурации стенда, директория конфигурации в общем случае может быть только одна)

   • CHANNEL=monosolution (сегмент) — приведен пример значения (значение должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • SCRIPTS_GIT_SSH_URL=<SSH путь до репозитория Ansible-скриптов (см. пункт 1. → раздела Подготовка окружения)>.

   

5. Сохраните настройки и выполните реконфигурацию Jenkins job — запуск Service job без параметров.

Настройка закончена. Можно выполнять установку SPO.

Создание Security job#

Security job предназначен для администраторов для настройки новых КТС и перенастройки уже имеющихся.

В инсталляции Jenkins создайте Jenkins job с произвольным названием (например, Security):

1. Нажмите кнопку New item ;

2. Выберите тип Pipeline.

3. Настройки секции General: В области Definition выберите Pipeline scripts from SCM → в SCM выберите Git и заполните параметры:

   • Repositories — созданный ранее репозиторий monosolution_pipeline — репозиторий с кодовой базой релизов pipeline (см. раздел Подготовка окружения);

   • Credentials — созданный ранее credentials jenkins SshKeyCreds (см. раздел Подготовка окружения);

   • Script Path — deploy-fpi-security.groovy.

   

4. Настройки секции Property Content:
   Необходимо выбрать: General –> Prepare an environment for the run –> Property Content

   Параметры:

   • NODE=Linux_Default || kubernetes || OpenShift (Jenkins slave, на которых будет выполняться операция развертывания)

   • ENVIR=mmv — наименование стенда (условное название стенда, например mmv или ift — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • CONFIG_DIR_LIST=main:main (блок стенда) — (здесь main — директория конфигурации стенда, директория конфигурации в общем случае может быть только одна)

   • CHANNEL=monosolution (сегмент) — приведен пример значения (значение должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • SCRIPTS_GIT_SSH_URL=<SSH путь до репозитория Ansible-скриптов (см. пункт 1. → раздела Подготовка окружения)>.

   

5. Сохраните настройки и выполните реконфигурацию Jenkins job — запуск Service job без параметров.

Настройка закончена. Можно выполнять установку SPO.

Создание Integration Job#

Integration Job предназначен для настройки интеграционных компонентов на полигоне: в частности MQ и Kafka, и представляет собой Security job с отдельными сценариями запуска (playbooks).

Этапы создания будут аналогичны описанным в разделе выше (см. Создание Security job).

Сценарий развертывания KAFKA_UPDATE_FP, позволяющий создавать топики в кластере Kafka требует предварительно настройки параметров, указанных в файле конфигурации kafka_fp.<fp_name>.json, который необходимо разместить в директории /conf/config/definitions:

{
    "create_point_to_point_objects": "${create_point_to_point_objects}",
    "point_to_point": {
          "fp_ID": "${fp_ID}",
          "partitions": "${point_to_point.partitions}",
          "replication_factor": "${point_to_point.replication_factor}",
           "retention_ms": "${point_to_point.retention_ms}",

           "retention_bytes": "${point_to_point.retention_bytes}",
           "max_message_bytes": "${point_to_point.max_message_bytes}"
    },
    "create_pubsub_objects": "${create_pubsub_objects}",
    "pubsub": {
          "partitions": "${pubsub.partitions}",
          "replication_factor": "${pubsub.replication_factor}",
          "retention_ms": "${pubsub.retention_ms}",

          "retention_bytes": "${pubsub.retention_bytes}",
          "max_message_bytes": "${pubsub.max_message_bytes}",
          "topics_list": [
               "${pubsub_1_name}",
               "${pubsub_2_name}"
          ]
     }

}

Параметрами для заполнения данного файла являются:

В результате для создания топиков Kafka необходимо:

1. Добавить в дистрибутив конфигурационные файлы kafka_fp.<fp_name>.conf, заполненные по инструкции выше.

2. Использовать версию pipeline не ниже release/D-01.038.500-21695.

3. Выполнить миграцию дистрибутива common на версию не ниже CI01027901_AS_EFS_Installer_Common_UKOFL-D-01.001.00-132 (для сегмента Platform V Frontend High Load).

4. Использовать версию скриптов Ansible не ниже release/D-01.001.0-450.

5. Написать ЗНО, в котором будут заданы создать следующие правила ACL на кластере Kafka:

   Resource type	Resource name	Principal	Host	Operation	Permission type
   TOPIC	*	DN сертификата gatewayClientCer	*	READ	ALLOW
   CLUSTER	kafka-cluster	DN сертификата gatewayClientCer	*	ALTER	ALLOW
   CLUSTER	kafka-cluster	DN сертификата gatewayClientCer	*	CREATE	ALLOW
   GROUP	*	DN сертификата consumer-приложения	*	READ	ALLOW
   GROUP	*	DN сертификата consumer-приложения	*	DESCRIBE	ALLOW

Сертификат gatewayClientCer должен быть включен в Jenkins credentials, именно из-под этого сертификата будет работать Jenkins job в режиме mTLS.

Следующим шагом, на стенде необходимо сослаться в inventory приложения группы Kafka на группу брокеров из globalInventory :

[local]
localhost ansible_connection=local

[kafka:children]
unified_cluster # Группа с брокерами KAFKA из globalInventory

.....................

[hosts:children]
local
kafka
.....................

В свою очередь в группе брокеров Kafka в globalInventory необходимо обязательно указать параметр listener_port (должен быть равен порту listeners Kafka: обычно 9092 или 9093).

Опционально, можно задать режим работы Jenkins job (с поддержкой mTLS или без нее), через параметр mtls_mode. Если не указать параметр в globalInventory, то будет взят одноименный параметр из среды common (файл kafka_common.conf.yml).

Пример заполнения globalInventory :

[unified_cluster:vars]

listener_port=9092

mtls_mode=true

ansible_user="{{ kafka_user }}"

ansible_ssh_pass="{{ kafka_ssh_pass }}"

# Либо ключ ansible_ssh_private_key_file="{{ xxxx_ssh_cred }}"

[unified_cluster]

xxx.xxx.xxx.xxx

yyy.yyy.yyy.yyy

zzz.zzz.zzz.zzz

Для корректной выдачи ACL на топики необходимо заполнить параметр mtls_dn из среды common (файл kafka_common.conf.yml). По умолчанию данный параметр идет пустой строкой, нв которую необходимо вписать DN от клиентских сертификатов приложения.

Подробнее о настройке Kafka см. в инструкции.

Создание AT MVN job#

AT MVN job предназначен для запуска тестов, разработанных командой устанавливаемого компонента. Jenkins job производит запуск в оффлайн режиме, в связи с этим требуется собранный дистрибутив с зависимостями, используемыми командами, при запуске тестов и приложения.

Пререквизиты:

• Дополнительная проектная область в SCM системе аналогичная по наименованию уже созданной, с добавлением суффикса _at. Пример: exampleProjectName → exampleProjectName_at.

• Репозиторий pipeline, аналогичный созданному в основной области с добавлением суффикса _at. Пример: monosolution_pipeline → monosolution_pipeline_at.

• Миграция АТ репозитория при помощи Service job.

В инсталляции Jenkins создайте Jenkins job с произвольным названием (например, Security):

1. Нажмите кнопку New item ;

2. Выберите тип Pipeline.

3. Настройки секции General: В области Definition выберите Pipeline scripts from SCM → в SCM выберите Git и заполните параметры:

   • Repositories — созданный ранее репозиторий monosolution_pipeline_at — репозиторий с кодовой базой релизов pipeline (см. раздел Подготовка окружения);

   • Credentials — созданный ранее credentials jenkins SshKeyCreds (см. раздел Подготовка окружения);

   • Script Path — deploy-fpi-at-mvn.groovy.

   

4. Настройки секции Property Content:
   Необходимо выбрать: General –> Prepare an environment for the run –> Property Content

   Параметры:

   • NODE=Linux_Default || kubernetes || OpenShift (Jenkins slave, на которых будет выполняться операция развертывания)

   • ENVIR=mmv — наименование стенда (условное название стенда, например mmv или ift — должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • CONFIG_DIR_LIST=main:main (блок стенда) — (здесь main — директория конфигурации стенда, директория конфигурации в общем случае может быть только одна)

   • CHANNEL=monosolution (сегмент) — приведен пример значения (значение должно совпадать с идентификатором репозиториев, созданных в п.3 раздела Подготовка окружения)

   • SCRIPTS_GIT_SSH_URL=<SSH путь до репозитория Ansible-скриптов (см. пункт 1. → раздела Подготовка окружения)>.

   

5. Сохраните настройки и выполните реконфигурацию Jenkins job — запуск Service job без параметров.

Настройка закончена. Можно выполнять запуск АТ.

Обновление#

Обновление проводится через запуск Service Job:

• Необходимо выполнить миграцию Pipeline (процедура описана в подразделе Проведение последовательной миграции pipeline, subsystems, common).

Удаление#

Удаление осуществляется через UI Jenkins:

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

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

Пример информации о записи файлов в логах Jenkins job:

Откат#

Откат для Deploy job#

При необходимости выполнить откат (или повторную установку/обновление) до валидной версии pipeline можно воспользоваться штатным механизмом программного компонента, запустив в Service Job, и указав в нем следующие параметры:

• ARTIFACT_TYPE: PIPELINE

• ARTIFACT_VERSION: <номер валидной версии, на которую необходимо выполнить откат>

• PARAMS: MIGRATION

  

Откат для Service job#

Механизм отката для Service job подразумевает собой выбор требуемой версии ветки /release_service в настройках UI Jenkins job.

Пример выбора версии в настройках:

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

Ошибки в механизмах отката, связанные с ошибкой в коде механизма#

1. В git-репозитории кода pipeline вашего полигона найти ID commit, в комментарии которого указана предыдущая стабильная версия (на которую хотите сделать откат). Пример комментария: <<Migration pipeline library - release/D-01.036.207-3692>>;

2. Выполнить откат кода на этот ID (требуется доступ к git репозиторию на изменение ветки master и локально установленный и настроенный git). Или запросить у уполномоченных специалистов поддержки инфраструктуры вашего полигона выполнить этот откат.

Git команды для выполнения отката:

    git clone <ssh путь до репозитория с кодом pipeline на вашем полигоне>;
    cd <имя репозитория>;
    git checkout master;
    git reset --hard <id коммита из пункта 1>;
    git push --force.

Ошибки в структуре файлов-конфигураций pipeline (environment.json, subsystems.json)#

Восстановить корректность формата файла одним из следующих способов:

1. Если ошибка структуры файла визуально локализуется — исправить ее вручную.

2. Если причина ошибки не ясна, выполнить откат на предыдущую версию файла:

   • открыть проблемный файл в WEB интерфейсе GitLab/BitBucket;

   • в меню history выбрать один из предыдущих commit, с которым работоспособность pipeline была корректной;

   • выделить текст файла и скопировать в буфер обмена;

   • вернуться на последнюю версию этого файла (через выпадающий список в меню history),

   • нажать edit и вставить скопированную версию файла, перезаписав его текущий контент;

   • повторить откат/установку версии pipeline штатным механизмом (service job → MIGRATION_PPL_DEPLOY).

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

После выполнения процедуры, описанной в разделе 2, проверьте наличие файлов в репозиториях:

1. В репозитории common (если был задан параметр CONFIG_DIR, то файлы будут расположены в указанной в нём директории):

   • subsystems.json — список конфигураций приложения для Deploy job;

   • environment.json — основной конфигурационный файл pipeline (создается, если ранее отсутствовал, если есть, то мигрируется);

   • jenkinsJobs.conf — список удаленных Jenkins jobs (необходим только для JOB_RECONF_ALL) (создается, если ранее отсутствовал);

   • version.conf — версии pipeline, common, ansible scripts (создается, если ранее отсутствовал, если есть, то мигрируется);

   • в директории main появятся две папки: ansible и installer.

2. В репозитории pipeline:

   • ветка master обновилась до состояния service ветки (в ней хранятся загрузчик и разделяемые библиотеки для всех Deploy jobs) (deploy-fpi.\*.groovy);

   • ветка release/D-01.038.172-11404 создалась (номер ветки — это значение, которое было указано в ARTIFACT_VERSION);

   • в файле environment.json обновлены секции: _default и секция по названию стенда (ENVIR в настройках Jenkins job).