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

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

Подготовка​

  1. Клонируйте проект salt-box-compose в Ваш рабочий каталог:
git clone https://dev.saltbox.pro/salt.box/salt-box-compose.git

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

    cd ./salt-box-compose/

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

    python3 ./bin/make_secrets.py

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

Запуск​

  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, показанных в приведённой ниже таблице.

Объект DockerСтатусОписание
make-redis-salt-certs—
proxy—Nginx reverse proxy.
Перенаправляет запросы клиента на внутренние сервисы в контейнерах
Network salt-box_default—Внутренняя сеть для взаимодействия контейнеров
ТОМА:
f85f6baa5742b4b1bf7b3b7ca86929361c
529aee6e06bff9b1a5208d76469345		—
salt-box_salt_box_core_var—
(контейнер-владелец — salt-box-salt-box-core-1)
salt-box_keycloak-db_data—Данные сервиса KeyCloak
(контейнер-владелец — salt-box-keycloak-1)
salt-box_salt_master_pki—Хранилище ключей сервиса salt-master
(контейнер-владелец — salt-box-salt-master-1)
salt-box_redis_taskiq_data—Данные сервиса taskiq
(контейнер-владелец — salt-box-salt-box-core-taskiq-worker-1)
salt-box_mongo_config—Конфигурационные данные СУБД MongoDB
(контейнер-владелец — salt-box-mongo-1)
salt-box_mongo_data—Данные СУБД MongoDB
(контейнер-владелец — salt-box-mongo-1)
salt-box_redis_salt_data—Данные сервера Redis
(контейнер-владелец — salt-box-redis-salt-1)
salt-box_redis_salt_certs—Хранилище сертификатов сервера Redis
(контейнер-владелец — salt-box-redis-salt-1)
КОНТЕЙНЕРЫ:
salt-box-mongo-1UpВ контейнере запущена СУБД MongoDB.
Используется бэкендом Salt.Box.
В БД хранятся такие сущности, как клиенты, коллекции и т. п.
salt-box-sshfs-1UpВ контейнере запущен сервер SSH.
Используется для монтирования файловой системы sshfs на миньонах
salt-box-opa-1UpВ контейнере запущен сервис Open Policy Agent.
OPA используется для создания политик доступа к различным частям веб-приложения
salt-box-keycloak-db-1UpВ контейнере запущен сервис KeyCloak.
Обеспечивает централизированную аутентификацию в веб-интерфейсе Salt.Box
salt-box-salt-box-frontend-1UpПользовательский интерфейс Salt.Box (фронтенд)
salt-box-make-redis-salt-certs-1ExitedМодуль, предоставляющий сервис выуска сертификатов для аутентификации на основе сертификатов Redis
salt-box-salt-box-core-tasks-watcher-1UpМодуль, ожидающий публикации задач в шине обмена SaltStack
salt-box-salt-box-core-taskiq-scheduler-1UpМодуль, отвечающий за работу с распределённой ассинхронной очередью задач
salt-box-salt-box-core-taskiq-worker-1UpВ контейнере запущен процесс tasiq worker. Отвечает за получение, отпарвку, выполнение задач из очереди
salt-box-rabbitmq-1UpВ контейнере запущен сервис RabbitMQ — брокер сообщений.
Отвечает за сбор данных из нескольких источников и отправляет их в сервисы для дальнейшей обработки
salt-box-redis-taskiq-1Up
salt-box-salt-box-core-faststream-redis-1Up
salt-box-redis-salt-1UpВ контейнере запущен сервер Redis — резидентная система управления базами данных класса NoSQL, работающая со структурами данных типа ключ-значение.
Используется для хранения результатов выполнения процессов связанных с SaltStack
salt-box-keycloak-1UpПодсистема идентификации и управления доступом Salt.Box
salt-box-salt-box-core-1UpГлавный серверный компонент Salt.Box (бэкенд)
salt-box-salt-master-1UpСервис salt-master для управления миньонами
salt-box-keycloak-init-1ExitedСкрипты инициализации сервиса KeyCloak
salt-box-proxy-1UpNginx reverse proxy.
Перенаправляет запросы клиента на внутренние сервисы в контейнерах

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

Образы​

Ниже приведён пример корректного вывода команды 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

Автоматические тесты​

Для запуска тестовых наборов раскомментируйте строку с compose-autotests.yaml в локальном файле .env.
Затем выполните:

sudo docker compose up autotests

Для выполнения автоматических тестов необходим прямой доступ к API Keycloak, поэтому область (реалм) следует создать заново.
В качестве альтернативы в настройках клиента Keycloak можно установить флаг Direct access grants.

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

sudo docker compose up autotests --pull=never

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

Обзор​

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

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

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

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

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

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

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

sudo docker compose build --no-cache

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

Подключение к экземпляру Redis 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/