Подготовка к установке Sage

Подготовка к развертыванию Sage выполняется на контрольном хосте и состоит из трех этапов:

1. Проверка инфраструктуры — автоматическая проверка хостов утилитой Sage Precheck.
2. Запуск контейнера установщика — подготовка изолированной среды для Ansible.
3. Настройка контейнера — указание дополнительных параметров перед запуском установки (опционально).

Важно

Перед началом выполнения инструкции убедитесь, что соблюдены следующие условия:

• подготовлена инфраструктура (серверы, сеть, DNS) в соответствии с Требованиями;
• созданы SSH-ключи для доступа к целевым хостам;
• от инженеров техподдержки Т-Софт получены:
  • ключ key.json для авторизации в репозитории с образами;
  • файл лицензии Sage;
  • номер актуальной версии Sage.

Этап 1. Проверка готовности инфраструктуры

Шаг 1. Получение утилиты Sage Precheck

Утилита распространяется в виде скрипта sage.sh, который загружает бинарный файл.

Примечание

Если установка или обновление производится в изолированном окружении, скрипт sage.sh и утилиту sage-precheck необходимо заранее скопировать на контрольный хост.

1. Скачайте или скопируйте на контрольный хост скрипт-загрузчик sage.sh.

2. Поместите файл сервисного ключа key.json в ту же директорию, где находится скрипт.

3. Загрузите утилиту проверки:

   chmod +x sage.sh
   ./sage.sh precheck-download

   Команда выполнит авторизацию в Yandex Cloud Storage и скачает утилиту на контрольный хост. В результате в текущей директории появится исполняемый файл sage-precheck.

Шаг 2. Настройка конфигурации

1. Создайте в той же директории конфигурационный файл config.yaml, в котором опишите доступы к целевым хостам и их роли.

   Пример конфигурации:

   config.yaml

   username: sage  # Пользователь на целевых хостах
   privateKeyPath: /private/key/path  # Путь к приватному SSH-ключу на контрольном хосте
   privateKeyPassword: privateKeyPassword  # Пароль ключа (если есть), иначе оставить пустым
   hosts:
    - hostname: host1.sage.example.com  # FQDN сервера
      ssh_port: 22  # Порт SSH (опционально, по умолчанию 22)
      roles: ["USER_DATA", "WARM"]  # Роли хоста
   
   # Справочник ролей:
   # USER_DATA — наличие раздела для хранения данных
   # WARM      — разрешение на использование HDD

Шаг 3. Запуск проверки

1. Запустите утилиту для проверки требований:

   chmod +x sage-precheck
   ./sage-precheck -config config.yaml -output report

   После завершения проверки в директории report будут созданы три файла:

   • report.txt — основной отчет по каждому хосту со списком требований, не прошедших проверку;
   • report.json — структурированный результат для парсинга с итоговым статусом (OK/FAIL);
   • raw_data.json — сырые данные, собранные с хостов.

2. Изучите report.txt и при необходимости исправьте конфигурацию соответствующих хостов: настройте параметры ядра, установите пакеты, проверьте сеть.

3. После исправлений запустите проверку повторно.

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

Этап 2. Запуск контейнера установщика

Шаг 1. Авторизация в реестре образов

Образы компонентов Sage, включая образ контейнера установщика, хранятся в Yandex Cloud Container Registry. Для доступа к реестру используется сервисный ключ Yandex Cloud. Файл ключа key.json должен находиться в директории со скриптом sage.sh.

1. Убедитесь, что файл key.json находится в директории со скриптом sage.sh.

2. Авторизуйтесь в реестре образов:

   ./sage.sh login

   При успешной авторизации отобразится сообщение Login succeeded.

Важно

Образы могут загружаться на контрольный хост напрямую из Yandex Cloud Container Registry либо из локального реестра. Если контрольный хост не имеет прямого доступа к реестру Yandex Cloud, скачайте образы в локальный реестр и укажите путь в переменной sage_images_source:

sage_images_source:
  path: <адрес_локального_реестра>
  username: json_key
  password: ""

Подробнее см. в разделе Работа с файлами конфигурации.

Шаг 2. Подготовка окружения и конфигурации

На этом шаге нужно скачать образ с шаблонами конфигурации clans и подготовить служебные директории.

1. Задайте версию Sage — обязательно с префиксом v:

   export SAGE_VERSION=<версия SAGE> # Пример: v1.12.41. Буква `v` обязательна

2. Скопируйте шаблоны конфигурации и подготовьте служебные директории:

   # Создать директории
   mkdir -p certificates license step spirit/kratos sage-ssh
   
   # Установить права для директорий
   chmod -R 0777 certificates license step spirit
   
   # Скачать шаблон файла конфигурации из образа-примера
   sudo docker run --name sage-trukk-${SAGE_VERSION}-template --pull always cr.yandex/crp9e7v1gtl8rlvmji4q/sage-trukk-example:release-${SAGE_VERSION} bash
   
   # Скопировать шаблон конфигурации из контейнера в текущую директорию
   sudo docker cp sage-trukk-${SAGE_VERSION}-template:/home/trukker/ansible/clans ./
   
   # Удалить временный образ
   sudo docker rm -f sage-trukk-${SAGE_VERSION}-template
   
   # Установить корректные права (UID/GID 1010 внутри контейнера)
   sudo chown -R 1010:1010 certificates step clans spirit

3. Настройте инвентарь. Для этого:

   1. Откройте файл clans/example/prod/1vm/hosts.yml для флейвора 1VM или clans/example/prod/3vm/hosts.yml для флейвора 3VM.

      Внимание

      Если вы разворачиваете Sage в конфигурации, требующей использования более трех хостов, обратитесь за помощью к инженерам техподдержки Т-Софт.

   2. Замените fqdn.host.example на реальные FQDN ваших серверов.

4. Подготовьте лицензию и SSH-ключи:

   1. Поместите в директорию license файл лицензии.

      Важно

      Файл лицензии должен называться строго sage_license.json. Если ваш файл называется иначе, переименуйте его.

   2. Скопируйте в папку sage-ssh приватный SSH-ключ, с помощью которого вы подключаетесь к целевым хостам. Убедитесь, что файл имеет понятное имя (например, sage_key), чтобы не перепутать его с key.json.

      mkdir sage-ssh
      cp ~/.ssh/<KEY_FILENAME> sage-ssh

   3. Установите права внутри контейнера:

      sudo chown -R 1010:1010 license sage-ssh

Шаг 3. Запуск контейнера установщика

Установщик Sage работает внутри Docker-контейнера sage-trukk, что гарантирует идентичность среды независимо от ОС контрольного хоста.

Замените <SSH_USER> и <KEY_FILENAME> на ваши значения и запустите контейнер установщика:

sudo docker run -it --name sage-trukk-${SAGE_VERSION} --pull always --network host \
-v "${PWD}/certificates:/home/trukker/ansible/files/certificates:rw" \
-v "${PWD}/step:/home/trukker/ansible/files/step:rw" \
-v "${PWD}/clans:/home/trukker/ansible/clans:rw" \
-v "${PWD}/sage-ssh:/home/trukker/.ssh:rw" \
-v "${PWD}/license:/home/trukker/ansible/files/licenses:rw" \
-v "${PWD}/key.json:/home/trukker/ansible/files/key.json:rw" \
-v "${PWD}/spirit/kratos:/home/trukker/ansible/files/spirit/kratos:rw" \
-e 'ANSIBLE_REMOTE_USER=<SSH_USER>' \
-e 'ANSIBLE_PRIVATE_KEY_FILE=/home/trukker/.ssh/<KEY_FILENAME>' \
cr.yandex/crp9e7v1gtl8rlvmji4q/sage-trukk-example:release-${SAGE_VERSION} bash

Пояснения к параметрам запуска

• -v ...certificates... — Сертификаты для TLS/SSL.
• -v ...step... — Токены Sage и Spirit IAM (для управления доступом).
• -v ...clans... — Конфигурация Ansible (инвентари, переменные, плейбуки).
• -v ...sage-ssh... — SSH-ключи для доступа к целевым хостам (маппинг на домашнюю директорию пользователя внутри контейнера).
• -v ...license... — Файл лицензии Sage.
• -v ...key.json... — Сервисный ключ Yandex Cloud (для доступа к реестру изнутри контейнера).
• -v ...spirit/kratos... — Конфигурация Spirit IAM (Kratos, Hydra, OIDC).
• -e 'ANSIBLE_REMOTE_USER...' — Пользователь, от имени которого Ansible будет подключаться к целевым хостам.
• -e 'ANSIBLE_PRIVATE_KEY_FILE...' — Путь к приватному SSH-ключу внутри контейнера.
• cr.yandex/... — Имя образа установщика с версией, соответствующей переменной SAGE_VERSION. Адрес соответствует выбранному реестру образов: cr.yandex для Yandex Cloud Container Registry либо адрес локального реестра, указанного в переменной sage_images_source.

При первом запуске контейнер запросит пароль для Ansible Vault — сгенерируйте пароль самостоятельно.

Внимание

Запомните этот пароль! Он потребуется для шифрования секретов и последующих запусков установки.

После успешного ввода пароля вы окажетесь внутри контейнера — вас встретит приглашение ко вводу:

trukker@sage-trukk:~ $

Этап 3. Настройка внутри контейнера (Опционально)

Все дальнейшие команды выполняются внутри запущенного контейнера (в оболочке bash).

Шаг 1. Конфигурация установки

Для стандартных флейворов (1VM/3VM) базовая конфигурация уже готова.

Если вы используете индивидуальную конфигурацию и/или вам требуется тонкая настройка параметров (порты, пути, лимиты), см. справочник переменных и инструкцию по редактированию в разделе Конфигурация установки Sage.

Шаг 2. Установка секретов

По умолчанию в шаблонах используются безопасные значения-заглушки — например, changeme. Для установки собственных значений выполните следующие действия:

1. Откройте файл секретов:

   • Для 1VM: clans/example/prod/1vm/group_vars/sage/_secrets.yml
   • Для 3VM: clans/example/prod/3vm/group_vars/sage/_secrets.yml

2. Замените значения по умолчанию на свои.

Совет

При необходимости вы можете зашифровать пароль с помощью Ansible Vault:

ansible-vault encrypt_string 'my_super_password'

Скопируйте вывод и вставьте его в файл секретов вместо открытого текста.

Следующие шаги

В результате выполнения инструкции:

1. Проверена готовность инфраструктуры.
2. Подготовлен файл инвентаря hosts.yml — указаны серверы для развертывания.
3. Запущен контейнер установщика.

На этом подготовка к развертыванию завершена. Подробнее о том, как запустить Ansible-плейбук и развернуть Sage, см. в разделе Процесс установки Sage.