SynapseInstaller#

Jenkins Job, в котором происходит установка конфигураций из дистрибутива в проект системы оркестрации приложений.

Результатами работы Jenkins Job являются:

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

Особенности:

Отправляет в систему анализа и статистики информацию о дистрибутиве и стенде для установки перед тем, как установить конфигурации из дистрибутива в проект системы оркестрации приложений.
Расшифровывает secret(s) из репозитория SCM (подробности см. в подразделе «Работа с secret(s)» раздела «Полезные материалы» текущего документа).
От вашего проекта нужно скопировать токен для доступа в проект и поместить в Credentials пространства Jenkins или в HashiCorp Vault. Можно использовать OrchestratorToken (описанного в подразделе «Pipelines» раздела «Дополнительная документация» текущего документа). Также можно вводить пароль руками, активировав параметр needInputOrchestratorLogin.
Перед каждой загрузкой может выполнять команду apply с ключом --dry-run=true и --dry-run=server для валидации изменений (стандартным схемам системы оркестрации и компонентой VALD (при наличии)), которые вносят конфигурационные файлы.
Имеется возможность включения подтверждения "второй рукой" (параметр needSecondApprove). Список разрешенных людей (логины) для подтверждения "второй рукой" прописывается в SubmitterAllowed.
Установка конфигурационных файлов в проект системы оркестрации приложений производится в следующем порядке: VirtualServices, DestinationRules, все остальное, Gateways, Deployments.
Может производить проверку наличия всех необходимых стендозависимых параметров в репозитории (шаг CheckTemplateParams.groovy (описан в подразделе «Шаги» раздела «Дополнительная документация» документа «Руководство прикладного разработчика»)).
По завершении работы проставляет в Jira задачу и в Jira Release, в рамках которых передается дистрибутив комментарий с результатами установки.
После успешной установки может передвинуть Jira задачу, в рамках которой передается дистрибутив, в необходимый статус. (для этого необходимо добавить два заполненных дополнительных файла teamSettings.json и jiraTransitionsMap.json (описаны в подразделе «Дополнительные файлы (additionalFiles)» раздела «Дополнительная документация» документа «Руководство прикладного разработчика»)).
Работа с templates подробно описана в подразделе «Работа с template в SynapseInstaller» раздела «Полезные материалы» текущего документа.
Вызов проверки результатов установки (параметр needSynaiCheck). Происходит вызов компоненты SYTL.
Откат к исходному состоянию в случае неуспешной установки.
Сравнение устанавливаемых конфигураций и того, что находится в проекте. Изменения отображаются в виде pull-request в репозитории SCM.
Возможность установки бэкапа из репозитория, собранным BackupMaker (описанного в подразделе «Pipelines» раздела «Дополнительная документация» текущего документа) или конфигураций из репозитория стендозависимых параметров. Важно! Для установки бэкапа одного проекта в другой, данный бэкап необходимо перенести в репозитории с бэкапами в каталог, названный именем проекта, в котором его планируют устанавливать.

Jenkins Job использует:

tool helm для обработки Helm Chart;
tool python для запуска Python скриптов;
tool executor для работы с системой оркестрации приложений;
tool processor для работы с системой оркестрации приложений;
tool precheckExecutor для запуска dry-run установки конфигураций;
tool yq для чтения YAML конфигураций.

Для настройки Jenkins Tool необходимо ознакомиться с разделом «Взаимодействие с Jenkins Tools» документа «Руководство по системному администрированию».

Функции Jenkins Job:

Название функции	Описание функции	Инструкция по настройке/включению
Удаление ресурсов	«Удаление ресурсов в проекте системы оркестрации приложений» раздел «Полезные материалы» текущего документа	Не требуется настройка/включение
Включение подтверждения удаления конфигураций "второй рукой"	При удалении конфигураций, после подтверждения удаления инициатором запуска Jenkins Job, потребуется подтверждение другого пользователя	В пользовательском конфигурационном файле в репозитории конфигураций SMDL.Configs определить параметр needSecondApproveDeleteConfigs равным `true`
Увеличение количества реплик у новой версии приложения при канареечном развертывании до уровня старой версии приложения	Количество реплик старой версии приложения будет увеличено, если у новой версии приложения количество реплик меньше, чем у старой версии	В пользовательском конфигурационном файле в репозитории конфигураций SMDL.Configs определить параметр needScaleNewPods равным `true` (Значение по умолчанию равно `false`)
Включение возможности выбора Helm Charts, которые необходимо установить	Возможность выбора устанавливаемого Helm Charts, которые расположены в дистрибутиве	На экране запуска Jenkins Job задать параметр needInstallSelectedCharts равным `true`
Зануление количества реплик устаревших версий приложения при канареечном развертывании	Количество реплик старых версий приложения будет приведено к 0	В пользовательском конфигурационном файле в репозитории конфигураций SMDL.Configs определить параметр needDownOldPods равным `true` (Значение по умолчанию равно `false`)
Задание `.Release.Name`	Возможность задания `.Release.Name` для Helm Charts	На экране запуска Jenkins Job задать параметр helmReleaseName

Параметры запуска Jenkins Job:

Параметр	Обязательность	Возможность изменить предопределенные значения	Описание
ClusterName	+	+	Кластер для установки
ClustersXml	-	-	Структура хранения информация о принадлежности проектов к кластерам
deleteResources	-	+	Ресурсы для удаления, разделенных ',' или ';'. Пример ввода:deployment.apps/bsp-egressgateway;service/bsp-egressgateway Для удаления всех сущностей одного типа, нуно задать тип сущности и флаг –all Пример ввода: service --all Для удаления всех сущностей необходимо задать в параметре: all --all=true Возможность задания маски для удаления в части названий конфигураций (используется флаг -e команды grep). Пример ввода: service/.adapt.
Division	+	-	Сегмент (Dev, Psi, Prom)
federalName	-	+	Имя федерации, для федеративной канареечной установки
gavParam	-	+	GAV параметры: Пример: 'nexus_PROD.CI90000017_synapse: SYNAPSE: zip: distrib: SP-01.025.00-02-SYDEVOPS-123\
needCanaryUpload	-	+	Включение режима канареечной установки. Используется для загрузки новой версии приложения при наличии старой.
needCheckTemplateParams	-	+	Флаг проверки templates из дистрибутивов на наличие переменных из templates в репозитории стендозависимых параметров
needCompareConfigs	-	+	Нужно ли производить сравнение устанавливаемых конфигураций с тем, что установлено в проекте
needConvert	-	+	Нужно ли актуализировать apiVersion в конфигурационных файлах. Конвертация выполняется с помощью команды convert.
needInputOrchestratorLogin	-	+	Флаг, отвечающий за авторизацию по логину/паролю (вводится во время работы pipeline динамически, маскируется)
needInputVault	-	+	Флаг, отвечающий за ввода пароля для шифрации/дешифрации secret(s)/конфигураций (вводится во время работы pipeline динамически, маскируется)
needLocalTemplateProcessing	-	+	Флаг, отвечающий за добавление ключа --local=true для обработки шаблонов конфигурационных файлов инструментом клиента системы оркестрации без подключения к серверу
needOrchestratorValidate	-	+	Добавление ключа --validate=true при загрузке конфигураций. Будет произведена валидация конфигураций по схемам системы оркестрации.
needPreCheck	-	+	Флаг запуска dry-run прогона перед установкой.
needServerPreCheck	-	+	Нужно ли проверить устанавливаемые конфигурации перед установкой
needServerSideForceConflicts	-	+	Нужно ли при apply конфигураций добавлять флаги --server-side=true и --force-conflicts. Только при использовании клиента kubectl
needSynaiCheck	-	+	Нужно ли вызывать компоненту SYTL для проверки успешности установки
needToUpdateVSandDR	-	+	Нужно ли обновить VS и/или DR в проекте, в котором они уже есть. Опция необходима в связи с ограничениями систем оркестрации приложений на перезаписывание VS и DR.
needUploadSecret	-	+	Выбор режима загрузка secret(s). Для расшифровки должен быть задан параметр AnsibleVaultCredentialsId, содержащий файл с паролем,либо использован параметр needInputVault. Дополнительно нужно заполнить параметр projectsConfigResourcesList: prepare-namespace/secrets/secret-1.yml,prepare-namespace/secrets/secret-2.yml
needInstallSelectedCharts	-	+	Флаг, отвечающий за включение возможности выбора Helm Charts, которые необходимо установить
nexusLink	-	+	Ссылка для скачивания дистрибутива Пример: https: //nexus.domain.ru/nexus/service/local/repositories/Nexus_PROD/content/Nexus_PROD/CI02001129_Synapse/SYNAPSE/SP-02.255.00-01-SYNAPSE-3586/SYNAPSE-SP-02.255.00-01-SYNAPSE-3586-distrib.tar.gz
orchestratorProject	-	+	Имя проекта Пример: synapse-ift
orchestratorProjectArray	-	+	Проекты по умолчанию. Если orchestratorProject пуст, выбираете из предложенных Пример: synapse-ift
projectApiURL	+	-	Ссылка на проект. Заполняется на основе ClusterName
projectsConfigGitBranchSources	-	+	Ветка репозитория стендозависимых параметров или репозитория с бэкапами Пример: feature/SYNAPSE-1503-TEST
projectsConfigGitUrlSources	-	+	Адрес репозитория стендозависимых параметров или репозитория с бэкапами.
projectsConfigResourcesList	-	+	Список ресурсов, разделенных ' , ' или ' ; ', из каталога проекта репозитория с конфигурационными файлами для установки. Формат заполнения параметра: path/file.yaml,path2/file2.yaml,path3/* Пример: adapter-erib/orchestrator/adapter-erib.yml,other/devops-test.yaml,test.yaml,folder-srv-client/*/, folder-srv-client/* Можно указывать маску, например, если написать */gateway, то будут поставлены все конфигурационные файлы с этой маской в пути или названии. Если необходимо установить все ресурсы из репозитория стендозависимых параметров, укажите маску: */.y*ml. Если поле оставить пустым, то будут установлены ТОЛЬКО конфигурации из дистрибутива.
ReposXml	-	-	Структура хранения информации об адресах репозиториев
skipChangeWeightCanary	-	+	Если параметр равен true, то будет только установлена новая версия сервиса, но при этом нагрзка на нее подаваться не будет. Нагрузка останется 100% на старой версии
skipGetInfoByCI	-	+	Флаг, отвечающий за пропуск сбора информации по КЭ
CIXml	-	-	Структура хранения информацию о связи КЭ с Nexus и Docker Registry.
helmReleaseName	-	+

Источники параметров:

projectConfig - конфигурация проекта. Параметры, которые считываются из репозитория конфигурации SMDL.

jenkinsParams - параметры, которые передаются в pipeline, путем заполнения их на экране запуска Jenkins Job, после нажатия кнопки "Собрать с параметрами". Их описание можете посмотреть выше.

libraryParams - параметры, которые заданы командой разработки SMDL.

Параметры Pipeline:

Параметр	Принцип валидации	Значение по умолчанию	Источник	Описание
nexusCredentialsId	requiredNotEmpty	—	projectConfig	Credential дя работы с Nexus
nexusUrl	requiredNotEmpty	—	libraryParams	Ссылка на Nexus
Division	requiredNotEmpty	—	projectConfig	Сегмент (Dev, Psi, Prom)
AnsibleVaultCredentialsId	requiredNotEmpty	—	projectConfig	ID CredentialsId для шифрации и дешифрации (тип: Secret file). Пример: dev_common_ansible_vault_secret
ciCred	requiredNotEmpty	—	projectConfig	Credential технической учетной записи DevOps команды
priorityUploadConfigs	requiredNotEmpty	—	libraryParams	Порядок загрузки конфигураций в проект
whiteListMetaInfo	requiredNotEmpty	['labels', 'name', 'annotations']	libraryParams	Список разрешенных полей в метаинформации
blackListMetaInfo	requiredNotEmpty	['clusterIP', 'externalIPs', 'nodePort', 'kubectl.kubernetes.io/last-applied-configuration']	libraryParams	Список запрещенных полей в метаинформации
removeIfNullMetaInfo	requiredNotEmpty	['tcp','tls']	libraryParams	Список полей в метаинформации, которые надо удалить, если их значение `null`
needReplaceNamespace	setPropsIfNotExist	—	libraryParams	Флаг для явного указания в командах ОС проекта
needPreCheck	setPropsIfNotExist	—	libraryParams	Флаг запуска холостого прогона перед установкойdafault: true
needStopAfterPreCheck	setPropsIfNotExist	false	libraryParams	Флаг, отвечающий за функционал подтверждения админимтратором корректности холостой установки конфигурационных файлов
needSecondApprove	setPropsIfNotExist	—	libraryParams	Флаг, отвечающий за подтверждения второй рукой продолжения работы установки после preCheck
customDevLogic	setPropsIfNotExist	—	libraryParams	Параметр для особенности dev сборок
checkDeploymentStatusTimeLimit	setPropsIfNotExist	—	libraryParams	Время, через которое будет произведена проверка готовности Deployment-а (в секундах)
needCheckStatusOfDeployments	setPropsIfNotExist	—	libraryParams	Флаг проверки работы deployment
needInputOrchestratorLogin	setPropsIfNotExist	—	libraryParams	Флаг, отвечающий за авторизацию по логину/паролю (вводится во время работы pipeline динамически, маскируется)
devMode	setPropsIfNotExist	—	libraryParams	Флаг для канарейки. при False автоматически ставится 100 на новой версии
needLeaveCommentInJira	setPropsIfNotExist	—	libraryParams	Флаг, регулирующий отбивку в Jira по результатам сборки
needMoveTicketInJira	setPropsIfNotExist	—	libraryParams	Флаг, регулирующий движение тикетов Jira
needCheckTemplateParams	setPropsIfNotExist	—	libraryParams	Флаг проверки template
orchestratorToken	setPropsIfNotExist	—	libraryParams	Авторизация по токену
orchestratorCred	setPropsIfNotExist	—	libraryParams	ID CredentialsId для доступа к системе оркестрации приложений
needToUpdateIstioConfigs	setPropsIfNotExist	—	libraryParams	Если вам необходимо обновить Istio конфигурации в проекте, в котором они уже есть. Опция необходима в связи с ограничениями на перезаписывание Istio конфигураций
needScaleNewPods	setPropsIfNotExist	false	libraryParams	Флаг отвечающий за увеличение количества подов для новой версии приложения. Если задано значение `true`, то количество подов будет увеличено до уровня старой версии приложения
PULL_REQUEST_FROM_BRANCH	optionalParam	—	jenkinsParams	Ветка с какой ветке идет ПР
PULL_REQUEST_TO_BRANCH	optionalParam	—	jenkinsParams	Ветка к какой ветке идет ПР
PULL_REQUEST_URL	optionalParam	—	jenkinsParams	Ссылка на ПР
PULL_REQUEST_ID	optionalParam	—	jenkinsParams	ID ПР
dockerRegistryURL	optionalParam	—	libraryParams	Ссылка на registry
dockerRegistryCI	optionalParam	—	jenkinsParams	Достается из xml
dockerRegistryRepo	optionalParam	—	libraryParams	Репозиторий registry
dockerRegistryProject	optionalParam	—	jenkinsParams	Берется из CIXml
dynamicOrchestratorTokenPrefix	optionalParam	—	libraryParams	Префикс динамического токена
nexusLink	optionalParam	—	jenkinsParams	URL для скачивания дистрибутива
gavParam	optionalParam	—	jenkinsParams	GAV параметр
needServerSideForceConflicts	optionalParam	—	jenkinsParams	Нужно ли при apply конфигураций добавлять флаги --server-side=true и --force-conflicts. Только при использовании клиента kubectl
federalName	optionalParam	—	jenkinsParams	Имя федерации для канареечной установки
needValidateYaml	optionalParam	—	libraryParams	Флаг включения валидации конфигураций
needLocalTemplateProcessing	setPropsIfNotExist	false	libraryParams	Флаг для подстановки стендозависимых параметров в шаблоны локально с помощью клиента оркестровщика
needPushConfigsToRepo	setPropsIfNotExist	—	libraryParams	параметр запуска шага загрузки успешно установленных template в Bitbucket
needCheckSecurity	setPropsIfNotExist	—	jenkinsParams	Нужна ли проверка конфигураций на безопасность
timeoutWaitSynaiScan	setPropsIfNotExist	—	libraryParams	Время ожидания проверки Synai (в минутах)
needAdditionalConfirmAfterInstall	setPropsIfNotExist	false	projectConfig	Флаг включения дополнительного подтверждения после установки конфигураций в проект
additionalConfirmation	optionalParam	—	projectConfig	Map c дополнительными сообщениями, которые нужно добавить к подтверждающему input
distrNameRegexForCanary	optionalParam	—	libraryParams	Регулярное выражение для получения имени дистрибутива из конфигураций канареечного развертывания
orchestratorResourceNameRegex	optionalParam	—	libraryParams	Регулярное выражение для определения является ли заданная строка именем конфигурации
needIgnoreSynaiError	setPropsIfNotExist	true	projectConfig	Флаг, отвечающий за обработку ошибок от SynAI. Если флаг имеет значение `false`, тогда ошибка при сканировании будет фатальной, с дальнейшим откатом патча. Иначе ошибка при сканировании не повлияет на дальнейшую работу Jenkins Job
needSecondApproveDeleteConfigs	setPropsIfNotExist	false	projectConfig	Флаг, отвечающий за подтверждения второй рукой удаления конфигураций
needInstallSelectedCharts	setPropsIfNotExist	false	libraryParams	Флаг, отвечающий за включение возможности выбора Helm Charts, которые необходимо установить
needDownOldPods	setPropsIfNotExist	false	libraryParams	Флаг, отвечающий за обнуление Pods устаревших версий приложения
helmReleaseName	setPropsIfNotExist	—	libraryParams	Имя Helm Release, которое будет подставляться в Helm Charts в .Release.Name

Минимально необходимые права для работы pipeline в системе оркестрации приложений:

rules:
  # oc login
  - verbs:
      - get
    apiGroups:
      - ''
      - project.openshift.io
    resources:
      - namespaces
      - projects

  # oc process файл-темплейт
  - verbs:
      - create
    apiGroups:
      - template.openshift.io
    resources:
      - processedtemplates

  # oc get тип_ресурсов (кроме secrets)
  - verbs:
      - get
      - list
    apiGroups:
      - apps
      - apps.openshift.io
      - networking.istio.io
      - ''
    resources:
      - deployments
      - deploymentconfigs
      - virtualservices
      - destinationrules
      - services
      - configmaps
      #- secrets

  # oc apply тип_ресурсов (кроме secrets)
  - verbs:
      - create
      - patch
    apiGroups:
      - apps
      - networking.istio.io
      - ''
    resources:
      - deployments
      - virtualservices
      - destinationrules
      - services
      - configmaps
      #- secrets

  # oc scale deploy
  - verbs:
      - get
      - update
      - patch
    apiGroups:
      - apps
    resources:
      - deployments/scale

  # oc delete тип_ресурсов(кроме secrets)
  - verbs:
      - delete
    apiGroups:
      - ''
      - apps.openshift.io
      - apps
      - networking.istio.io
      - autoscaling
      - route.openshift.io
    resources:
      - configmaps
      - services
      #- secrets
      - deploymentconfigs
      - deployments
      - replicasets
      - destinationrules
      - envoyfilters
      - gateways
      - serviceentries
      - sidecars
      - virtualservices
      - horizontalpodautoscalers
      - routes

Используемые шаги:

Все указанные ниже исполняемые скрипты в формате .groovy расположены в подразделе «Шаги» раздела «Дополнительная документация» документа «Руководство прикладного разработчика».

Название stage	Используемый шаг
Загрузка инструментов для выполнения pipeline	CommonStep
Валидация параметров	Validation
Подготовка к сборке	SynapseInstallerPrebuild
Скачивание репозиториев SCM	MultiGitCheckOut
Скачивание дистрибутива	DownloadDistrib SendDistribInfoToCUPOL
Применяем конфигурации	ApplyOrchestratorConfig
Всегда выполняются в конце	UploadRollbackConfigs CheckNeedLeaveJiraComment AddJiraComment MoveJiraTicket FinalStep