Справочник переменных конфигурации

В этом справочнике приведены переменные для управления конфигурацией Sage.

Подробнее о структуре и формате конфигурационных файлов см. в статье Обзор конфигурации Sage. О том, как внести изменения в конфигурацию, см. в статье Работа с конфигурацией Sage.

Важно

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

Обязательные переменные

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

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

Переменные, определяющие идентификатор каталога конфигурации.

Название переменной	Значение по умолчанию	Описание
sage_clan str	example	Имя каталога конфигурации. Во флейворах сооветствует первому сегменту пути clans/<sage_clan>/.... В Ansible Inventory задается в конфигурационном файле и не участвует в пути
sage_env str	prod	Название окружения: dev, test, prod. Во флейворах соответствует сегменту пути clans/<sage_clan>/<sage_env>/...; в Ansible Inventory — директории inventories/<sage_env>/
sage_datacenter str	—	Идентификатор дата-центра. Во флейворах — тип размещения 1vm, 3vm; в Ansible Inventory — имя дата-центра или группы, задается для каждого дата-центра

Управление доступом

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

Название переменной	Значение по умолчанию	Описание
sage_admin_password str	changeme	Пароль администратора Sage. Является корневым: используется для создания паролей компонентов и админских учетных записей. Рекомендуется шифровать через Ansible Vault
sage_auth_provider str	spirit	Провайдер аутентификации для пользователей Sage. Подробнее см. в разделе Spirit IAM

Доступность и сертификаты

Переменные внешнего доступа к Sage.

Название переменной	Значение по умолчанию	Описание
sage_external_domain str	—	Внешний домен для доступа к Sage. Если не задан, используется FQDN первого хоста из инвентаря. Также см. подробнее в статье Отказоустойчивость и балансировка нагрузки
sage_certificate_source str	self-signed	Источник сертификатов. Допустимые значения: self-signed — установщик генерирует самоподписанные сертификаты; подходит для тестирования и dev-стендов; external — используются сертификаты, выпущенные для указанного внешнего домена. Подробнее см. в статье Сертификаты

Опциональные переменные

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

Общие настройки

Переменные для настройки окружения, в котором развертывается и работает Sage.

Название переменной	Значение по умолчанию	Описание
sage_images_source dict	{'path': '…', 'username': 'json_key', 'password': ''}	Источник образов для компонентов Sage, path по умолчанию — реестр контейнерных образов cr.yandex:443/crp9e7v1gtl8rlvmji4q. Для установки на хостах без доступа в интернет скачайте образы в локальный реестр и укажите в переменной данные для подключения. Значение json_key по умолчанию означает авторизацию по сервисному ключу из файла key.json
sage_internal_subdomain str	internal.	Общий поддомен для внутреннего взаимодействия компонентов Sage. Также используется в сценариях балансировки. Подробнее см. в статье Отказоустойчивость и балансировка нагрузки
sage_limits_override dict	{}	Переопределение лимитов ресурсов для контейнеров Sage. Заполняется для каждого компонента в файле _limits.yml. Для флейворов 1VM и 3VM значения по умолчанию уже заданы. Для других конфигураций подбирайте лимиты под конкретное окружение и предполагаемую нагрузку; изменение лимитов выполняйте по согласованию с технической поддержкой
sage_versions_override dict	{}	Переопределение версий компонентов для закреплении версии при обновлении. Заполняется для нужных компонентов в файле _versions.yml. Используется при миграции или при точечном применении патча. Определяется по указанию технической поддержки или согласно инструкциям в Upgrade Notes

Аутентификация

Переменные аутентификации пользователей через Spirit IAM и Keycloak. Определяют, какие пользователи и каким образом получают доступ к Sage.

Название переменной	Значение по умолчанию	Описание
sage_admin_user str	admin	Имя учетной записи администратора Sage. Создается при установке и используется для входа в администрируемые системы: Grafana, Luna, OpenSearch, Kafka
sage_iam_client_id str	—	Client ID для аутентификации в Spirit IAM. Генерируется автоматически. При изменении конфигурации рекомендуется сохранять значение. Подробнее см. в статье Настройка OIDC-провайдеров
sage_iam_client_secret str	—	Client Secret для аутентификации в Spirit IAM. Генерируется автоматически. При изменении конфигурации рекомендуется сохранять значение. Подробнее см. в статье Настройка OIDC-провайдеров
sage_keycloak_oauth__clientsecret str	—	Client Secret для OAuth-аутентификации в KeyCloak. Генерируется автоматически. При изменении конфигурации рекомендуется сохранять значение. Подробнее см. в статье Настройка OIDC-провайдеров
sage_keycloak_users list	[]	Список пользователей Keycloak, создаваемых при развертывании Sage. По умолчанию переменная не задана, и пользователи не создаются. В типовых шаблонах example указан пользователь sage_admin. Учетными записями можно управлять в интерфейсе после установки Sage, а также выдать роли в Spirit
sage_oidc_provider str	keycloak	OIDC-провайдер по умолчанию для аутентификации в Sage. Подробнее см. в статье Настройка OIDC-провайдеров
sage_spirit_external_domain str	—	Внешний домен Spirit IAM. Если отдельный домен не определен, используется <sage_hostname:9443>, где <sage_hostname> — это FQDN основного домена в инвентаре
sage_spirit_login_webhooks list	[]	Список вебхуков, которые отправляют запрос при входе пользователя в Spirit IAM. Подробнее см. в статье Настройка вебхуков при входе и регистрации пользователя
sage_spirit_oidc_providers list	—	Список внешних OIDC-провайдеров для Spirit IAM. Подробнее см. в статье Настройка OIDC-провайдеров
sage_spirit_registration_webhooks list	[]	Список вебхуков, которые отправляют запрос при регистрации пользователя в Spirit IAM. Подробнее см. в статье Настройка вебхуков при входе и регистрации пользователя

Уведомления

Email

Переменные SMTP для отправки email-уведомлений об алертах. Настраивают канал уведомлений, по которому Sage сообщает о событиях.

Название переменной	Значение по умолчанию	Описание
sage_alerts_email_enabled bool	True	Включить проверку, доставляются ли email-уведомления об алертах. Если True, дашборд Sage Health использует параметры sage_alerts_smtp_* для авторизации на почтовом сервере и отправки тестового сообщения
sage_alerts_smtp_from str	pager_bot@localhost	Email-адрес отправителя уведомлений об алертах
sage_alerts_smtp_host str	localhost	Хост SMTP-сервера для отправки уведомлений
sage_alerts_smtp_login str	" "	Логин для авторизации на SMTP-сервере
sage_alerts_smtp_need_auth bool	False	Включить аутентификацию на SMTP-сервере
sage_alerts_smtp_password str	" "	Пароль для авторизации на SMTP-сервере. Рекомендуется шифровать через Ansible Vault
sage_alerts_smtp_port str	25	Порт SMTP-сервера
sage_alerts_smtp_ssl_options str	StartTlsWhenAvailable	Параметры SSL/TLS для SMTP. Допустимые значения: None — шифрование не используется; StartTlsWhenAvailable — используется STARTTLS, если сервер его поддерживает; StartTlsRequired — STARTTLS обязателен, соединение без него отклоняется; SslRequired — используется SSL/TLS с момента установки соединения.

Вебхуки

Переменные для интеграции Sage с внешними системами через вебхуки.

Подробнее о настройке вебхуков см. в статьях Алертинг с помощью Webhook и Отправка алертов в Telegram.

Название переменной	Значение по умолчанию	Описание
sage_alerts_escalation_webhook_secret_storage str	None	Тип хранилища секретов вебхуков. Допустимые значения: LocalAes — секреты вебхуков хранятся в зашифрованном виде; None — хранение секретов не используется, при создании адреса в интерфейсе Sage блок авторизации не отображается
sage_alerts_webhook_key str	" "	Ключ для расшифровки вебхука. Рекомендуется шифровать через Ansible Vault

Настройки circuit breaker

Переменные механизма circuit breaker, который защищает поиск от перегрузки, отключая неисправный компонент от балансировки.

Название переменной	Значение по умолчанию	Описание
sage_celestia_blocklist list	[]	Список заблокированных запросов для балансировщика поиска. С помощью списка можно явно указать, какие запросы нельзя отправлять в Sage
sage_search_router_cb_break_duration str	00:00:05	Продолжительность, на которую circuit breaker исключает компонент из балансировки
sage_search_router_cb_break_on_status_codes list	[503]	Статус-коды HTTP, при получении которых срабатывает circuit breaker
sage_search_router_cb_failure_ratio float	0.1	Доля ошибочных ответов от общего числа запросов к поиску, при превышении которой срабатывает circuit breaker
sage_search_router_cb_minimum_throughput int	100	Минимальное количество ошибочных запросов за период сэмплирования, при котором срабатывает circuit breaker
sage_search_router_cb_sampling_duration str	00:00:30	Продолжительность сэмплирования запросов к поиску, за который оценивается срабатывание circuit breaker

Логи

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

Название переменной	Значение по умолчанию	Описание
sage_logs_auth_enabled bool	False	Включить аутентификацию для записи логов. Если False, логи принимаются без аутентификации; если True, для записи логов требуется API-ключ Spirit
sage_vector_export_logs_batch_max_bytes int	1048576	Максимальный размер батча в байтах
sage_vector_export_logs_batch_max_events int	100	Максимальное количество событий в батче
sage_vector_export_logs_batch_timeout int	1	Таймаут формирования батча в секундах
sage_vector_export_logs_custom_headers dict	{}	Пользовательские заголовки для HTTP-адреса приемника
sage_vector_export_logs_endpoint_auth_header str	—	Заголовок авторизации для адреса приемника логов
sage_vector_export_logs_endpoint_uri str	—	Адрес (URI) приемника для отправки отфильтрованных логов
sage_vector_export_logs_groups list	[]	Список групп логов для чтения с фильтрами
sage_vector_export_logs_retry_initial_backoff_secs int	1	Начальная задержка перед повторной попыткой отправки логов, в секундах
sage_vector_export_logs_retry_max_duration_secs int	30	Максимальная суммарная продолжительность повторных попыток отправки логов, в секундах

Метрики

Переменные записи и зеркалирования метрик для совместимости с дашбордами Grafana, а также периода хранения данных в кластерах VictoriaMetrics.

Название переменной	Значение по умолчанию	Описание
sage_exporters_container_group_name str	—	Группа Linux, под которой запускается агент сбора метрик Telegraf. Используется в средах, где стандартная группа docker не имеет доступа к сокету Docker: для агента назначается группа с правами на доступ, ее GID подставляется в docker-compose.yml контейнера Telegraf. Например: "r_sage_kc_t_admins"
sage_metrics_allow_client_metrics bool	False	Включить запись метрик алертов для совместимости с дашбордами Grafana. При включении эмулируются Prometheus-алерты: пишутся метрики ALERTS и ALERTS_FOR_STATE. Чтобы включить эмуляцию, задайте True и настройте групповые параметры внутри Sage
sage_metrics_mirror_write_endpoint str	—	Адрес приемника, куда зеркалируются метрики. Если не задан, зеркалирование не выполняется
sage_metric_retention_lts str	1y	Период хранения данных долгосрочного кластера VictoriaMetrics. Формат: <число><единица>, где единица — d (дни), m (месяцы) или y (годы), например, 1y
sage_metric_retention_sts str	30d	Период хранения данных стандартного кластера VictoriaMetrics. Формат: <число><единица>, например 30d (30 дней)

Трассировка

Переменные приема трассировок в Sage.

Название переменной	Значение по умолчанию	Описание
sage_tracing_auth_required bool	False	Включить аутентификацию для приема трассировок. Если False, логи принимаются без аутентификации; если True, для приема требуется API-ключ Spirit
sage_tracing_operation_limit int	300	Максимальное количество операций на один сервис, отображаемых в трейсинге. При запросе показывается только указанное количество операций
sage_tracing_templating_enable bool	True	Включить шаблонизацию высококардинальных операций. При загрузке трейсов шаблонизатор распределяет их по сервисам, откуда пришел трейс. Если в имени сервиса есть цифры, для корректной работы установите значение False

Маскирование

Переменные маскирования чувствительных данных в логах Sage. Подробнее см. в статье Маскирование данных.

Название переменной	Значение по умолчанию	Описание
sage_search_masking_groups list	[]	Группы, к которым применяется маскирование. Логи Sage могут содержать чувствительные данные (например, логины и пароли). Маскирование скрывает такие данные в указанных группах
sage_search_masking_regexes list	[]	Регулярные выражения для маскирования. Чувствительные данные, найденные по регулярным выражениям, заменяются на ***. Формат: [{"name": "Test", "pattern": "\b[A-Z][a-z]+\b"}]
sage_celestia_masking_settings_basemask str		Список паттернов для маскирования: строки, каждая из которых содержит паттерн для замены. Формат: значение вида <что заменить>\n<чем заменить> — каждый паттерн из списка заменяется указанным значением. Пустая строка отключает маскирование

Kafka

Переменные для управления Kafka.

Название переменной	Значение по умолчанию	Описание
sage_frost_rw_kafka_compression str	none	Тип сжатия сообщений, которые Sage отправляет в Kafka. Сжатие применяется на уровне формата сообщения: сериализатор оборачивает данные в выбранный формат перед отправкой. Допустимые значения: none — сжатие не используется; gzip — данные сжимаются в формат gzip; рекомендуется, чтобы снизить объем передаваемых данных и нагрузку на сеть
sage_frost_rw_kafka_linger int	0	Задержка, в течение которой frost_remote_write Kafka-клиент накапливает сообщения перед отправкой, в миллисекундах. Увеличение задержки позволяет снизить снизить число сетевых операций и повысить эффективность сжатия
sage_kafka_retention_bytes int	10737418240	Максимальный размер файла журнала Kafka перед его удалением, в байтах. Сообщения удаляются при превышении лимита, даже если период хранения еще не истек
sage_kafka_retention_hours int	24	Период хранения журнала Kafka, в часах, после которого сообщения удаляются. Сообщения удаляются при достижении этого периода, даже если лимит размера еще не достигнут
sage_kafka_version str	upgrade	Выбор версии Kafka при обновлении Sage. Допустимые значения: upgrade — обновить Kafka до версии из дистрибутива Sage; current — сохранить текущую версию Kafka, не обновляя ее вместе с Sage. Обновление Kafka в этом случае выполняется отдельно с тегом kafka. Подробнее см. в инструкции по обновлению Kafka
sage_kafka_version_rollback bool	—	Флаг отката версии Kafka к предыдущей версии. Если требуется откат, установите флаг True и повторите обновление с тегом kafka. После завершения обновления снимите флаг. Подробнее см. в инструкции по обновлению Kafka

Anomaly Analyzer

Переменные дополнительного модуля Anomaly Analyzer для выявления аномалий. Подробнее см. в статье Anomaly Analyzer.

Название переменной	Значение по умолчанию	Описание
sage_anomaly_caches_max_alerts_count int	1000	Ожидаемое максимальное количество алертов, обрабатываемых Anomaly Analyzer
sage_anomaly_caches_max_series_count int	10000	Ожидаемое максимальное количество временных рядов, обрабатываемых Anomaly Analyzer
sage_anomaly_topic_partition_number int	3	Количество партиций для топиков Anomaly Analyzer
sage_notifier_channels_email_enabled bool	True	Включить канал доставки Email для отправки алертов Sage Notifier. Используется модулем Anomaly Analyzer

Инфраструктура

Переменные инфраструктурных компонентов Sage: межкластерное взаимодействие, OpenSearch, Nginx, Luna, Service Map.

Название переменной	Значение по умолчанию	Описание
sage_crosscluster_jwt_keys list	[]	Список JWT-ключей для межкластерного взаимодействия. Используется в мульти-дата-центр установках. Каждый ключ задается структурой: name имя ключа; kid — идентификатор ключа; value — значение ключа. Рекомендуется шифровать через Ansible Vault
sage_elastic_write_queue_size int	200	Размер очереди OpenSearch для пула потоков записи (index, delete, update, bulk)
sage_enable_nginx_aliases bool	False	Включить алиасы для Nginx. Если True, в Nginx добавляются алиасы для всех сервисов Sage, через которые компоненты взаимодействуют с Nginx в Docker-сети. Подробнее в статье Отказоустойчивость и балансировка нагрузки
sage_luna_ssh_username str	ubuntu	Имя пользователя SSH для Luna. Используется для подключения к серверам с Grafana, необходим доступ к sudo
sage_luna_ssh_privatekey str	—	SSH-ключ для Luna в формате PKCS#8. Используется для подключения к серверам с Grafana, необходим доступ к sudo. Рекомендуется шифровать через Ansible Vault
sage_nginx_enable_proxy_protocol bool	False	Включить поддержку Proxy Protocol для Nginx
sage_remote_datacenters list	[]	Список удаленных дата-центров. Используется в мульти-дата-центр установках, когда Sage развернут на нескольких дата-центрах, которые синхронизируются между собой
sage_service_map_pgsql_sslmode str	—	Тип подключения Service Map к PostgreSQL. Подробнее см. в статье Внешние сервисы и интеграции