Обновление

Основным источником требований и ограничений для обновления между релизами являются Release Notes.

Этот документ дополняет Release Notes в двух случаях:

  • когда нужно описать типовой повторяемый процесс обновления, который нецелесообразно дублировать в каждом релизе;
  • когда для отдельного релиза требуется более подробная процедура, чем уместно держать в Release Notes.

Таким образом, Release Notes остаются основным источником требований конкретного релиза, а этот документ описывает общий порядок обновления и дополнительные шаги, которые могут расширять соответствующий релизный раздел.

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

  • обновлении на версию 5.3.0;
  • обновлении между версиями 5.3.0 и выше.

Данный документ не подходит для обновлений ниже 5.3.0. Для обновлений вида 5.2.1 -> 5.2.5 следует использовать только соответствующие Release Notes.

Общие правила обновления#

Резервное копирование#

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

  • БД решения;
  • данные контура переносимого состояния сервисов;
  • текущая рабочая директория установки, из которой используется smartcpd-setup.sh.

Резервное копирование БД обязательно, если в Release Notes указано изменение схемы БД.

Под данными контура переносимого состояния сервисов в этом документе понимаются данные, которые в отказоустойчивой схеме обычно размещаются в общем хранилище. В non-HA установках эти же данные могут размещаться локально на соответствующей ноде, поэтому для резервного копирования нужно ориентироваться на фактическое размещение данных в текущем контуре.

Точный состав таких данных в текущей схеме поставки описан в разделе Отказоустойчивое распределенное хранилище данных.

Обновление без остановки сервиса#

Обновление без остановки сервиса допустимо только если одновременно выполняются следующие условия:

  • обязательные настройки Docker не изменялись;
  • миграция данных в БД не выполняется;
  • обновление не затрагивает компоненты balancer, worker, redis и redis-sentinel по версиям или runtime-параметрам.

Такое обновление может вызвать временную деградацию service-слоя. В этот период могут быть затронуты:

  • UI;
  • API;
  • мониторинг и алертинг;
  • возможности управления и изменения настроек решения.

При этом обновление не должно останавливать процесс обзвона и не должно приводить к потере данных.

Во всех остальных случаях рекомендуется заранее снять трафик и выполнять обновление в технологическое окно.

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

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

В этом случае необходимо кумулятивно учитывать:

  • обязательные изменения Docker;
  • миграции данных в БД;
  • все компоненты, затронутые изменениями версий и runtime-параметров на каждом промежуточном шаге.

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

Восстановление предыдущей версии#

Если после обновления требуется восстановление предыдущей версии, рекомендуется следующий общий порядок:

  1. Остановить SmartCPD:
docker stack rm <stack_name>
  1. Восстановить БД из резервной копии.
  2. Восстановить данные контура переносимого состояния сервисов из резервной копии.
  3. Восстановить последнюю рабочую директорию установки.
  4. Из восстановленной директории установки выполнить:
./smartcpd-setup.sh deploy

Порядок обновления#

Выполнить требования Release Notes#

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

В Release Notes должны быть отражены:

  • компоненты, затронутые обновлением;
  • наличие или отсутствие миграции данных в БД;
  • изменение обязательных параметров Docker, если такие изменения есть.

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

В этом случае необходимо последовательно выполнить требования каждого промежуточного обновления. Пропуск неподдерживаемых шагов обновления не допускается.

Подготовить новую директорию поставки#

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

Необходимо:

  • скопировать новую поставку в новую рабочую директорию;
  • перенести в нее smartcpd-setup.env;
  • перенести в нее smartcpd-docker-setup.env;
  • перенести compose.override.yml, если он используется.

Это позволяет сохранить предыдущее состояние поставки и выполнять обновление из чистой директории новой версии.

Обновление настроек БД#

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

Обычно обновление настроек БД требуется, когда релиз добавляет нового пользователя БД или изменяет права доступа пользователей. Для схемы использования per-service такие изменения обычно явно указываются в Release Notes.

Для обновления настроек БД нужно выполнить SQL-скрипты из новой поставки:

  • db/postgres/sql/10-users-required.sql — обязательно;
  • db/postgres/sql/20-users-optional.sql — дополнительно для схемы per-service.

Подробности по назначению и запуску этих скриптов описаны в документе База данных.

Обновление настроек Docker#

Релиз может включать изменение обязательных параметров Docker.

Если Docker в контуре SmartCPD настраивается вручную, такие изменения должны применяться вручную в соответствии с Release Notes и разделом Ручная настройка Docker daemon.

Если для настройки Docker используется smartcpd-docker-setup.sh, что является рекомендуемым вариантом, нужно запустить его в новой директории поставки на текущей service-ноде SmartCPD, которая одновременно является manager-нодой Docker Swarm.

При запуске скрипт сам определяет, требуется ли обновление настроек Docker относительно предыдущей версии. Это используется для обновления обязательных параметров daemon.json.

Если обновление настроек Docker не требуется, дополнительных действий не нужно.

Если обновление требуется, необходимо:

  1. Выделить технологическое окно, так как применение новых настроек приведет к перезапуску Docker на manager-ноде и остальных нодах.
  2. Остановить контур SmartCPD командой:
./smartcpd-setup.sh down
  1. Выполнить smartcpd-docker-setup.sh на текущей service + manager ноде.
  2. После генерации скрипта docker/smartcpd-docker-node-setup.sh выполнить его на всех остальных нодах кластера.
  3. После завершения обновления Docker перейти к следующему шагу обновления SmartCPD.

Обновление SmartCPD#

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

Запустить smartcpd-setup.sh в новой директории поставки на текущей service + manager ноде:

./smartcpd-setup.sh

Скрипт использует сохраненные параметры из smartcpd-setup.env.

Если обязательного обновления setup-параметров для текущей версии не требуется, скрипт сообщит об этом и спросит, нужно ли изменять параметры. Если обновление параметров требуется, скрипт сразу перейдет к полному setup flow.

При обновлении SmartCPD рекомендуется выполнить полный проход setup-скрипта и проверить актуальность параметров новой поставки.

Перед подтверждением deployment необходимо:

  • скопировать сгенерированные stack/smartcpd-node-*-setup.sh на ноды с соответствующими ролями;
  • выполнить их на этих нодах;
  • если нода совмещает несколько ролей, последовательно выполнить все требуемые role-specific скрипты.

После подготовки нод можно подтверждать deployment.

Дальнейший порядок действий соответствует разделам Процесс установки и Проверка запуска документа Установка.

Обновления отдельных версий#

5.2.8+ -> 5.3.0#

Для обновления с версии 5.2.8+ до 5.3.0 требуется переход на новый setup flow.

Порядок действий:

  1. Остановить стек SmartCPD:
docker stack rm smartcpd

  1. Выполнить полное резервное копирование в соответствии с разделом Резервное копирование.

  2. Выполнить резервное копирование текущей схемы каталогов и их данных на всех нодах.

  3. На всех нодах привести структуру каталогов к новой схеме:

  • Local data root [/opt/scpd];
  • Shared data root [/opt/shared_data].

В текущем setup flow используются только эти два корневых пути. В non-HA установке допускается указать один и тот же локальный путь и для Local data root, и для Shared data root.

Размещение обязательных каталогов по ролям:

  • service:
    • ${LOCAL_DATA_ROOT}/redis_data
    • ${SHARED_DATA_ROOT}/config-server_data
    • ${SHARED_DATA_ROOT}/metrics_data
  • worker:
    • ${LOCAL_DATA_ROOT}/node_records
    • ${LOCAL_DATA_ROOT}/node_results
    • ${LOCAL_DATA_ROOT}/node_prompts
  • analyzer и balancer:
    • для этих ролей в текущей схеме установки отдельные обязательные каталоги не используются.

Role-specific node-setup scripts сами создают и проверяют нужные подкаталоги с корректными правами доступа. На этапе подготовки к обновлению нужно привести существующие данные к новой схеме корневых путей и убедиться, что целевые root-каталоги доступны на нужных нодах.

  1. Скопировать новую поставку в новую рабочую директорию.
  2. Скопировать файл setup.env из текущего deployment в новую директорию поставки.

При необходимости можно дополнительно выполнить smartcpd-docker-setup.sh, если требуется перевести контур на managed-схему настройки Docker.

При таком переходе следует учитывать, что параметры mTLS для Docker daemon должны задаваться через systemd override, а не через daemon.json, если они уже использовались в предыдущем контуре. Подробности описаны в документе Docker.

  1. Запустить:
./smartcpd-setup.sh

Скрипт подхватит старый setup.env, выполнит миграцию параметров в новый формат и покажет перенесенные значения перед продолжением setup.

В новом setup вместо отдельных путей к данным задаются только Local data root и Shared data root.

В версии 5.3.0 в поставку добавлен встроенный контур мониторинга и логирования. Включать или не включать его можно на этапе прогона smartcpd-setup.sh. Подробности по составу и режиму использования этого контура описаны в документе Логирование и мониторинг.

Расширенные настройки NGINX больше не задаются через интерактивный setup и должны оформляться через compose.override.yml. То же относится к настройке таймаута cloud-connector при работе через proxy. Подробности описаны в разделах Использование compose.override.yml, Настройка дополнительной безопасности NGINX и Настройка таймаута для cloud-connector при использовании proxy документа Установка.

  1. Перед немедленным применением стека отказаться от deployment.
  2. Выполнить:
./smartcpd-setup.sh labels

И проверить назначение labels на нодах.

  1. Скопировать stack/smartcpd-node-*-setup.sh на серверы с соответствующими ролями и выполнить их, включая текущий сервер, если ему назначены соответствующие роли.
  2. После этого выполнить:
./smartcpd-setup.sh deploy

В остальном этот переход соответствует разделам Процесс установки и Проверка запуска документа Установка. Специфика сценария 5.2.8+ -> 5.3.0 состоит в необходимости перенести старый setup.env в новую поставку и пройти миграцию параметров на новый setup flow.

Восстановление предыдущей версии#

Если после перехода 5.2.8+ -> 5.3.0 требуется восстановить предыдущую версию, рекомендуется следующий порядок:

  1. Остановить стек SmartCPD:
docker stack rm smartcpd
  1. Восстановить БД из резервной копии.
  2. Восстановить прежнюю структуру каталогов и их данные на всех нодах.
  3. Перейти в директорию установки предыдущей версии и выполнить:
docker stack deploy -c compose.yml smartcpd

Дата формирования

Backward База данных Docker Forward
Powered by Altuera