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

Развёртывание сервера Salt.Box

Подготовка​

  1. Клонируйте проект salt-box-compose в Ваш рабочий каталог:

    git clone https://dev.saltbox.pro/salt.box/salt-box-compose.git

  2. Смените текущий рабочий каталог:

    cd ./salt-box-compose/

  3. В подкаталоге проекта ./secrets/ должны быть созданы файлы с секретами.
    Создать файлы можно с помощью вспомогательного скрипта:

    python3 ./bin/make_secrets.py

  4. В корневом каталоге проекта создайте копию файла example.env с именем .env.
    Настройте его перед запуском docker compose.

    Далее приведены описания некоторых переменных файла .env, переопределение которых может потребоваться пользователю для корректной работы Salt.Box в его сетевой среде.

    1. Если Вы планиуете развёртывание Salt.Box на виртуальной машине или на хосте, отличном от localhost, то в файле .env должны быть переопределены переменные, значением которых по умолчанию является 'localhost':

      Порт хост-системы, которому будет сопоставлен порт контейнера Docker, обслуживающего веб-интерфейс Salt.Box, например:

      WEB_SERVER_PORT=80

      Переменной WEB_SERVER_OUTER_SOCKET должен быть присвоен сетевой адрес или сетевое имя хоста, на котором веб-интерфейс Salt.Box будет доступен пользователю. Опционально может быть указано также номер порта:

      WEB_SERVER_OUTER_SOCKET=<HOST> | <HOST>:<PORT>

      Если доступ к Salt.Box будет осуществляется без использования обратного прокси-сервера, то в WEB_SERVER_OUTER_SOCKET должен быть указан тот же порт, что и в WEB_SERVER_PORT. Если порт не указан явно, будет использовано значение по умолчанию для протокола (80/TCP для HTTP, 443/TCP для HTTPS).

    2. Сокет сервера Redis (для подключения к нему мастера).
      Для подключения внешних мастеров следует указать 0.0.0.0:6379 (все сетевые интерфейсы) либо указать адрес одного из сетевых интерфейсов:

      REDIS_SALT_EXPOSE_SOCKET=<IP_ADDRESS>:6379

    3. Переключение веб-интерфейса Salt.Box на использование протокола SSL.
      Протокол SSL накладывается внешним веб-сервером (обратным прокси-сервером).

      WEB_SERVER_SCHEME=https
      WEB_SERVER_WS_SCHEME=wss

      Для подключения к веб-интерфейсу с внешнего хоста без использования SSL необходимо в используемом браузере указать исключения для небезопасных источников.
      Ниже приведён пример соответствующей настройки для браузеров Chrome/Chromium:

      • Перейдите по адресу chrome://flags/#unsafely-treat-insecure-origin-as-secure
      • Включите опцию "Insecure origins treated as secure"
      • В поле ввода укажите URL c адресом веб-интерфейса: http://<IP_ADDRESS>
      • Перезапустите браузер

    4. Теги образов, с которых осуществляется развёртывание Salt.Box:

      CORE_AUTOTESTS_TAG=<vX.Y.Z>
      CORE_IMAGE_TAG=<vX.Y.Z>
      FRONTEND_IMAGE_TAG=<vX.Y.Z>
      KEYCLOAK_IMAGE_TAG=<vX.Y.Z>
      NGINX_IMAGE_TAG=<vX.Y.Z>
      OPA_IMAGE_TAG=<vX.Y.Z>
      REDIS_IMAGE_TAG=<vX.Y.Z>
      SALT_MASTER_IMAGE_TAG=<vX.Y.Z>
      SSHFS_IMAGE_TAG=<vX.Y.Z>

      где <vX.Y.Z> — номер версии программного комплекса Salt.Box

    5. Время ожидания остановки контейнера до принудительной остановки:

      STOP_GRACE_PERIOD=5s

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

    6. Уровень журналирования контейнера главного мастера SaltStack:

      SALT_MASTER_LOG_LEVEL='warning'
      SALT_MINION_LOG_LEVEL='warning'

      Обозначения уровней журналирования:

      УровеньЧисловое значениеОписание
      critical50Критические ошибки
      error40Ошибки
      warning30Предупреждения
      info20Важная информация, предоставляемая приложением при нормальном выполнении
      debug10Информация для диагностики проблем и устранения неполадок
      all0Все события
      предупреждение

      Любой уровень журнала ниже уровня "info" НЕБЕЗОПАСЕН и может регистрировать конфиденциальные данные.
      Подробную информацию об уровнях журналирования смотрите в документации проекта SaltStack.

    7. Пути к каталогам в файловой системе хоста Docker, в которых будут хранится конфигурации для клиентов.
      Каталоги могут быть перенесены, например, на примонтированное хранилище:

      SSHFS_STORAGE_PATH='./_sshfs-storage/'

      SSHFS-хранилище предназначено для хранения шаблонов и некоторых других типов файлов, используемых при работе Salt.Box.

Установка с помощью скрипта​

Самый простой способ запустить систему — выполнить скрипт автоматической установки:

sudo ./bin/update_and_run.sh

Скрипт автоматической установки:

  • выполняет слияние файлов example.env и override.env (если файл существует) в файл конфигурации .env
  • создаёт набор файлов с секретами
  • выполняет обновление образов
  • запускает экземпляр Salt.Box

Используйте файл override.env для переопределения значений по умолчанию из файла example.env.
Используйте флаг -h или --help для просмотра опций скрипта автоматической установки.

Альтернативным способом развёртывания сервера Salt.Box является пошаговая установка.

Пошаговая установка​

  1. Находясь в каталоге ./salt-box-compose/, запустите сборку:

    sudo docker compose up --build -d
    предупреждение

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

  2. Для обновления внешних образов выполните команду:

    sudo docker compose pull

    затем перезапустите сборку командой:

    sudo docker compose down && sudo docker compose up -d

    Если указан флаг --pull=always, перед сборкой будут загружены актуальные образы:

    sudo docker compose up --build --pull=always

    Для развёртывания рабочей версии продукта рекомендуется установить режим обработки перерасхода памяти с помощью команд:

    sudo sh -c "echo 'vm.overcommit_memory=1' > /etc/sysctl.d/salt-box.conf"
    sudo sysctl -p /etc/sysctl.d/salt-box.conf

    Значение vm.overcommit_memory=1 является требовнием Redis.

Объекты Docker, создаваемые при установке​

После успешного завершения процесса сборки создаётся ряд объектов Docker, показанных в таблицах 1, 2, 3.

Таблица 1. Загружаемые образы Docker
Образ DockerРазмерОписание
saltbox-proxy208 МБNginx reverse proxy
saltbox-make-redis-salt-certs109 МБСервис выпуска сертификатов для Redis
registry.saltbox.pro/saltbox/saltbox-compose/keycloak-init820 МБ
registry.saltbox.pro/saltbox/saltbox-compose/keycloak808 МБIdAM сервер KeyCloak
registry.saltbox.pro/saltbox/saltbox-compose/sshfs357 МБПодключаемая файловая система SSHFS
registry.saltbox.pro/saltbox/saltbox-compose/opa84 МБOpen Policy Agent
registry.saltbox.pro/saltbox/saltbox-compose/redis61 МБRedis server
registry.saltbox.pro/saltbox/saltbox-core488 МБСерверные компоненты (ядро) Salt.Box
registry.saltbox.pro/saltbox/saltbox-bridge/salt-master336 МБСервер SaltStack (Salt Master)
registry.saltbox.pro/saltbox/saltbox-frontend215 МБПользовательский интерфейс Salt.Box
postgres394 МБСУБД PostgreSQL
mongo1.1 ГБСУБД MongoDB
rabbitmq389 МББрокер сообщений RabbitMQ
Таблица 2. Контейнеры Docker, создаваемые при установке
Контейнер DockerСтатусОписание
saltbox-mongo-1UpСУБД MongoDB.
Используется бэкендом Salt.Box.
В БД хранятся такие сущности, как клиенты, коллекции и т. п.
saltbox-sshfs-1UpСервер SSH.
Используется для монтирования файловой системы sshfs на миньонах
saltbox-opa-1UpСервис Open Policy Agent.
OPA используется для создания политик доступа к различным компонентам веб-приложения
saltbox-keycloak-db-1UpСервис KeyCloak.
Обеспечивает централизированную аутентификацию в веб-интерфейсе Salt.Box
saltbox-saltbox-frontend-1UpПользовательский интерфейс Salt.Box (фронтенд)
saltbox-make-redis-salt-certs-1ExitedМодуль, предоставляющий сервис выпуска сертификатов для аутентификации на основе сертификатов Redis
saltbox-saltbox-core-tasks-watcher-1UpМодуль, ожидающий публикации задач в шине обмена SaltStack
saltbox-saltbox-core-taskiq-scheduler-1UpМодуль, отвечающий за работу с распределённой асинхронной очередью задач
saltbox-saltbox-core-taskiq-worker-1UpПроцесс Taskiq worker.
Отвечает за получение, отпарвку, выполнение задач из очереди
saltbox-rabbitmq-1UpСервис RabbitMQ.
Брокер сообщений. Отвечает за сбор данных из нескольких источников и отправляет их в сервисы для дальнейшей обработки
saltbox-redis-taskiq-1UpСервер Redis, используемый как брокер и хранилище результатов для Taskiq
saltbox-saltbox-core-faststream-redis-1UpСервер Redis, используемый как брокер для Faststream
saltbox-redis-salt-1UpСервер Redis, используемый для хранения результатов выполнения процессов, связанных с SaltStack
saltbox-keycloak-1UpПодсистема идентификации и управления доступом Salt.Box
saltbox-saltbox-core-1UpГлавный серверный компонент Salt.Box (бэкенд)
saltbox-salt-master-1UpMaster-сервер SaltStack для управления миньонами
saltbox-keycloak-init-1Exited
saltbox-proxy-1UpNginx reverse proxy.
Перенаправляет запросы клиента на внутренние сервисы в контейнерах

Статусы, указанные в таблице 2:
Up — Контейнер запущен
Exited — Контейнер запущен, затем нормально остановлен до запуска по требованию


Таблица 3. Тома Docker, создаваемые при установке
Том DockerНачальный
размер		Описание
<256-битное имя в 16-ричной записи>< 1 МБДанные сервиса RabbitMQ
(используется контейнером saltbox-rabbitmq-1)
saltbox_saltbox_core_var< 1 МБКлючи GPG
(используется контейнерами:
saltbox-saltbox-core-faststream-redis-1,
saltbox-saltbox-core-tasks-watcher-1,
saltbox-saltbox-core-1,
saltbox-saltbox-core-taskiq-scheduler-1,
saltbox-saltbox-core-taskiq-worker-1)
saltbox_keycloak-db_data67 МБДанные сервиса KeyCloak
(используется контейнером saltbox-keycloak-db-1)
saltbox_salt_master_pki< 1 МБХранилище ключей сервиса salt-master
(используется контейнером saltbox-salt-master-1)
saltbox_redis_taskiq_data< 1 МБДанные сервиса Taskiq
(используется контейнером saltbox-redis-taskiq-1)
saltbox_mongo_config< 1 МБКонфигурационные данные СУБД MongoDB
(используется контейнером saltbox-mongo-1)
saltbox_mongo_data311 МБДанные СУБД MongoDB
(используется контейнером saltbox-mongo-1)
saltbox_redis_salt_data< 1 МБДанные сервера Redis
(используется контейнером saltbox-redis-salt-1)
saltbox_redis_salt_certs< 1 МБХранилище сертификатов сервера Redis
(используется контейнерами:
saltbox-saltbox-core-faststream-redis-1,
saltbox-saltbox-core-tasks-watcher-1,
saltbox-saltbox-core-1,
saltbox-saltbox-core-taskiq-scheduler-1,
saltbox-saltbox-core-taskiq-worker-1,
saltbox-redis-salt-1,
saltbox-make-redis-salt-certs-1,
saltbox-salt-master-1)
saltbox_salt_master_saltbox_var< 1 МБ
(используется контейнером saltbox-salt-master-1)
saltbox_salt_repos< 1 МБСхемы JSON для различных функций SaltStack
(используется контейнерами:
saltbox-saltbox-core-faststream-redis-1,
saltbox-saltbox-core-tasks-watcher-1,
saltbox-saltbox-core-1,
saltbox-saltbox-core-taskiq-scheduler-1,
saltbox-saltbox-core-taskiq-worker-1,
saltbox-sshfs-1)

Образы​

Ниже приведён пример корректного вывода команды docker image ls.

REPOSITORY                                                     TAG            IMAGE ID       CREATED        SIZE
registry.saltbox.pro/salt.box/salt-box-bridge/salt-master      master         6e6a65ae6d5c   14 hours ago   305MB
registry.saltbox.pro/salt.box/salt-box-core                    master         dc990973edb6   15 hours ago   486MB
registry.saltbox.pro/salt.box/salt-box-frontend                master         cb046f5104d3   22 hours ago   215MB
salt-box-proxy                                                 latest         0a7a69e50215   9 days ago     208MB
registry.saltbox.pro/salt.box/salt-box-compose/keycloak-init   master         c3ad347807b2   11 days ago    819MB
registry.saltbox.pro/salt.box/salt-box-compose/keycloak        master         cce07c6262d2   11 days ago    808MB
registry.saltbox.pro/salt.box/salt-box-compose/sshfs           master         6d4bced308df   11 days ago    218MB
registry.saltbox.pro/salt.box/salt-box-compose/opa             master         9f4e528e02fb   11 days ago    82.6MB
registry.saltbox.pro/salt.box/salt-box-compose/redis           master         2cb6940da7ee   11 days ago    60.7MB
mongo                                                          7              8c30f14b362a   2 weeks ago    1.1GB
postgres                                                       16-alpine      3b057e1c2c6d   6 weeks ago    394MB
salt-box-make-redis-salt-certs                                 latest         f82ed3daf965   6 weeks ago    109MB
rabbitmq                                                       3-management   49895caee5d3   6 months ago   389MB

Тома​

Ниже приведён пример корректного вывода команды docker volume ls.

DRIVER    VOLUME NAME
local     f85f6baa5742b4b1bf7b3b7ca86929361c529aee6e06bff9b1a5208d76469345
local     salt-box_keycloak-db_data
local     salt-box_mongo_config
local     salt-box_mongo_data
local     salt-box_redis_salt_certs
local     salt-box_redis_salt_data
local     salt-box_redis_taskiq_data
local     salt-box_salt_box_core_var
local     salt-box_salt_master_pki

Контейнеры​

Ниже приведён пример корректного вывода команды docker compose ls -a.

NAME                STATUS                   CONFIG FILES
salt-box            exited(2), running(16)   root/salt-box-compose/compose.yaml

Ниже приведён пример корректного вывода команды docker container ls -a.

CONTAINER ID   IMAGE                                                                 COMMAND                  CREATED          STATUS                      PORTS                                                                  NAMES
88dc531cc401   salt-box-proxy                                                        "/docker/entrypoint.…"   22 minutes ago   Up 21 minutes               0.0.0.0:80->80/tcp                                                     salt-box-proxy-1
9027787dcf67   registry.saltbox.pro/salt.box/salt-box-core:master                    "entrypoint.sh salt-…"   22 minutes ago   Up 22 minutes               8000/tcp                                                               salt-box-salt-box-core-faststream-redis-1
372acea8af4a   registry.saltbox.pro/salt.box/salt-box-core:master                    "/usr/local/bin/uvic…"   22 minutes ago   Up 21 minutes               8000/tcp                                                               salt-box-salt-box-core-1
04ccd3ce9c7c   registry.saltbox.pro/salt.box/salt-box-bridge/salt-master:master      "/usr/local/bin/entr…"   22 minutes ago   Up 22 minutes               0.0.0.0:4505-4506->4505-4506/tcp, 8000/tcp                             salt-box-salt-master-1
a864aec0556a   registry.saltbox.pro/salt.box/salt-box-core:master                    "entrypoint.sh salt-…"   22 minutes ago   Up 22 minutes               8000/tcp                                                               salt-box-salt-box-core-tasks-watcher-1
8ed8856d31c1   registry.saltbox.pro/salt.box/salt-box-compose/keycloak-init:master   "/usr/local/bin/crea…"   22 minutes ago   Exited (0) 21 minutes ago                                                                          salt-box-keycloak-init-1
332bc7787b30   registry.saltbox.pro/salt.box/salt-box-core:master                    "/usr/local/bin/task…"   22 minutes ago   Up 21 minutes               8000/tcp                                                               salt-box-salt-box-core-taskiq-scheduler-1
140c425ca829   registry.saltbox.pro/salt.box/salt-box-core:master                    "/usr/local/bin/task…"   22 minutes ago   Up 21 minutes               8000/tcp                                                               salt-box-salt-box-core-taskiq-worker-1
f8b895c79ec2   registry.saltbox.pro/salt.box/salt-box-compose/redis:master           "entrypoint.sh '--sa…"   22 minutes ago   Up 22 minutes (healthy)     127.0.0.1:6379->6379/tcp                                               salt-box-redis-salt-1
05bb59635b38   registry.saltbox.pro/salt.box/salt-box-compose/keycloak:master        "/usr/local/bin/star…"   22 minutes ago   Up 21 minutes (healthy)     8080/tcp                                                               salt-box-keycloak-1
b68811fa1e30   postgres:16-alpine                                                    "docker-entrypoint.s…"   22 minutes ago   Up 22 minutes (healthy)     5432/tcp                                                               salt-box-keycloak-db-1
e7091bac8749   rabbitmq:3-management                                                 "docker-entrypoint.s…"   22 minutes ago   Up 22 minutes (healthy)     4369/tcp, 5671-5672/tcp, 15671-15672/tcp, 15691-15692/tcp, 25672/tcp   salt-box-rabbitmq-1
6673e7cb5a06   mongo:7                                                               "docker-entrypoint.s…"   22 minutes ago   Up 22 minutes               127.0.0.1:27017->27017/tcp                                             salt-box-mongo-1
8cd31f8c27ad   salt-box-make-redis-salt-certs                                        "entrypoint.sh /root…"   22 minutes ago   Exited (0) 22 minutes ago                                                                          salt-box-make-redis-salt-certs-1
b1ba6ea04662   registry.saltbox.pro/salt.box/salt-box-compose/redis:master           "entrypoint.sh '--sa…"   22 minutes ago   Up 22 minutes               6379/tcp                                                               salt-box-redis-taskiq-1
77199f687853   registry.saltbox.pro/salt.box/salt-box-frontend:master                "/docker/entrypoint.…"   22 minutes ago   Up 22 minutes               80/tcp                                                                 salt-box-salt-box-frontend-1
c727e1df0c0b   registry.saltbox.pro/salt.box/salt-box-compose/sshfs:master           "/usr/local/bin/sshd…"   22 minutes ago   Up 22 minutes               0.0.0.0:1022->1022/tcp                                                 salt-box-sshfs-1
53f1daabbebd   registry.saltbox.pro/salt.box/salt-box-compose/opa:master             "/opa run --server -…"   22 minutes ago   Up 22 minutes               0.0.0.0:8181->8181/tcp                                                 salt-box-opa-1

Режим разработки​

к сведению

Информация, приведённая в этом разделе, предназначена для разработчиков ПО, и не является важной для стандартного развёртывания сервера Salt.Box.

Обзор​

Режим разработки позволяет выполнять сборку образов вместо загрузки готовых версий и добавляет несколько полезных переопределений.

Посмотрите на раздел "Dev options" в вашей копии файла example.env.
Чтобы включить параметры разработки, раскомментируйте требуемые строки COMPOSE_FILE=.
Затем запустите compose как обычно.

Используйте флаг --watch или переключите наблюдение с помощью w в приоединённом режиме для пересборки dev-services при внесении изменений.

предупреждение

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

Сборка образов в режиме разработки​

Для создания чистых образов используйте команду с разрешённым переопределением COMPOSE_FILE:

sudo docker compose build --no-cache

Флаг --no-cache гарантирует сборку с использованием последних зависимостей.

Подключение к экземпляру redis-salt​

Режим разработки позволяет подключиться к экзепмляру Redis по URL rediss://localhost:6379 (SIC!).
Поскольку TLS включён, клиент может пропустить проверку сертификата (опция типа --insecure) или использовать корневой сертификат (CA certificate).
Корневой сертификат может быть получен с помощью команды:

sudo docker compose exec redis-salt cat /etc/redis/certs/ca.crt

Тестовые миньоны​

Режим разработки предоставляет набор миньонов с ограниченным временем жизни.
Смотрите параметры в файле example.env.

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

sudo docker compose restart salt-master
к сведению

docker compose up --force-recreate salt-master не пересоздаёт миньоны.

Очистка​

Очистка данных​

После внесения изменений контейнеры и тома могут стать несовместимыми с текущим кодом без специальных операций миграции объектов.
Чтобы исправить проблемы с запуском в среде разработки, остановите контейнеры нажатием комбинации клавиш Control-c и закройте их.

sudo docker compose -f compose.yaml -f compose-dev-override.yaml down --volumes
к сведению

Если указан флаг --volumes, то будут удалены подключённые тома, что приведёт к потере данных.
Убедитесь, что Вы не потеряете важные данные.

Очистка устаревших данных Docker​

При изменении кода и файлов конфигурации создаются новые слои и другие объекты Docker.
Для освобождения ресурсов время от времени выполняйте следующую команду:

sudo docker system prune --force

Обычно эта процедура безопасна, удаляются только устаревшие данные.

Соглашения по разработке​

Redis: каналы событий​

Имя хеша должно иметь синтаксис OBJ_TYPE:{ID}:DATA_TYPE, например, minion:{MID}:grains.
Обратите внимание на форму единственного числа для типа OBJ_TYPE и множественного числа для типа DATA_TYPE, т. к. существует множество значений объектов.

Keycloak​

Keycloak для пользователя admin (пароль находится в файле ./secrets/keycloak_admin_password):
http://localhost/auth/keycloak/