Кастомизация GitLab: опыт Совкомбанк Технологий в написании компонентов для типовых банковских проектов

Вступление

Хабр, привет! На связи Владимир, DevOps-инженер компании Совкомбанк Технологии. В этой статье расскажу о компонентах GitLab, способах их применения и том, как они помогли нам с настройкой CI/CD на проектах.

Как мы настраивали CI/CD раньше

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

Как обычно в корне проекта находился файл .gitlab-ci.yml, в котором мы описывали стадии, шаблоны с переменными для каждого стенда, шаблоны с самими скриптами для различных тестов, сборки образов, сканирования собранных образов на уязвимости, деплоем в K8S или на docker-хосты и удалением текущего деплоя. Отдельно в каталоге ci-cd-files мы храним Dockerfile и yml-файлы для пайплайнов, содержащих в себе описание заданий, в которые подключаются шаблоны из .gitlab-ci.yml. Также в корне проекта есть отдельный каталог helm, в котором по началу находился чарт с values.yaml для него, а, в последствии, когда мы написали собственный «универсальный» чарт, только values.yaml для каждого стенда. Но сейчас не про чарт и его конфиг.

Из проекта в проект конфигурации пайплайнов могли получать изменения. В основном изменения касались именно скриптов, а набор заданий был стандартным для большей части проектов. И каждый раз, при настройке нового проекта или изменении старого в части скриптов, по «вине» изменений в работе инфраструктурных сервисов, нам приходилось вносить изменения в каждый скрипт для каждого проекта отдельно. Например, в какой-то момент произошли изменения в нашем хранилище Docker-образов — скрипт по сканированию образов на уязвимости и выгрузке этих уязвимостей сломался и ничего не выводил. Путем долгих поисков вместе с «соседней» командой девопсов мы обнаружили причину в изменении запросов к АПИ. Теперь дополнительно требовалось передавать определенный заголовок. После изменения скрипта мы снова начали получать результаты сканирования, но появилась задача распространить изменения на все проекты. После того, как мы с этим успешно справились, зародилась мысль написать общие шаблоны, которые могли бы использоваться если не во всех, то хотя бы в большей части банковских проектов.

Сначала это были локальные шаблоны для самых крупных проектов или для отдельных команд, у которых процесс настройки CI/CD отличался парочкой переменных.

Результаты радовали, а одна из команд самостоятельно развила эту идею и практически реализовала GitOps прямо в GitLab. Впоследствии мы виделись с этой командой только по каким-нибудь проблемам в самом K8S или других инфраструктурных сервисах.

Но все равно оставалась другая бо́льшая часть проектов, в которых использовался старый формат CI/CD. Пусть и немного обновленный, приведенный к более понятному и красивому формату описания пайплайнов.

Прежде, чем я расскажу о способах решения этой проблемы, раскрою описание компонентов, чтобы вы лучше понимали, о чем пойдет речь дальше.

Описание компонентов

Компоненты в виде экспериментальной функции были добавлены в GitLab 16.0

В Совкомбанк Технологиях используется GitLab 17-й версии. Если вы решили «потрогать» компоненты собственными руками – рекомендую использовать версию не ниже 17. Начиная с этой версии компоненты стали общедоступными, а их функционал неплохо расширился, по-сравнению с версией 16.

Заглянем на страницу документации компонентов.

Компоненты CI/CD – это блок конфигурации пайплайна, который можно повторно использовать.

И тут может возникнуть вопрос:

– Чем это отличается от шаблонов, которые мы подключаем через include? Например, template, remote или project.

Во-первых, у нас появился новый блок в include – component. Дальше больше, вернемся к описанию компонентов:

Компоненты можно настроить с помощью входных параметров для более динамичного поведения.

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

Компоненты CI/CD похожи на другие виды конфигураций, подключаемых с помощью include, но имеют ряд преимуществ.

Посмотрим, что это за преимущества:

– Компоненты могут быть перечислены в каталоге CI/CD;

– Компоненты могут быть выпущены и использованы с определенной версией;

– В одном проекте можно определить несколько компонентов и создавать для них версии одновременно.

По второму и третьему пунктам все более-менее понятно, а вот обсудить, что такое каталог CI/CD будет не лишним.

Каталог CI/CD – это список проектов с опубликованными компонентами CI/CD, которые вы можете использовать для расширения своего рабочего процесса CI/CD

Все созданные проекты компонентов и сами компоненты можно посмотреть на странице <your-instance>/explore/catalog. Там будут перечислены все проекты, а внутри них все компоненты определенного проекта с описанием параметров и документацией к проекту.

Немного практики

Начнем с простого: создадим проект для наших компонентов, сделаем из него элемент каталога CI/CD, добавим туда базовый компонент и попробуем подключить его к нашему проекту.

Создаем наш новый проект, выдаем ему красивое имя и обязательно просим GitLab создать в проекте файл README.

После создания проекта нужно перейти в Settings -> General -> Naming, description, topics и заполнить описание проекта. Этого требует GitLab для каталогов CI/CD.

Дальше идем в Settings -> General -> Visibility, project features, permissions, находим пункт CI/CD Catalog project и активируем его

В проекте создаем каталог templates, в который и будем складывать наши компоненты. Я назову первый компонент example.yml. Его содержимое:

spec:   inputs:     message:       default: "Сообщение по умолчанию."       description: 'Сообщение для джобы.'     extra-message:       default: false       type: boolean       description: 'Включает вывод дополнительного сообщения.'     array-script:       default:         - echo "Скрипт №1"         - echo "Скрипт №2"       type: array       description: 'Массив скриптов для джобы.'     port:       default: 8080       options:         - 8080         - 9000         - 3000       type: number       description: 'Номер порта.'     version:       regex: ^v\d\.\d+(\.\d+)$       description: 'Номер версии.' --- TEST:   stage: test   image: $CI_REGISTRY/common-alpine:6.13   script:     - echo $[[ inputs.message ]]     - |       if $[[ inputs.extra-message ]]; then         echo "Дополнительное сообщение"       fi     - |       echo "Порт: $[[ inputs.port ]]"       echo "Версия: $[[ inputs.version ]]"   after_script: $[[ inputs.array-script ]]   tags:     - public 

Описание компонентов следует начинать с блока spec:inputs. В этом блоке необходимо описать параметры компонента, которые мы сможем определять/переопределять. Все возможные параметры должны быть определены в spec:inputs.

По умолчанию для параметра используется тип string. На выбор нам дается четыре типа:

– string – тип по умолчанию, принимает на вход строковое значение

– number – принимает на вход числовое значение

– array – принимает на вход допустимый синтаксисом YAML массив. Более сложные функции, такие как !reference, не могут быть использованы

– boolean – принимает на вход true/false

Обязательность параметра определяется наличием поля default – при его отсутствии поле является обязательным и должно быть определено при подключении компонента.

Также параметры могут иметь следующие поля:

– options – задает список из вариантов, которые можно передать в параметре. Значение, которое не совпадает со списком, приведет к ошибке в работе пайплайна. Применяется ко всем типам, кроме boolean.

– regex – задает регулярное выражение, которому должно следовать значение. Шаг влево/вправо – ошибка в работе пайплайна. Применяется только к типу string.

Как только закончили описание всех параметров – необходимо в новой строке написать ”—“. Это требуется для разделения блоков с параметрами и основным кодом. После этого можно приступить к описанию заданий/шаблонов.

Чтобы использовать описанные параметры, их нужно записать в таком виде:

$[[ inputs.<parameter-name> ]]

Но, перед тем как подключать наш новый компонент, нужно подготовить релиз. Для этого в корне проекта создаем файл .gitlab-ci.yml со следующим содержимым:

include:   - component: [ДАННЫЕ УДАЛЕНЫ]/components/templates/default@1.18.3  stages: [release]  create-release:   stage: release   script: echo "Creating release $CI_COMMIT_TAG"   rules:     - if: $CI_COMMIT_TAG       when: always   release:     tag_name: $CI_COMMIT_TAG     description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH"

Здесь я подключаю собственный компонент, в котором описал образ по умолчанию для запуска заданий и тег раннера. Но это не важно. Важно то, что ниже. А ниже у нас стандартное задание по выпуску релиза, которое запустится только при создании тега из ветки.

Сохраняем изменения и идем выпускать тег:

Для создания релизов следует использовать семантическое версионирование https://semver.org/. Например, 1.0.0, 2.3.4 или 1.2.2-alpha. При этом, если при подключении компонента указать @~latest, будет использована последняя версия, соответствующая маске X.Y.Z. Делать так, конечно же, не рекомендуется.

Создаем тег и ждем выполнения задания по выпуску релиза.

Теперь займемся подключением компонента в проект.

Создаем новый проект, если его еще нет и добавляем туда файл .gitlab-ci.yml со следующим содержимым:

include:   - component: [ДАННЫЕ УДАЛЕНЫ]/habr-example-component/example@0.0.1     inputs:       version: v1.2.3  stages: [test]

Для подключения компонента используем include:component. Адрес подключения указываем следующим образом: <your-gitlab-instance>/<path/to/project>/<component-name>@<version>, где:

<your-gitlab-instance> — адрес GitLab

<path/to/project> — путь до проекта с компонентами

<component-name> — название компонента без указания расширения файла

<version> — версия релиза

Так как в компоненте параметр version определен без поля default, он является обязательным, указываем его через inputs:<parameter-name>. Не забываем, что на этот параметр мы «навесили» regex, а значит нужно указать версию, которая подойдет нашему регулярному выражению.

Сохраняем изменения и идем смотреть на логи нашего задания:

Как видим, все прекрасно работает. Версия соответствует значению параметра.

Но есть и другие параметры, попробуем поменять все:

include:   - component: [ДАННЫЕ УДАЛЕНЫ]/habr-example-component/example@0.0.1     inputs:       version: v1.2.3       message: "Хабр, вам тут сообщение!"       extra-message: true       array-script:        - echo "Теперь этот параметр содержит только один скрипт."       port: 9000

Отлично, поменяли значение параметра message, переключили extra-message на true, переопределили массив array-script и указали новый порт для параметра port из списка options.

Смотрим результат:

Все работает!

Давайте сломаем наш пайплайн. Для этого изменим version, чтобы значение не соответствовало regex или укажем новый порт, который отсутствует в options. Я поменяю порт:

include:   - component: [ДАННЫЕ УДАЛЕНЫ]/habr-example-component/example@0.0.1     inputs:       version: v1.2.3       port: 80

Смотрим: Unable to create pipeline

• [ДАННЫЕ УДАЛЕНЫ]/habr-example-component/example@0.0.1: port input: 80 cannot be used because it is not in the list of the allowed options

Ну что же… Это было ожидаемо.

Наш краткий экскурс по самим компонентам подошел к концу. Все остальное вы сможете найти в документации GitLab.

Как мы внедрили компоненты в проекты Совкомбанк Технологий и что изменилось после этого

Я начал активно изучать тему в начале 2024 года, тогда компоненты казались мне чем-то магическим. Путем скрупулезного чтения документации и выпуска сотни релизов, пришел к оптимальному решению. После чего предоставил команде первую стабильную версию своих компонентов.

Итого получилось 3 проекта:

– stands – проект с компонентами, описывающими каждый стенд. Dev, test, stage, prod и дополнительный компонент custom для настраиваемого окружения, например, preprod;

– jobs – проект с компонентами описывающим необходимые задания для каждого стенда. Напомню, что по умолчанию их 4: сборка образа, сканирование образа на уязвимости, деплой и удаление релиза;

– templates – «основной» проект компонентов, описывающий шаблоны и скрипты.

Структура следующая:

STANDS

├─test - шаблон с переменными для test среды ├─dev - шаблон с переменными для develop среды ├─stage - шаблон с переменными для stage среды ├─prod - шаблон с переменными для prod среды └─custom - шаблон с переменными для настраиваемой среды

JOBS

├─test - стандартные задания для test среды ├─dev - стандартные задания для develop среды ├─stage - стандартные задания для stage среды ├─prod - стандартные задания для prod среды └─custom - стандартные задания для настраиваемой среды

TEMPLATES

├─default - блок default с образом и тегом для раннеров по умолчанию, а также скрипты для уведомлений в мессенджер и некоторые функции ├─dast – элемент сканирования DAST ├─build - скрипт для сборки образа. Также включает в себя функции по скачиванию секретов из хранилища секретов, необходимых на стадии сборки ├─docker-compose - скрипты для деплоя и удаления релизов через docker-compose. Также включает в себя функции по скачиванию секретов из хранилища секретов, необходимых на стадии деплоя ├─docker - скрипты для деплоя и удаления релизов через docker. Также включает в себя функции по скачиванию секретов из хранилища секретов, необходимых на стадии деплоя ├─k8s - скрипты для деплоя и удаления релизов через helm. Также включает в себя функции по скачиванию секретов из хранилища секретов, необходимых на стадии деплоя ├─sast – элемент сканирования SAST ├─sca – элемент сканирования SCA └─scan - скрипт сканирования образов на наличие уязвимостей

Структура может показаться не очень удобной, но так было нужно, поскольку на момент составления шаблонов, в проекте могло быть не больше 10 компонентов. Из-за этого пришлось выкручиваться с несколькими проектами. В будущем проведем рефакторинг и сформируем единый проект.

Покажу примеры текущей реализации из каждого проекта.

stands/test:

spec:   inputs:     environment:       default: test       description: 'Название окружения GitLab.'     stand:       default: test       description: 'Название стенда.'     context:       default: NOT_REQUIRED       description: 'Имя кластера.'     vr-lvl:       default: Pofig       options:         - Pofig         - Negligible         - Low         - Medium         - High         - Critical       description: 'Минимальный недопустимый уровень уязвимостей.'     vr-exit-code:       default: 0       type: number       options:         - 0         - 1       description: 'Exit Code для джобы сканирования при нахождении уязвимостей.'     node-env:       default: ''       description: 'Переменная окружения для Node.' --- .test_template:   environment: $[[ inputs.environment ]]   variables:     ENVRM: $[[ inputs.stand ]]     VR_LVL: $[[ inputs.vr-lvl ]]     VULN_EXIT_CODE: $[[ inputs.vr-exit-code ]]     K8S_TOKEN: $K8S_TOKEN_$[[ inputs.context ]]     K8S_URL: $K8S_URL_$[[ inputs.context ]]     K8S_CLUSTER: $K8S_CLUSTER_$[[ inputs.context ]]     NODE_ENV: $[[ inputs.node-env ]]

jobs/test:

spec:   inputs:     build-extends:       type: array       default:         - .test_template         - .build_template       description: 'Набор подключаемых шаблонов для джобы сборки образа.'     build-rules:       type: array       default:         - if: $CI_COMMIT_BRANCH == "test"           when: always         - if: "$CI_COMMIT_BRANCH =~ /^devops.*$/"           when: always         - when: never       description: 'Набор правил для триггера джобы сборки образа.'     build-needs:       type: array       default:         - job: EMPTY_NEEDS           optional: true       description: 'Набор needs для джобы сборки образа.'     build-interruptible:       type: boolean       default: false       description: 'Помечает задание как прерываемое.'     scan-extends:       type: array       default:         - .test_template         - .scan_template       description: 'Набор подключаемых шаблонов для джобы сканирования образа.'     scan-rules:       type: array       default:         - if: $CI_COMMIT_BRANCH == "test"           when: on_success         - if: "$CI_COMMIT_BRANCH =~ /^devops.*$/"           when: on_success         - when: never       description: 'Набор правил для триггера джобы сканирования.'     scan-needs:       type: array       default:         - job: Build App Test           optional: true       description: 'Набор needs для джобы сканирования образа.'     scan-interruptible:       type: boolean       default: false       description: 'Помечает задание как прерываемое.'     deploy-extends:       type: array       default:         - .test_template         - .deploy       description: 'Набор подключаемых шаблонов для джобы деплоя.'     deploy-rules:       type: array       default:         - if: $CI_COMMIT_BRANCH == "test"           when: manual         - if: "$CI_COMMIT_BRANCH =~ /^devops.*$/"           when: manual         - when: never       description: 'Набор правил для триггера джобы деплоя.'     deploy-needs:       type: array       default:         - job: Scan App Test           optional: true       description: 'Набор needs для джобы деплоя.'     deploy-interruptible:       type: boolean       default: false       description: 'Помечает задание как прерываемое.'     cleanup-extends:       type: array       default:         - .test_template         - .delete_command       description: 'Набор подключаемых шаблонов для джобы очистки деплоя.'     cleanup-rules:       type: array       default:         - if: $CI_COMMIT_BRANCH == "test"           when: manual         - if: "$CI_COMMIT_BRANCH =~ /^devops.*$/"           when: manual         - when: never       description: 'Набор правил для триггера джобы очистки деплоя.'     cleanup-needs:       type: array       default:         - job: EMPTY_NEEDS           optional: true       description: 'Набор needs для джобы очистки деплоя.'     cleanup-interruptible:       type: boolean       default: false       description: 'Помечает задание как прерываемое.' --- Build App Test:   extends: $[[ inputs.build-extends ]]   rules: $[[ inputs.build-rules ]]   needs: $[[ inputs.build-needs ]]   interruptible: $[[ inputs.build-interruptible ]]  Scan App Test:   extends: $[[ inputs.scan-extends ]]   rules: $[[ inputs.scan-rules ]]   needs: $[[ inputs.scan-needs ]]   interruptible: $[[ inputs.scan-interruptible ]]  Deploy App Test:   extends: $[[ inputs.deploy-extends ]]   rules: $[[ inputs.deploy-rules ]]   needs: $[[ inputs.deploy-needs ]]   interruptible: $[[ inputs.deploy-interruptible ]]  Cleanup App Test:   extends: $[[ inputs.cleanup-extends ]]   rules: $[[ inputs.cleanup-rules ]]   needs: $[[ inputs.cleanup-needs ]]   interruptible: $[[ inputs.cleanup-interruptible ]]

templates/scan:

spec:   inputs:     stage:       default: scan       description: 'Название стадии.'     notify:       default: false       type: boolean       description: 'Включает уведомления о статусе задания сканирования образа.' --- .scan_template:   stage: $[[ inputs.stage ]]   variables:     GREP_ID: '"id":*"[^"]*"'     GREP_PACKAGE: '"package":*"[^"]*"'     GREP_VERSION: '"version":*"[^"]*"'     GREP_FIX_VERSION: '"fix_version":*"[^"]*"'     GREP_SEVERITY: '"severity":*"\(Low\|Medium\|High\|Critical\)"'   before_script:     - !reference [.border]     - !reference [.log]   script:     - |       DEBUG=${DEBUG:-false}       if $DEBUG; then         set -x       fi       if [ -z ${SCAN_PROJECT_NAME+x} ]; then         log "INFO" "Переменная SCAN_PROJECT_NAME не установлена. Вместо нее будет использована переменная PROJECT_NAME = ${PROJECT_NAME}."       else         log "INFO" "Переменная SCAN_PROJECT_NAME установлена. SCAN_PROJECT_NAME = ${SCAN_PROJECT_NAME}."         SCAN_PROJECT_NAME=$(echo ${SCAN_PROJECT_NAME} | sed 's,/,%252F,g');       fi        URL=”Путь к API-методу для сканирования образа.”            log "INFO" "Адрес сканирования - ${URL}."     - curl -s -X POST -u "$CI_REGISTRY_USER":"$CI_REGISTRY_PASSWORD" "$URL"     - count=16     - |       while [[ "$(curl -s -u "$CI_REGISTRY_USER":"$CI_REGISTRY_PASSWORD" -H "$HEADER" $URL)" != *"severity"* ]] && [[ 0 -lt $count ]]; do          (( count-- ));         log "INFO" "Ожидание завершения сканирования.... Осталось $count попыток"         if [ $count = 0 ]; then           log "ERROR" "Не удалось получить статус сканирования. Попробуйте позже."           exit 1;          fi;          sleep 20;        done     - |       curl -s -u "$CI_REGISTRY_USER":"$CI_REGISTRY_PASSWORD" -H "$HEADER" "$URL" > all_vuln.txt       cat all_vuln.txt | grep --color=always -o ${GREP_ID},${GREP_PACKAGE},${GREP_VERSION},${GREP_FIX_VERSION},${GREP_SEVERITY} || log "DONE" "Уязвимостей не найдено."       cat all_vuln.txt | grep -o ${GREP_ID},${GREP_PACKAGE},${GREP_VERSION},${GREP_FIX_VERSION},${GREP_SEVERITY} > vulnerability.txt || z=1;     - |       cat all_vuln.txt | grep -o '"severity":"'${VR_LVL}'"' > /dev/null || s=1;       if [[ "$s" -eq "1" ]]; then         log "DONE" "Не найдено уязвимостей уровня ${VR_LVL}."       else         log "ERROR" "Обнаружены уязвимости уровня ${VR_LVL}."         exit 1;       fi     - NOTIFY_BY_COMPONENT=$[[ inputs.notify ]]     - !reference [.notify, success]   allow_failure: true   after_script:     - NOTIFY_BY_COMPONENT=$[[ inputs.notify ]]     - if [ $CI_JOB_STATUS == 'success' ]; then exit 0; fi     - !reference [.notify, error]

Выглядит не так хорошо, как хотелось бы, но моя команда постоянно вносит изменения в компоненты и постепенно их улучшает.

 На текущий момент статистика следующая:

Внедрили компоненты в ~700 проектах и планируем масштабироваться

Значения постоянно скачут из-за количества самих проектов. Планируем увеличивать число и расти еще. Такое различие в числах между тремя проектами на скриншоте вызвано тем, что проект templates так же содержит в себе компоненты DAST, SAST, SCA, которые могут подключаться ко всем банковским проектам, независимо от того используются остальные компоненты или нет.

Большую часть новых проектов Совкомбанк Технологий переводим на компоненты и актуализируем действующие проекты на их основе. Если сравнивать скорость настройки пайплайна на основе компонентов со старым, заметны улучшения. При знакомстве с новым шаблоном, командам нужно время, чтобы разобраться в механиках, зато потом скорость написания пайплайнов только растет. Улучшился и процесс обновления скриптов. Теперь достаточно просто выпустить новый релиз и сообщить командам о том, в каких компонентах необходимо поменять версию. Latest мы используем только в компонентах sast, sca и dast, так как они не влияют на процесс CI/CD и их поломка не тормозит выкатку релиза.

Очень полезной оказалась и возможность переопределять шаблоны, скрипты и задания. Это позволяет гибко перенастроить определенный элемент пайплайна в случае чего.

Плюсы и минусы данного решения

Плюсы

– Основные настройки пайплайнов теперь хранятся в одном месте, что позволяет один раз внести необходимые изменения, а разработчикам только поменять версию определенного компонента в сбственных проектах.

– Настройка пайплайна в собственных компонентах гибкая: любое задание можно встроить в любое место пайплайна и настроить так, что все будет работать корректно и без поломок.

– Весь цикл от CI до CD можно реализовать только с помощью компонентов.

Минусы

В течение всего процесса написания мне, конечно же, пришлось столкнуться со многими проблемами.

– Из самых серьезных хочу выделить отсутствие возможности использовать проверки IF/ELSE, как это реализовано в helm-templates. Понятное дело, что helm и GitLab совершенно разные инструменты, но функционала, аналогичного helm’у в плане рендера готовой конфигурации очень не хватало. Но и к этому можно адаптироваться.

– Еще одним минусом считаю ограничения по числу компонентов на проект. Сейчас лимит подняли до 30, но хотелось бы, чтобы его вообще не было.

– Наконец, не самая удобная настройка: начиная от инициализации самого проекта компонентов, где без документации первое время ничего не будет понятно, до процесса внедрения компонентов в проекты, особенно для новичков.

Вот таким нехитрым образом мы решили проблему комплексного обновления процессов CI/CD в банковских проектах. Есть идеи, как можно развить финтех? Добро пожаловать к нам в команду.

Буду рад ответить на ваши вопросы в комментариях!