Upgrade Notes v1.12
Установщик Sage
Добавление группы ДЦ
Начиная с версии Sage 1.12 установщик поддерживает 2 формата Ansible Inventory:
- старый ("кланы", содержащие конфигурацию каждого ДЦ)
- новый (единый инвентарь, содержащий информацию о всех ДЦ)
Если 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. Внутри директорий dev, stage, prod каждое из окружений конфигурируется по отдельности, не добавляя ЦОД как отдельную дополнительную вложенность — вместо этого используются Ansible-группы:
---
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:
...
---
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, и перечислить в них все хосты, принадлежащие соответствующему ДЦ:
...
# Here go groups from clans/example/prod/dc1/hosts.yml
...
dc1:
hosts:
kafka1.dc1.example.com:
nginx1.dc1.example.com:
apps1.dc1.example.com:
...
...
# 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
-
Если у вас определены переменные
*elastic_remote_cluster_name, удалите их. -
Если есть, файлы
_secrets_keycloak.ignore.yml,_secrets_spirit.ignore.ymlи_secrets_step.ignore.ymlнеобходимо перенести в директориюinventories/prod/group_vars/sage. -
Для каждого ДЦ надо объявить свою переменную
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-panel | Anodot | Panel | Удален: • для соблюдения требования ИБ • angularjs плагин | |
| briangann-datatable-panel | Grafana Datatable Panel | Panel | Удален: • для соблюдения требования ИБ • angularjs плагин | Перейти на нативную панель Table (не путать с Table (old)) |
| flant-statusmap-panel | Statusmap | Panel | Удален: • плагин не совместим с Grafana 11 • более не поддерживается • для соблюдения требования ИБ • angularjs плагин | Перейти на нативную панель Status history / State timeline |
| gapit-htmlgraphics-panel | HTML graphics | Panel | Удален: • для соблюдения требования ИБ • angularjs плагин | Перейти на нативную панель Canvas Panel / Text |
| grafana-worldmap-panel | Worldmap Panel | Panel | Удален: • плагин более не поддерживается • для соблюдения требования ИБ • angularjs плагин | Перейти на нативную панель Geomap |
| jdbranham-diagram-panel | Diagram | Panel | Удален: • для соблюдения требования ИБ • angularjs плагин | Перейти на нативную панель Canvas Panel |
| marcusolsson-calendar-panel | Business Calendar | Panel | Удален: • для соблюдения требования ИБ | |
| marcusolsson-gantt-panel | Gantt | Panel | Удален: • плагин более не поддерживается • для соблюдения требования ИБ • angularjs плагин | Перейти на нативную панель State timeline |
| vonage-status-panel | Status Panel | Panel | Удален: • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель Stat / Polystat |
| natel-plotly-panel | Natel Plotly Panel | Panel | Удален: • плагин не совместим с Grafana 11 • плагин более не поддерживается • angularjs плагин | |
| agenty-flowcharting-panel | FlowCharting | Panel | Удален: • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель Canvas Panel |
| grafana-piechart-panel | Pie chart (old) | Panel | Удален: • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель Pie chart |
| yesoreyeram-boomtable-panel | Boom Table | Panel | Удален: • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель Table с использованием transformations при необходимости |
| natel-discrete-panel | Discrete | Panel | Удален: • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель State timeline |
| blackmirror1-singlestat-math-panel | Singlestat Math | Panel | Удален: • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель Stat с использованием transformations при необходимости |
| gipong-grafana-groupedbarchart-panel | Grouped Bar Chart | Panel | Удален: • плагин не совместим с Grafana 11 • плагин более не поддерживается • angularjs плагин | Перейти на нативную панель Bar Chart |
| raintank-worldping-app | worldPing | Panel | Удален: • плагин не совместим с Grafana 11 • angularjs плагин • официальный EOL плагина | |
| alexanderzobnin-zabbix-app | Zabbix | Datasource | Удален: • для соблюдения требования ИБ | |
| anodot-datasource | Anodot Datasource | Datasource | Удален: • для соблюдения требования ИБ | |
| camptocamp-prometheus-alertmanager-datasource | Prometheus AlertManager Datasource | Datasource | Удален: • для соблюдения требования ИБ | Перейти на нативный источник данных AlertManager |
| frser-sqlite-datasource | SQLite | Datasource | Удален: • Беканд Grafana использует PostgreSql | Требуется только для Grafana, использующего SQLite |
| simpod-json-datasource | JSON | Datasource | Удален: • для соблюдения требования ИБ | |
| vertamedia-clickhouse-datasource | Altinity plugin for ClickHouse | Datasource | Удален: • для соблюдения требования ИБ | |
| yesoreyeram-infinity-datasource | Infinity | Datasource | Удален: • для соблюдения требования ИБ | |
| sbueringer-consul-datasource | Consul | Datasource | Удален: • для соблюдения требования ИБ • плагин более не поддерживается | Перейти на нативный источник данных Prometheus для сбора метрик (через эндпоинт /agent/metrics) |
Процедура обновления до Grafana v11
-
Сделать резервную копию базы данных 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 -
Подготовить окружение:
- в
group_vars/all/grafana.ymlпараметруgrafana_version_variantприсвоить значениеgrafana_11 - в
group_vars/all/_versions.ymlпараметруgrafana_versionприсвоить значениеrelease-a78522620
- в
-
Развернуть Grafana v11 поверх Grafana v9 командой:
ansible-playbook sage-setup.yml --diff --tags=reload_grafana --skip-tags always -
Проверить, что Grafana работает корректно и не возникает проблем с дашбордами.
Процедура отката до Grafana v9
-
Подготовить окружение:
- в
group_vars/all/grafana.ymlпараметруgrafana_version_variantприсвоить значениеgrafana_9 - в
group_vars/all/_versions.ymlпараметруgrafana_versionприсвоить значениеrelease-av16
- в
-
Остановить контейнер Grafana.
-
Восстановить базу данных 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'; -
Развернуть 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_override | sage_limits_override |
elastic_write_queue_size | sage_elastic_write_queue_size |
kafka_retention_bytes | sage_kafka_retention_bytes |
kafka_retention_hours | sage_kafka_retention_hours |
luna_ssh_username | sage_luna_ssh_username |
frost_rw_kafka_compression | sage_frost_rw_kafka_compression |
frost_rw_kafka_linger | sage_frost_rw_kafka_linger |
celestia_blocklist | sage_celestia_blocklist |
Обновите ваши файлы конфигурации для использования новых имён переменных.
Отказоустойчивая балансировка
В Sage появилась поддержка отказоустойчивой балансировки.
Включить разрешение имён в Docker-сети — требуется, если обновление выполняется без перехода на новую модель балансировки:
sage_enable_nginx_aliases: true
Подробности см. в инструкции по установке Sage, раздел «Обеспечение отказоустойчивости».