Reference

Структура

Описание структуры главного репозитория

genesis/
    cli         # Main cli app.
    webui       # The webui app.
    commands    # Commands for start app (compose/k8s)
    k8s         # k8s manfests
    nginx       # nginx container

Genesis cli команды

genesis cmd [options]

Команды запускаемые на сервере

start - Запуск экземпляра приложения на дроплете

stop - Остановка запущенных на дроплете контейнеров (кроме genesis, nginx)

restart - Принудительный перезапуск всех контейнеров

update - Обновление текущего экземпляра приложения

list - Список запущенных в контейнерах сервисов с указанием маршрутизации

create_routings - Формирование nginx конфигов для маршрутизации

services - Пулл сервисов из docker-compose.yml/k8s манифестов

Команды запускаемые в ci/cd

link - Удаленное создание/обновление/управление экземпляром приложения

build - Сборка и публикация контейнеров в реджестри

Переменные проекта

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

VERSION: *.*.*   # Genesis version, вместо *.*.* необходимо подставить последнюю доступную версию/tag,
                 # список тэгов - https://gl.sbdagroup.com/framework/genesis/-/tags
                 # ex: VERSION: 0.0.1

# These variables must be set in Gitlab -> Settings -> CI/CD -> Variables
GITLAB_TOKEN: $GITLAB_TOKEN # Gitlab Personal Access Token (with "api" scope and name "genesis"),
                            # see: https://gitlab.com/-/profile/personal_access_tokens
                            # required
HOSTING_PROVIDER: DO # Name of the hosting provider
                     # options: SSH, DO, YA, none (only for existing k8s cluster))
HOSTING_TOKEN: $HOSTING_TOKEN # For DigitalOcean: Personal Access Token (with "read" and "write" permissions)
                              # see: https://cloud.digitalocean.com/account/api/tokens
                              # required HOSTING_PROVIDER DO
                              #
                              # For YandexCloud: for start must be created service account with admin role
                              # and request oauth creds for it.
                              # see:
                              #  - https://cloud.yandex.ru/docs/iam/quickstart-sa#create-sa
                              #  - https://cloud.yandex.ru/docs/iam/operations/sa/create
                              #  - https://cloud.yandex.ru/docs/iam/operations/sa/assign-role-for-sa
                              # oauth json credentials for service account in format:
                              # {
                              #   "id": str,                 # oauth key id
                              #   "service_account_id": str, # service account id
                              #   "private_key": str,        # private key
                              # }
                              # required HOSTING_PROVIDER YA
                              # required YANDEX_CLOUD_FOLDER_ID str

SIZE: C1M1 # size droplet C1M1, C2M2, C2M4, C4M8, C8M16, C16M32
           # required HOSTING_PROVIDER
CONTAINER_MANAGER: docker # Name of the container provider
                          # Options: docker, k8s
                          # required

# Hosting specified variables
YANDEX_CLOUD_FOLDER_ID: str # id of the folder from yandex cloud

# route settings
# used for route settings
DNS_PROVIDER: CF  # Name of the dns provider
                  # Options: CF, YA
                  # required
DOMAIN: genesis-framework.com # Project domain for create dns.
                              # ex: genesis-framework.com.
                              # Template is "SERVICE.BRANCH.DOMAIN"
ROOT_SERVICE: frontend # service for use as root. ex for domain BRANCH.DOMAIN (for none ROOT_BRANCH) or DOMAIN (for ROOT_BRANCH)
                       # required DOMAIN
ROOT_BRANCH: master # branch for use as root in build domain.
                    # required DOMAIN and ROOT_SERVICE
#  used for auto settings dns (work only with route settings)
DNS_TOKEN: $CLOUDFLARE_TOKEN # DNS access token (for cloudflare (with permissions: ZONE -> DNS -> EDIT && ZONE -> ZONE -> READ))
                             # see: https://dash.cloudflare.com/profile/api-tokens"
                             # required DOMAIN
SSL: 1  # Using ssl.
        # Options: 0, 1
PATH_LIKE_DOMAIN: 0 # Optional
                    # Options: 0, 1
                    # If you use this options - env var $DNS_TOKEN don't work
                    # Only for use with k8s. Turn on path like generate domains (based on $DOMAIN).
                    # Template "SERVICE.BRANCH.DOMAIN" -> "DOMAIN/BRANCH/SERVICE"
                    # ex: "docs.dev.genesis-framework.com" -> "genesis-framework.com/dev/docs"

#  SELF_CONTAINERS_BUILD: 0 # Optional
#                           # Options: 0, 1
#                           # used for builds genesis containers. ex for WEBUI.
# IP_ADDRESS: 0.0.0.0 # Optional
                      # ip address for setting dns (if use client k8s cluster)
                      # or using for SSH provider

# used for smtp send creds
SMTP_LOGIN: $SMTP_LOGIN         # Smtp login (email from)
SMTP_PASSWORD: $SMTP_PASSWORD   # Smtp password
SMTP_HOST: $SMTP_HOST           # Smtp host
SMTP_PORT: $SMTP_PORT           # Smtp port
SMTP_TLS: 1  # using tls for smtp.
             # Options 0, 1

REGISTRY_PROVIDER: str    # Name of the docker registry provider
                          # options: GL, YA
                          # required REGISTRY_URL, REGISTRY_USER, REGISTRY_TOKEN.

REGISTRY_URL: str         # A fully-qualified URL for an externally-reachable address for the registry.
                          # default: gitlab registry url
REGISTRY_USER: str        # user for your docker registry
                          # default: gitlab registry user
REGISTRY_TOKEN: str       # credentials for docker registry
                          # default: gitlab registry password
                          # For Yandex: for start must be created service account with admin role
                          # and request oauth creds for it.
                          # see:
                          #  - https://cloud.yandex.ru/docs/iam/quickstart-sa#create-sa
                          #  - https://cloud.yandex.ru/docs/iam/operations/sa/create
                          #  - https://cloud.yandex.ru/docs/iam/operations/sa/assign-role-for-sa
                          # oauth json credentials for service account in format:
                          # {
                          #   "id": str,                 # oauth key id
                          #   "service_account_id": str, # service account id
                          #   "private_key": str,        # private key
                          # }

DOCKER_HUB_LOGIN: $DOCKER_HUB_LOGIN        # used to bypass rate limit docker hub pull (required)
DOCKER_HUB_PASSWORD: $DOCKER_HUB_PASSWORD  # used to bypass rate limit docker hub pull (required)

PROJECT_TAGS: '{"budget_line": "product", "org_structure": "software_development_kit", "project_owner": "username@example.com"}'      # required
YANDEX_USE_LOCAL_IP: 1          # used to using local or public ip 
                                                                # Options 0, 1
YANDEX_PRIVATE_NETWORKID: str   # id of the network from yandex cloud
CORP_EMAIL_DOMAIN: str          # your corp email domain. ex: "example.com"

Список служебных переменных:

# job services vars
DOCKER_DRIVER: overlay2
DOCKER_TLS_CERTDIR: ""

# services vars
PROJECT_NAME: $CI_PROJECT_NAME # Name of the project to be used for droplet and repository creation
                               # required
PROJECT_NAMESPACE: $CI_PROJECT_NAMESPACE # Project namespace to be used for find project in git provider
                                         # required
BRANCH: $CI_COMMIT_REF_SLUG # Branch to deploy
                            # required
COMMIT_SHORT_SHA: $CI_COMMIT_SHORT_SHA  # used in tests
COMMIT_SHA: $CI_COMMIT_SHA              # used in tests

При необходимости указания приватных токенов использующихся в сервисах/приложениях необходимо указивать постфикс _TOKEN для имени переменной. В таком случае ваши приватные данные не будут попадать в переменные окружения контейнера.

PROJECT_TAGS

Обязательная переменная в виде json:

{
 "budget_line": "product",
 "org_structure": "software_development_kit",
 "project_owner": "youremail@example.com",
 "branch_owner": "youremail@example.com"
}

"budget_line" Статья бюджета. Принимает значения product/infrastructure/presale/project.

"org_structure" Подразделение к которому относится ваш проект. Значение можно взять на портале rubbles.hrbox.io во вкладке Оргструктура.

"project_owner" Почта ответсвтенного за проект. Ответственным может выступать тимлид, владелец продукта итд.

"branch_owner" Ваша почта в домене rubbles.ru, как комитившего\создающего ресурс.

Base CI/CD Jobs overview

Код genesis'a начинает исполняться в CI/CD процессе выбранного git провайдера (Gitlab CI/CD).

Структура описана в подключаемом genesis.gitlab-ci.yml. Рассмотрим описание базовых джоб:

  1. .genesis. Это before_script т.е. запускается перед каждой джобой. Служит для подготовки и настройки окружения базовых джоб.
  2. genesis-protect-master. Необходим для служебных проверок.
  3. genesis-release. Здесь genesis собирает базовые образы и пушит их в указанный частный docker registry
  4. genesis-deploy. Здесь genesis непосредственно разворачивает заданную параметрами инфраструктуру.

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

Нужно понимать разные окружения запуска, по очереди деплоя:

  1. Окружение Gitlab CI/CD (.gitlab-ci.yml)
  2. Окружение хостовой машины (docker-compose.yml/k8s)
  3. Окружение контейнера (Dockerfile)

По дефолту genesis пробрасывает переменные окружения (gitlab ci variables) и генерируемые переменные в контейнеры.

Генерируемые переменные:

  • {SERVICE_NAME}_PUBLIC_URL - публичный урл сервиса (используется, например, для прописывания origin у backend сервиса), где SERVICE_NAME - имя сервиса в upper_case. В случае если указан домен, то из него и будет состоять урл, если домен не указан то будет сформирован сетевой сокет из ip адреса и port'a в случае докер композа и node_port'a в случае k8s.

В случае необходимости определенных переменных в окружении контейнера, их можно указать в build_args.txt (смотреть секцию сборка образов) или в Dockerfile с помощью ARG\ENV (docs). Для genesis-webui это: CI_SERVER_HOST, GITLAB_TOKEN, CI_COMMIT_REF_SLUG -> BRANCH, CI_PROJECT_NAME -> PROJECT_NAME.

Yandex_iam_token

Для работы с Yandex Cloud, genesis использует способ аутентификации через iam-token. Для работы вам необходимо получить креды и YANDEX_CLOUD_FOLDER_ID.

Получение YANDEX_CLOUD_FOLDER_ID описано в документации яндекса.

Получение кредов:

1) Создайте каталог и сервис аккаунт с ролью admin для этого каталога.

Смотреть:

  • https://cloud.yandex.ru/docs/iam/quickstart-sa#create-sa
  • https://cloud.yandex.ru/docs/iam/operations/sa/create
  • https://cloud.yandex.ru/docs/iam/operations/sa/assign-role-for-sa

2) Зайдите в карточку сервисного аккаунта, создайте oAuth токен и сохраните открытый и закрытый ключи.

create oauth token

3) После создания oauth токена необходимо сформировать json вида для переменной YANDEX_TOKEN:

{
    "id": str,                 # oauth key id (см на рис ниже)
    "service_account_id": str, # service account id (см на рис ниже)
    "private_key": str,        # закрытый ключ из предыдущего пункта
}

other credentials

Atop

atop - инструмент для мониторинга и логирования активностей (CPU, memory, swap, disks (including LVM), network layers) хоста. По дефолту устнавливается на сервер с переменными /etc/default/atop :

LOGINTERVAL=300
LOGGENERATIONS=14

Логи хранятся по пути /var/log/atop/atop_.