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

Upgrade Notes v1.12

Установщик Sage

Добавление группы ДЦ

Начиная с версии Sage 1.12 установщик поддерживает 2 формата Ansible Inventory:

  1. старый ("кланы", содержащие конфигурацию каждого ДЦ)
  2. новый (единый инвентарь, содержащий информацию о всех ДЦ)

Если Sage должен быть развёрнут в 3 ДЦ или более, то необходимо использовать инвентарь нового формата.

Sage развёртывается только в одном окружении, например prod, test, dev. Соответствующий инвентарь хранится в директории inventories/<env>/:

inventories/
  stage/
  test/
  prod/
    hosts.yml
    group_vars/
      dc1/
        nginx.yml
      dc2/
        nginx.yml
      sage/
        sage.yml

В директории inventories содержатся поддиректории, соответствующие окружениям — один Sage установлен в одно окружение, не поддерживается установка одного Sage и в dev, и в prod. Внутри директорий devstageprod каждое из окружений конфигурируется по отдельности, не добавляя ЦОД как отдельную дополнительную вложенность — вместо этого используются Ansible-группы:

prod/dc01/hosts.yml
---
nginx:
hosts:
ng1-dc01.example.ru:
ng2-dc01.example.ru: # <-- Добавили второй Nginx
kafka:
hosts:
ka-dc01.example.ru:
...

dc01:
hosts:
ng1-dc01.example.ru:
ng2-dc01.example.ru: # <-- Этот же хост надо указать в группе dc01
ka-dc01.example.ru:
...
prod/dc02/hosts.yml
---
nginx:
hosts:
ng1-dc02.example.ru:
ng2-dc02.example.ru: # <-- Добавили второй Nginx
kafka:
hosts:
ka-dc02.example.ru:
...

dc02:
hosts:
ng1-dc02.example.ru:
ng2-dc02.example.ru: # <-- Этот же хост надо указать в группе dc02
ka-dc02.example.ru:
...

Таким образом, в рамках нового формата необходимо изменить структуру директорий (убрать один уровень вложенности) и добавить группы, названные по имени ДЦ, содержащие список всех хостов, содержащихся в этом ДЦ.

Для миграции между форматами предлагается следующая последовательность действий.

1. Создайте новую структуру директорий

В директории ansible/ для каждого существующего окружения env создайте директорию inventories/env/ со следующим содержимым:

inventories/
dev/
test/
prod/
group_vars/
dc01/
dc02/
...

Имена ДЦ используйте те, что вы использовали в кланах - например, если вы использовали единственное окружение prod с двумя кланами clans/example/prod/{dc1,dc2}/, то новая структура будет выглядеть следующим образом:

inventories/
prod/
group_vars/
dc1/
dc2/
sage/

2. Заполните файлы с хостами

Новый Ansible inventory позволяет использовать единый файл, в котором перечислены все хосты Sage, или же несколько отдельных файлов.

Продолжая пример, создайте файлы inventories/prod/dc1.yml и inventories/prod/dc2.yml, скопировав в них содержимое файлов clans/example/prod/{dc1,dc2}/hosts.yml:

cat clans/example/prod/dc1/hosts.yml > inventories/prod/dc1.yml
cat clans/example/prod/dc2/hosts.yml > inventories/prod/dc2.yml

Теперь необходимо создать группы dc1 и dc2, и перечислить в них все хосты, принадлежащие соответствующему ДЦ:

inventories/prod/dc1.yml
...
# Here go groups from clans/example/prod/dc1/hosts.yml
...

dc1:
hosts:
kafka1.dc1.example.com:
nginx1.dc1.example.com:
apps1.dc1.example.com:
...
inventories/prod/dc2.yml
...
# Here go groups from clans/example/prod/dc2/hosts.yml
...

dc2:
hosts:
kafka1.dc1.example.com:
nginx1.dc1.example.com:
apps1.dc1.example.com:
...

Возможно, у вас будет несколько раз определена группа external. Хосты, перечисленные в группе external, не должны настраиваться установщиком Sage и не принадлежат ни одной группе ДЦ. Остальные хосты обязательно должны состоять в одной и только одной группе ДЦ.

3. Удалите ненужные группы

Старые группы, содержащие списки хостов из другого ДЦ, больше не нужны. Удалите из файла группы elastic_remote_cluster и victoriametrics_select_remote.

После выполнения этого шага выполните команду ansible-inventory --graph — вы должны увидеть инвентарь следующего вида (для наглядности показана лишь часть групп):

@all:
|--@ungrouped:
|--@sage:
| |--@sage_hosts:
| | |--@clickhouse:
| | | |--click0.dc1.example.com
| | | |--click1.dc1.example.com
| | | |--click0.dc2.example.com
| | | |--click1.dc2.example.com
| | |--@grafana:
| | | |--grafana0.dc1.example.com
| | | |--grafana0.dc2.example.com
| | |--@kafka:
| | | |--kafka0.dc1.example.com
| | | |--kafka1.dc1.example.com
| | | |--kafka2.dc1.example.com
| | | |--kafka0.dc2.example.com
| | | |--kafka1.dc2.example.com
| | | |--kafka2.dc2.example.com
| | |--@nginx:
| | | |--apps0.dc1.example.com
| | | |--apps1.dc1.example.com
| | | |--apps2.dc1.example.com
| | | |--apps0.dc2.example.com
| | | |--apps1.dc2.example.com
| | | |--apps2.dc2.example.com
| |--ansible-control-plane
|--@external:
|--@dc1:
| |--apps0.dc1.example.com
| |--apps1.dc1.example.com
| |--apps2.dc1.example.com
| |--click0.dc1.example.com
| |--click1.dc1.example.com
| |--kafka0.dc1.example.com
| |--kafka1.dc1.example.com
| |--kafka2.dc1.example.com
| |--grafana0.dc1.example.com
|--@dc2:
| |--apps0.dc2.example.com
| |--apps1.dc2.example.com
| |--apps2.dc2.example.com
| |--click0.dc2.example.com
| |--click1.dc2.example.com
| |--kafka0.dc2.example.com
| |--kafka1.dc2.example.com
| |--kafka2.dc2.example.com
| |--grafana0.dc2.example.com

4. Перенесите групповые переменные

Переменные, прежде определённые в директориях clans/example/prod/{dc1,dc2}/group_vars/sage/, должны оказаться в директориях, соответствующим ДЦ. Например, файл clans/example/prod/dc1/group_vars/sage/nginx.yml должен быть перемещён в директорию inventories/prod/group_vars/dc1/nginx.yml.

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

cp -rTL clans/example/prod/dc1/group_vars/sage/ inventories/prod/group_vars/dc1
cp -rTL clans/example/prod/dc2/group_vars/sage/ inventories/prod/group_vars/dc2

Переменные, одинаковые для всех ДЦ (например, sage_external_domain) можно указать один раз в директории inventories/prod/group_vars/sage/ и удалить их вхождения из директорий inventories/prod/group_vars/{dc1,dc2}/. Найти одинаковые файлы можно при помощи команды

diff -rs inventories/prod/group_vars/dc1 inventories/prod/group_vars/dc2
Обратите внимание!
  1. Если у вас определены переменные *elastic_remote_cluster_name, удалите их.

  2. Если есть, файлы _secrets_keycloak.ignore.yml, _secrets_spirit.ignore.yml и _secrets_step.ignore.yml необходимо перенести в директорию inventories/prod/group_vars/sage.

  3. Для каждого ДЦ надо объявить свою переменную sage_datacenter:

    inventories/prod/group_vars/dc1/sage.yml
    ---
    ...
    sage_datacenter: dc1
    ...

    inventories/prod/group_vars/dc2/sage.yml
    ---
    ...
    sage_datacenter: dc2
    ...

    Значение переменной должно содержать имя ДЦ, которому принадлежат хосты!

    Рекомендуем проверить файлы в директориях group_vars/{dc1,dc2}/: значения переменных, указанных там, мало отличаются между кланами и могут быть указаны в одной директории group_vars/sage/.

5. Убедитесь, что миграция прошла успешно

Для того, чтобы убедиться в успешности миграции, выполните команды:

export ANSIBLE_INVENTORY=groups,inventories/prod
export SAGE_DC=dc1
ansible-playbook -CD sage-setup.yml

Команда запустит плейбук установки Sage в ДЦ dc1 в режиме отладки: команда виртуально повторит процесс установки и покажет предполагаемые изменения, не применяя их — запускать её безопасно на любом окружении.

Если всё было настроено верно, команда не покажет существенных изменений в файлах конфигурации: порядок следования полей в файлах может измениться, однако на функциональность Sage это не повлияет.

Изменения в процессе установки

Теперь процесс установки инициируется путём прямого вызова Ansible-плейбука:

ansible-playbook sage-setup.yml

Для выполнения определённого этапа установки следует использовать соответствующие теги:

ansible-playbook sage-setup.yml --tags "apps"

Полный список доступных тегов представлен в плейбуках sage-setup.yml и файлах, расположенных в каталоге setup_playbooks/*.

Снижение downtime алертинга

Для мульти-ДЦ инсталляций доступна новая схема обновления, позволяющая существенно сократить время простоя системы алертинга.

Для её активации необходимо перед началом процедуры обновления выполнить команду:

export SAGE_SHARED_DB=true

При использовании данного флага сначала производится установка приложений, а затем применяются миграции. Такой порядок действий обеспечивает обработку алертов как минимум одним ДЦ в любой момент времени.

dp-connector

Версия 1.12 содержит новую обязательную компоненту dp-connector, участвующую в процессе синхронизации групп. Компонента практически не потребляет ресурсов, перед установкой версии 1.12 добавьте группу dp_connector, содержащую любой из уже существующих серверов (на него будет установлена эта компонента) в файл hosts.yml:

dp_connector:
hosts:
any-host.domain:

Изменение работы Precheck

Начиная с версии Sage 1.12 Precheck (шаг check) по-умолчанию запрещает установку/обновление при наличии предупреждений (например, если вы используете неподдерживаемые переменные). Это поведение может быть сознательно изменено при необходимости, рекомендуется согласование отключения с поддержкой.

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

export SAGE_CHECK_FAIL_ON_WARNINGS=false

Не рекомендуется продолжать установку/обновление Sage при наличии предупреждений.

Сертификаты

Формат сертификатов, используемых в Sage, был изменён. Подробности см. в инструкции по установке Sage, раздел «Сертификаты».

Обновление Grafana v9 → v11

Плагины Grafana

Grafana 11 — последняя версия, в которой сохраняется поддержка плагинов, использующих angularjs. Начиная с версии Grafana 12 эти плагины перестанут работать. Поэтому при текущей миграции следует заранее проверить свои плагины.

Plugin IDНаименованиеТипРешениеКомментарий
anodot-panelAnodotPanelУдален:
• для соблюдения требования ИБ
• angularjs плагин
briangann-datatable-panelGrafana Datatable PanelPanelУдален:
• для соблюдения требования ИБ
• angularjs плагин
Перейти на нативную панель Table (не путать с Table (old))
flant-statusmap-panelStatusmapPanelУдален:
• плагин не совместим с Grafana 11
• более не поддерживается
• для соблюдения требования ИБ
• angularjs плагин
Перейти на нативную панель Status history / State timeline
gapit-htmlgraphics-panelHTML graphicsPanelУдален:
• для соблюдения требования ИБ
• angularjs плагин
Перейти на нативную панель Canvas Panel / Text
grafana-worldmap-panelWorldmap PanelPanelУдален:
• плагин более не поддерживается
• для соблюдения требования ИБ
• angularjs плагин
Перейти на нативную панель Geomap
jdbranham-diagram-panelDiagramPanelУдален:
• для соблюдения требования ИБ
• angularjs плагин
Перейти на нативную панель Canvas Panel
marcusolsson-calendar-panelBusiness CalendarPanelУдален:
• для соблюдения требования ИБ
marcusolsson-gantt-panelGanttPanelУдален:
• плагин более не поддерживается
• для соблюдения требования ИБ
• angularjs плагин
Перейти на нативную панель State timeline
vonage-status-panelStatus PanelPanelУдален:
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель Stat / Polystat
natel-plotly-panelNatel Plotly PanelPanelУдален:
• плагин не совместим с Grafana 11
• плагин более не поддерживается
• angularjs плагин
agenty-flowcharting-panelFlowChartingPanelУдален:
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель Canvas Panel
grafana-piechart-panelPie chart (old)PanelУдален:
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель Pie chart
yesoreyeram-boomtable-panelBoom TablePanelУдален:
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель Table с использованием transformations при необходимости
natel-discrete-panelDiscretePanelУдален:
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель State timeline
blackmirror1-singlestat-math-panelSinglestat MathPanelУдален:
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель Stat с использованием transformations при необходимости
gipong-grafana-groupedbarchart-panelGrouped Bar ChartPanelУдален:
• плагин не совместим с Grafana 11
• плагин более не поддерживается
• angularjs плагин
Перейти на нативную панель Bar Chart
raintank-worldping-appworldPingPanelУдален:
• плагин не совместим с Grafana 11
• angularjs плагин
• официальный EOL плагина
alexanderzobnin-zabbix-appZabbixDatasourceУдален:
• для соблюдения требования ИБ
anodot-datasourceAnodot DatasourceDatasourceУдален:
• для соблюдения требования ИБ
camptocamp-prometheus-alertmanager-datasourcePrometheus AlertManager DatasourceDatasourceУдален:
• для соблюдения требования ИБ
Перейти на нативный источник данных AlertManager
frser-sqlite-datasourceSQLiteDatasourceУдален:
• Беканд Grafana использует PostgreSql
Требуется только для Grafana, использующего SQLite
simpod-json-datasourceJSONDatasourceУдален:
• для соблюдения требования ИБ
vertamedia-clickhouse-datasourceAltinity plugin for ClickHouseDatasourceУдален:
• для соблюдения требования ИБ
yesoreyeram-infinity-datasourceInfinityDatasourceУдален:
• для соблюдения требования ИБ
sbueringer-consul-datasourceConsulDatasourceУдален:
• для соблюдения требования ИБ
• плагин более не поддерживается
Перейти на нативный источник данных Prometheus для сбора метрик (через эндпоинт /agent/metrics)

Процедура обновления до Grafana v11

  1. Сделать резервную копию базы данных Grafana v9.

    Как создать резервную копию БД
    pg_dump \
    --dbname=sage_grafana \
    --host=sage.grafana.host \
    --port=5432 \
    --username=sage_grafana \
    --schema=sage_grafana \
    --no-tablespaces \
    --format=directory \
    --file=./grafana_db_dump \
    --verbose
  2. Подготовить окружение:

    • в group_vars/all/grafana.yml параметру grafana_version_variant присвоить значение grafana_11
    • в group_vars/all/_versions.yml параметру grafana_version присвоить значение release-a78522620
  3. Развернуть Grafana v11 поверх Grafana v9 командой:

    ansible-playbook sage-setup.yml --diff --tags=reload_grafana --skip-tags always
  4. Проверить, что Grafana работает корректно и не возникает проблем с дашбордами.

Процедура отката до Grafana v9

  1. Подготовить окружение:

    • в group_vars/all/grafana.yml параметру grafana_version_variant присвоить значение grafana_9
    • в group_vars/all/_versions.yml параметру grafana_version присвоить значение release-av16
  2. Остановить контейнер Grafana.

  3. Восстановить базу данных Grafana v9 из резервной копии.

    Как восстановить БД из резервной копии
    pg_restore \
    --dbname=sage_grafana \
    --host=sage.grafana.host \
    --port=5432 \
    --username=sage_grafana \
    --schema=sage_grafana \
    --jobs=2 \
    --no-owner \
    --clean \
    --format=directory \
    --verbose \
    ./grafana_db_dump/

    После операции восстановления может потребоваться установить схему по умолчанию для пользователя Grafana:

    ALTER USER sage_grafana set SEARCH_PATH = 'sage_grafana';
  4. Развернуть Grafana v9 поверх Grafana v11 командой:

    ansible-playbook sage-setup.yml --diff --tags=reload_grafana --skip-tags always

Обновление Kafka

По умолчанию при вызове инсталлятора происходит обновление компонентов до новых версий. Для того, чтобы оставить текущие версии, требуется внести следующее изменение в клан — в файле group_vars/sage/kafka.yml прописать:

sage_kafka_version: current

Для обновления необходимо использовать инструкцию: Обновление Kafka.

Обновление VictoriaMetrics

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

vm_versions: current

Компоненты VictoriaMetrics были обновлены до v1.127.0 в предыдущем релизе. В 1.12 ожидается обновление клиентов, которые ещё не перешли на эту версию.

В рамках 1.12:

  • удалён vmagent;
  • при использовании v1.127.0 ожидается увеличение потребления памяти vmselect примерно на 50%.

Настройка времени хранения метрик VictoriaMetrics STS

Теперь retention у VictoriaMetrics можно задавать через переменную:

sage_metric_retention_sts: 180d

Поддержка VictoriaMetrics LTS

Начиная с версии Sage 1.12 добавлена поддержка LTS (Long-Term Support) в VictoriaMetrics.

Новые группы

Для использования LTS-версии VictoriaMetrics необходимо добавить в инвентарь следующие группы:

  • victoriametrics_storage_lts — инстансы vmstorage для LTS-кластера
  • victoriametrics_insert_lts — инстансы vminsert для LTS-кластера
  • victoriametrics_select_lts — инстансы vmselect для LTS-кластера

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

victoriametrics_storage_lts:
hosts:
vmstorage-lts-0.example.com:
vmstorage-lts-1.example.com:

victoriametrics_insert_lts:
hosts:
vminsert-lts-0.example.com:
vminsert-lts-1.example.com:

victoriametrics_select_lts:
hosts:
vmselect-lts-0.example.com:
vmselect-lts-1.example.com:

Добавление LogsCollector

Начиная с версии Sage 1.12 запись логов клиентских приложений выполняется через новый компонент – Logs Collector. Он реализует механизмы авторизации и квотирования при записи логов. Возможность прямой записи в Kafka по-прежнему доступна, однако рекомендуем переходить на новый компонент.

Новые группы

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

  • logs_collector_api: Реализует API для записи логов
  • logs_collector_scoring: Реализует подсчёт квот (scoring)
  • redis_logs_collector: Инстансы Redis, которые используются Logs Collector для синхронизации.

Пример в инвентаре:

logs_collector_api:
hosts:
logs-collector.host-1.example.com:
logs-collector.host-2.example.com:
logs_collector_scoring:
hosts:
logs-collector.host-3.example.com:
logs-collector.host-4.example.com:
redis_logs_collector:
hosts:
redis.host-1.example.com:
redis.host-2.example.com:
  • Все три группы обязательны
  • Для реализации отказоустойчивости можно указать несколько хостов в каждой группе
  • Допустимо совмещать группы на одном хосте

Redis: пояснения и рекомендации по настройке

  • Иерархия: Группа redis_logs_collector является подгруппой redis.
  • Отказоустойчивость: Рекомендуется использовать минимум 2 инстанса для обеспечения стабильной работы.
  • Совместное использование:
    • Допустимо размещать группы redis_logs_collector и redis_mage на одном хосте. В этом случае будет установлен один общий инстанс Redis для обоих компонентов.

Настройка авторизации

Включением/выключением авторизации для записи логов можно управлять флагом. Для этого добавьте в ansible инвентарь переменную:

sage_logs_auth_enabled: false # Или true для включения авторизации
  • Значение по умолчаниюfalse, то есть запись логов возможна без авторизации.

Подробнее с механизмами авторизации и записи логов через Logs Collector можно будет ознакомиться в клиентской документации Sage.

Балансировка трафика

В тестовых (пилотных) средах допускается запись логов напрямую в один инстанс Logs Collector. Для продуктовых инсталляций потребуется обеспечить отказоустойчивость и балансировку нагрузки между несколькими инстансами.

Для отказоустойчивой работы Logs Collector необходимо обеспечить балансировку входящего трафика между хостами группы logs_collector_api.

Параметры для настройки

  • Протокол: HTTP
  • Порт по умолчанию: 8032

Возможная конфигурация внешнего балансировщика (на примере Nginx, но можно использовать любой)

upstream logs_collector_backend {
server logs-collector.host-1.example.com:8032;
server logs-collector.host-2.example.com:8032;
}

server {
listen 80;
server_name logs-collector.sage.example.com;

location / {
proxy_pass http://logs_collector_backend;
}
}

Устаревшие группы

Следующие группы больше не используется с версии Sage 1.12.

  • redis_dtracing

Рекомендуется удалить их из инвентаря.

Переименование переменных

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

Старое имяНовое имя
limits_overridesage_limits_override
elastic_write_queue_sizesage_elastic_write_queue_size
kafka_retention_bytessage_kafka_retention_bytes
kafka_retention_hourssage_kafka_retention_hours
luna_ssh_usernamesage_luna_ssh_username
frost_rw_kafka_compressionsage_frost_rw_kafka_compression
frost_rw_kafka_lingersage_frost_rw_kafka_linger
celestia_blocklistsage_celestia_blocklist

Обновите ваши файлы конфигурации для использования новых имён переменных.

Отказоустойчивая балансировка

В Sage появилась поддержка отказоустойчивой балансировки.

Включить разрешение имён в Docker-сети — требуется, если обновление выполняется без перехода на новую модель балансировки:

sage_enable_nginx_aliases: true

Подробности см. в инструкции по установке Sage, раздел «Обеспечение отказоустойчивости».

Возможная потеря данных трейсинга при обновлении

При обновлении Sage с версии 1.10 до 1.12 может происходить небольшая потеря данных трейсинга, которые в этот момент еще находились в Kafka. Это происходит из-за внутреннего изменения в формате данных, используемых для трейсинга.

Порядок отката до версии 1.11 с версии 1.12

ВНИМАНИЕ!

Процедура отката до версии вызывает downtime в системе алертирования на время проведения процедуры.

Для выполнения процедуры отката необходимо будет использовать 2 контейнера sage-trukk версий 1.12 и 1.11.

  1. Зайдите в sage-trukk версии 1.12, предварительно смонтировав созданный клан, соответствующий выбранному окружению.

  2. Выполните команды source setup.sh и clan, чтобы активировать необходимый клан.

  3. Выполните команду:

    ansible-playbook sage-apps-migrations.yml ${ANSIBLE_ARGS:-} --extra-vars '{"sql_migrations_ids": {"manul": "20260126092107_DbVersion", "pager": "20260124161538_DbVersion"}}'
  4. Зайдите в sage-trukk версии 1.11, предварительно смонтировав клан.

  5. Произвести установку версии 1.11 cогласно инструкции по обновлению.

  6. При установке версии 1.11 этап validate может завершиться ошибкой из-за изменения типа полей в логах компонента Manul. Перед запуском validate необходимо выполнить ролловер индекса OpenSearch logs.prod.sage.manul. Сделать это можно в https://{sage_domain}/luna во вкладке "Index Rollover".