Описание по интеграции c SecMan#

Secret Management (SecMan) — система хранения и управления secret(s). В качестве secret(s) используются credentials, мигрированые из Jenkins в хранилище SecMan и данные secret(s) файлов из репозитория стендозависимых параметров.

Экземпляры(instances) SecMan#

Экземпляры Vault Secret Management различаются в зависимости от сегмента сети и назначения стендов. Для хранения secret(s) промышленных стендов используется экземпляр в соответствующем сегменте, для остальных стендов — экземпляр с тестовой среды в соответствующем сегменте.

Ссылка(образец)

Для каких сред применяется instance

p.secrets.domain.ru

Промышленные стенды

t.secrets.domain.ru
ift.secrets.domain.ru

Тестовые (до ПСИ включительно) стенды

Структура хранения secret(s)#

На рисунке ниже представлена иерархия хранения secret(s), по которой формируется путь для secret(s) АС: КЭ АС_КЭ СТЕНДА/A/ИМЯ БЛОКА/ГРУППА SECRET(S)/ДОПОЛНИТЕЛЬНОЕ ПРОСТРАНСТВО/ДВИЖОК SECRET(S)/КАТАЛОГ/SECRET(S) Например: CI01994970_CI02129749/A/SNPS/JEN/IFT/KV/domen_auth_users/ciCredDelta, где

  • CI01994970_CI02129749 в схеме формирования пути — КЭ АС_КЭ СТЕНДА (уровень «Тенант» или уровень стенда). Является родительским для всех остальных уровней.

  • A в схеме формирования пути — /A (Уровень «Секреты АС»). На 2 уровне иерархии выполняется разделение на хранение secret(s) инфраструктуры (I) и АС (A) для распределения доступов между группами сопровождения инфраструктуры и АС.

  • SNPS в схеме формирования пути — /ИМЯ БЛОКА (уровень «Блок»). Блок — это георезервированная end-to-end выделенная группа КТС, т.е. shards, обслуживающие заданную группу клиентов.

  • JEN в схеме формирования пути — /ГРУППА SECRET(S) (уровень «Общие secret(s)/Jenkins/Orchestrator/Прикладные secret(s)»). В имени пространства указывается соответствующая группа secret(s) (Global/Jenkins/Orchestrator/App). На этом уровне выполняется разделение на группы secret(s). Существующие группы secret(s):

    • Общие secret(s) (global) — сокращенное значение GLOB

    • Jenkins (jenkins) — сокращенное значение JEN

    • Orchestrator (orchestrator) — сокращенное значение OSH

    • Прикладные secret(s) (app) — сокращенное значение APP

    • Secret(s) MEF — сокращенное значение MEF

  • IFT в схеме формирования пути — /ДОПОЛНИТЕЛЬНОЕ ПРОСТРАНСТВО (уровень дополнительных пространств). На данном уровне при необходимости можно разделить хранение secret(s) по дополнительным пространствам.

  • KV в схеме формирования пути — /ДВИЖОК SECRET(S)

  • domen_auth_users в схеме формирования пути — /КАТАЛОГ. Актуален, если secret(s) разделены по типам (аналог Domain в Credentials(Jenkins), возможно дублирование наименований secret(s)

  • ciCredDelta в схеме формирования пути — /SECRET(S)

structure_vault_secrets

Рисунок. Структура хранилища secret(s)

Типы secret(s) в SecMan — типы credentials в Jenkins#

SecMan

Jenkins

LOGIN_PASSWORD_KV

usernamePassword

SSH_LOGIN_KEY

sshUserPrivateKey

SECRET_TEXT

string

SECRET_FILE

file

Интеграция с SecMan#

Для интеграции с SecMan необходимо наличие в Jenkins credential типа «Vault App Role Credential» для approle хранилища (создается администраторами хранилища SecMan).

В конфигурационном файле для стенда (configDev.yml, configPsi.yml, configProm.yml и т.п.) в репозитории конфигураций SMDL.Configs нужно заполнить блок параметров для доступа к хранилищу SecMan.

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

Пример блока параметров:

#Настройки для Secret Managment
needVault: true
configurationVault:
  vaultUrl: 'https://ift.secrets.domain.ru'
  vaultCredentialId: 'Synapse-approle-IFT-all'
  engineVersion: '1'
  vaultNamespace: 'CI01994970_CI02129749'
  pathVaultJEN: 'A/SNPS/JEN/IFT/KV'
  pathVaultOSH: 'A/{{segmentName}}/OSH/{{clusterName}}/KV'

  • needVault — флаг, отвечающий за активность SecMan

  • vaultUrl — ссылка на экземпляр SecMan

  • vaultCredentialId — credential в Jenkins для approle

  • engineVersion — версия системы хранения secret(s)(по умолчанию '1')

  • vaultNamespace — тенант (КЭ АС_КЭ СТЕНДА) обязательно для заполнения

  • pathVaultJEN — относительный путь хранения secret(s) (credentials, мигрированные из Jenkins)

  • pathVaultOSH — относительный путь-шаблон хранения secret(s) (данные файлов secret(s) из репозитория стендозависимых параметров) параметр-константа {{segmentName}}, {{clusterName}} заполняются в runtime значениями из параметра CIXml

Настройки конфигурации для промышленных стендов#

Используемые secret(s) располагаются в хранилище SecMan в разных областях хранения (ветка "AS", ветка "INFRA" ), в зависимости от типа secret(s).

Для доступа к области хранения ветки "AS" необходимо наличие в конфигурационном файле блока параметров configurationVault (пример выше).

Для доступа к области хранения ветки "INFRA" необходимо наличие в конфигурационном файле блока параметров configurationVaultInfra.

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

Пример блока параметров:

needInfra: true
configurationVaultInfra:
  vaultUrl: 'https://p.secrets.domain.ru'
  vaultCredentialId: 'approle'
  engineVersion: '1'
  vaultNamespace: 'CI01994970_CI02025191'
  pathVaultJEN: 'I/CI03555516/KV'
  pathVaultOSH: 'I/{{segmentName}}/OSH/{{clusterName}}/KV'

  • needInfra — флаг, отвечающий за активность ветки "INFRA"

  • vaultUrl — ссылка на экземпляр SecMan

  • vaultCredentialId — credential в Jenkins для approle

  • engineVersion — версия системы хранения secret(s)(по умолчанию '1')

  • vaultNamespace — тенант (КЭ АС_КЭ СТЕНДА) обязательно для заполнения

  • pathVaultJEN — относительный путь хранения secret(s)

  • pathVaultOSH — относительный путь-шаблон хранения secret(s) (данные файлов secret(s) из репозитория стендозависимых параметров) параметр-константа {{segmentName}}, {{clusterName}} заполняются в runtime значениями из параметра CIXml

Secret(s) для промышленных стендов#

Наименование secret(s) с токеном для промышленных стендов фиксировано и определяется как - jenkins-token. Наименование ключа в конфигурации(структуре) secret(s) при создании инструментом создания secret(s) варьируемое, по умолчанию определяется как - token. Для корректной обработки secret(s) и для обратной совместимости рекомендовано указывать в качестве наименования ключа - secretString. Требование к наименованию ключа не обязательно. Допустимо указывать ключ с любым наименованием.
Структура хранения secret(s) в области хранения KV может состоять как из одного, так и из нескольких подкаталогов.

Настройки конфигурации для промышленных стендов (репозиторий хранения артефактов - NEXUS)#

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

Пример блока параметров:

needNexus: true
configurationVaultNexus:
  vaultUrl: 'https://t.secrets.ru'
  vaultCredentialId: 'nexus_user_cred_secret'
  engineVersion: '1'
  vaultNamespace: 'CI00751652_CI01098402'
  pathVaultJEN: 'A/ALPHA/JEN/NEXUS/KV'
  pathVaultOSH: ''

  • needNexus — флаг, отвечающий за активность работы с репозиторием хранения артефактов в среде промышленных стендов

  • vaultUrl — ссылка на экземпляр SecMan

  • vaultCredentialId — credential в Jenkins для approle

  • engineVersion — версия системы хранения secret(s)(по умолчанию '1')

  • vaultNamespace — тенант (КЭ АС_КЭ СТЕНДА) обязательно для заполнения

  • pathVaultJEN — относительный путь хранения secret(s)

  • pathVaultOSH — не используется

Настройка расположения secret(s) в хранилище SecMan#

Secret(s) в области хранения KV могут располагаться как в корне, так и в подкаталогах. Изменить расположение secret(s) по умолчанию возможно указав в параметре subpath необходимую структуру подкаталогов, пустое значение предполагает расположение в корне. Со структурой параметров соответствия типов credentials/secret(s) можно ознакомиться в credentialTypes.json в подразделе «Дополнительные файлы (additionalFiles)» раздела «Дополнительная документация» документа «Руководство прикладного разработчика».

Для частных случаев, когда secret(s) одного типа располагаются в разных подкаталогах в области хранения KV, допустимо использовать персонализированные типы credentials. На текущий момент реализовано применение персонализированного типа "customString" в credentialTypes.json.

Пример реализации в скрипте:

dev.withCustomCreds([[credentialsId: config.sonarQubeToken, variable: 'SONAR_AUTH_TOKEN', credentialsType: 'customString']])

Настройки для обработки secret(s) с персонализированными ключами#

В конфигурации(структуре) большинства secret(s) для каждого типа используются наименования ключей по умолчанию. В случае, если наименование ключа в конфигурации secret(s) отлично от наименования по умолчанию, предусмотрены параметры для переопределения наименования ключа(см. таблицу).

Тип secret(s)

Наименования ключа по умолчанию

Параметр для переопределения

SECRET_TEXT

secretString

field

SECRET_FILE

secretFileName

field

LOGIN_PASSWORD_KV

secretUsername
secretPassword

namefield
passwordfield

SSH_LOGIN_KEY

secretUsername
secretKey
secretPassphrase

sshnamefield
sshkeyfield
sshpasswordfield

Для обработки secret(s) с персонализированными ключами необходимо заполнить параметр fields в файле соответствия типов credentials/secret(s) в credentialTypes.json.

Пример:

"vault": {
"type": "LOGIN_PASSWORD_KV",
"subpath": "domen_auth_users",
"fields": {
"namefield": "nexus_user_cred_name",
"passwordfield": "nexus_user_cred_password"
}
}

Особенности взаимодействия с новыми версиями доработанного плагина Jenkins Credentials(v.3.8.8-3.8.XX)#

Начиная с версии 3.8.10 доработанного плагина Jenkins Credentials(v.3.8.10) в структуру secret(s) типа SECRET_FILE добавились параметры fileNameField, fileContentField и decodeBase64 и значение ключа по умолчанию в Vault было изменено с secretFileName на fileContent. Обратная совместимость по наимованию ключа в новых версиях плагина есть. В частности, поддерживаются ключи по умолчанию secretFileName для secret(s) типа SECRET_FILE. Параметр decodeBase64 для secret(s) типа SECRET_FILE отвечает за декодирование идентификационных данных и по-умолчанию активен. Для исключения двойного декодирования данных со стороны доработанного плагина **Jenkins Credentials(v.3.8.8-3.8.XX) и со стороны механизма интеграции с Secret Managment необходимо деактивировать этот параметр в файле соответствия типов credentials/secret(s) в credentialTypes.json, заполнив параметр vault.fields в секции file.
Пример:

  "file": {
"groupId": 3,
"type": "file",
"authentication": {
"variable": "fileCredential"
},
"vault": {
"type": "SECRET_FILE",
"subpath": "global",
"fields": {
"decodeBase64": false
}
}
},

Особенности сетевого взаимодействия экземпляра(instance) Secret Managment с Jenkins и хостом пользовательского интерфейса#

По стандарту сетевое взаимодействие экземпляра(instance) Secret Managment настроено на один IP-адрес хоста (взаимодействие с Jenkins и WEB UI) Если в конфигурации сетевого взаимодействия с Jenkins и хостом WEB UI отличается IP-адресация, необходимо в конфигурационном файле для стенда (configDev.yml, configPsi.yml, configProm.yml и т.п.) в репозитории конфигураций SMDL.Configs определить и заполнить параметр general.vaultUrlUI, указав IP-адрес WEB UI хоста.
Пример:

vaultUrlUI: 'http://domain.ru:8200'

Подключение библиотек в представлении Jenkins пространства#

Для подключения библиотек в представлении Jenkins пространства необходимо наличие в Jenkins credentials типа «Vault SSH Username with private key Credential» (создается администраторами хранилища SecMan).

Рекомендации#

Для стабильной работы доработанного плагина Jenkins Credentials(v.3.8.8-3.8.XX), необходимо заполнить поля в секции «Vault Plugin» в представлении Jenkins. Поля заполнить значениями параметров из секции configurationVault конфигурационного файла.

Важно!!! поле Vault Namespace обязательно для заполнения.

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

Для проверки работоспособности необходимо настроить интеграцию с SecMan, запустить Jenkins Jobs и проверить, что они завершаются со статусом "SUCCESS".