Перейти к основному содержимому
Версия: 1.12

Подготовка к обновлению Sage

Перед переходом на новую версию Sage выполните следующие шаги:

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

Инструкция подходит для всех версий Sage:

  • мажорных — например, 1.12 → 1.13;
  • минорных — например, 1.12.1 → 1.12.2.

Обновление выполняется из той же рабочей директории на контрольном хосте, которая использовалась при первичной установке. Если вы планируете выполнять обновление из новой директории, скопируйте в нее все содержимое рабочей директории установщика из предыдущей инсталляции.

Этап 1. Подготовка конфигурации​

Убедитесь, что конфигурация Sage готова к обновлению.

Шаг 1. Изучение Upgrade Notes​

Upgrade Notes содержат обязательные шаги и особенности перехода. Для мажорной версии Sage ознакомиться с ними обязательно; для минорной версии Upgrade Notes может не быть — в этом случае руководствуйтесь общей инструкцией.

  1. Ознакомьтесь с Upgrade Notes версии, на которую планируете выполнить обновление.

  2. Внесите необходимые изменения в конфигурационные файлы — см. раздел Работа с файлами конфигурации.

  3. При необходимости обновите отдельные компоненты — см. раздел Обновление компонентов.

Шаг 2. Создание резервной копии​

Перед началом работ создайте резервную копию текущей конфигурации. Это позволит восстановить рабочее состояние Sage, если в процессе что-то пойдет не так.

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

Храните резервную копию до тех пор, пока не убедитесь, что Sage работает корректно.

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

Убедитесь, что инфраструктура соответствует требованиям. Для проверки используйте утилиту Sage Precheck.

Шаг 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. После исправлений запустите проверку повторно.

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

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

Шаг 1. Проверка лицензии и выбор версии​

  1. Убедитесь, что файл лицензии sage_license.json находится в директории license.

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

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

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

Образы компонентов 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: ""

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

Шаг 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, который использовался при первой установке Sage. После успешного ввода пароля вы окажетесь внутри контейнера — вас встретит приглашение ко вводу:

trukker@sage-trukk:~ $

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

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

Последнее обновление