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

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

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

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

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

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

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

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

Примечание:

*

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

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

**

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

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

Также, перед началом работы на узлах (nodes) Jenkins должны быть установлены следующие утилиты:

• yq – версии не ниже чем: 4.25.3;

• jq – версии не ниже чем: 1.6;

• Groovy - версии не ниже чем: 4.0.15.

Опционально можно использовать сервер приложений 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).