Перейти к основному контенту

Порядок подготовки проекта к системе сборки

Любой проект должен быть подготовлен для автоматической сборки с использованием конвеера CI/CD. Для этого в структуру проекта должны быть внесены соответствующие изменения. Код проекта должен поддерживать конфигурирование через переменные окружения, с использованием dotenv или аналогичной библиотеки.

Начальное пополнение проекта

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

  • contrib - набор вспомогательных файлов для сборки пакета - шаблоны сервисов, конфигурации веб серверов и т.п.
  • debian - набор рецептов для сборки Debian пакета
  • Makefile - основной сборочный сценарий проекта
  • build.sh - специальный файл обновляющий историю изменений и запускающий сборку. Может использоваться для локальной сборки пакетов
  • .env - Переменные окружения, используемые при сборке проекта в распространяемый debian пакет
  • .env.develop - Переменные окружения, используемые при настройке стенда, дополняют собой значения переменных, объявленных в файле .env
  • .env.example - Все доступные переменные окружения. Может включаться в документацию проекта.
  • .env.local - Локальные переменные при локальной сборке и запуске проекта

Набор файлов шаблонов доступен для скачивания с корпоративного GIT репозитория. В шаблонах файлов в качестве имени проекта используется слово dummy, его требуется заменить на корректное имя проекта согласно его пути в репозитории GitLab. Путь анализируется от корня репозитория и не учитывает лидирующие пути содержащие слова back и front в имени проекта. Все прямые слеши (символ /) заменяются на тире (символ -). Если в пути проекта присутствует суффикс, содержащий  слова front или back, то к имени проекта добавляется суффикс -frontend или -backend, соответственно.  Например, если репозиторий имеет путь cok/lms/front то полное имя проекта будет иметь вид cok-lms-frontend, а если репозиторий имеет путь cok/video-store, то полное имя проекта будет иметь вид cok-video-store. Имя проекта, его тип, ветка репозитория отражаются при сборке как соответствующие переменные окружения и могут использоваться в шаблонах конфигурации.

Переменные окружения

При сборке проекта определен ряд переменных окружения, которые автоматически подставляются в файлы конфигурации и файлы .env с параметрами окружения проекта. Основные переменные при сборке проекта:

  • PROJECT_NAME - Короткое имя проекта, без суффикса
  • PROJECT_FULL_NAME - Полное имя проекта с суффиксом типа проекта
  • PROJECT_TYPE - Тип проекта - пустое значение, значения frontend или backend
  • PROJECT_BRANCH - Собираемая ветка проекта. Для стендов - имя ветки указывается без префикса stand/
  • DB_HOST - Адрес сервера баз данных
  • DB_PORT - Порт сервера баз данных
  • DB_NAME - Наименование базы данных на сервере
  • DB_USER - Имя пользователя для сервера баз данных
  • DB_PASSWORD - Пароль пользователя для сервера баз данных
  • DB_SCHEME - Схема на сервере баз данных. Параметр задан только для баз данных совместимых с PostgreSQL!
  • BACKEND_SERVICE - Адрес бакенд сервера, значение берется из файла конфигурации .env после сборки проекта
  • PUBLISH_TYPE - Тип публикации проекта, возможные значения: none, public, private.
  • PUBLISH_DOMAIN - Домен публикации - пустое значение, dev.ao-nk.site или dev.ao-nk.ru в зависимости от типа публикации, задаваемого переменной PUBLISH_TYPE

Если требуется провести подстановку переменных в файл конфигурации времени сборки, используется синтаксис %VAR%, где VAR - имя переменной.

Если требуется задать пользовательскую переменную, которая будет использоваться в файлах contrib/ingress.yaml или contrib/watchdog.yaml, используется ключевое слово export перед именем переменной, например:

export MY_VAR="Text based value"

Секреты и служебная информация

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

Для обращения к секрету используется следующий синтаксис .env файла - %SECRET_<NAME>%, где <NAME> - имя секрета для собираемого проекта. Секреты в Jenkins имеют формат именования <PROJECT_NAME>_<NAME> в нижнем регистре. Таким образом, использование подстановки %SECRET_AUTH_ID% для проекта cok/lms/frontend будет искать значение секрета Jenkins с именем cok-lms_auth_id.

Рекомендуется выделять отдельный домен Jenkins для каждого сервиса/группы сервисов в Jenkins для точечного управления полномочиями на их просмотр и изменение. Тип секрета Jenkins указывается как Text Secret.

Служебные файлы для публикации в Kubernetes

Для публикации сервиса в Kubernetes, в особенности для создания стенда, используются следующие служебные файлы:

  • contrib/Dockerfile - Рецепт для упаковки образа контейнера (Dockerimage)Docker Image). Упакованный образ размещается в корпоративном Docker Registry по адресу registry.ao-nk.ru с именем <PROJECT_FULL_NAME>:<PROJECT_BRANCH>.
  • contrib/ingress.yaml - Опциональный файл, указывающий правила публикации сервиса. Возможна подстановка переменных во время стадии подготовки контейнера. Переменные подставляются с использованием синтаксиса Bourne Shell - ${VAR}.
  • contrib/watchdog.yaml - Опциональный файл, для проверки активности сервиса, согласно спецификации k18s.
  • contrib/dummy.sql - Опциональный файл дампа начального состояния базы данных. Используется если сервис не предоставляет миграции или требуется определенное начальное состояние базы данных при первичном запуске сервиса или очистке стенда. SQL сценарий должен соответствовать используемой РСУБД.

Пример содержимого файла contrib|wathcdog.yaml:

httpGet:
  path: /healthz
  port: 8080
  httpHeaders:
  - name: Custom-Header
    value: Awesome
initialDelaySeconds: 3
periodSeconds: 3

Порты и постоянные тома экземпляра сервиса в Kubernetes

Для автоматического определения портов сервиса и постоянных томов сервиса используются ключевые слова Dockerfile - EXPOSE и VOLUME.

EXPOSE определяет номер и тип порта (TCP или UDP) сервиса, например:

EXPOSE 80/tcp

Наверх