feature_flags

В рамках классического подхода feature toggling проект YDB реализует механизм фича-флагов.

Фича-флаги — настройки, которые включают или отключают отдельные возможности YDB. Они позволяют включать новую функциональность поэтапно: её код уже может присутствовать в установленной версии YDB, а сама функциональность ещё недоступна пользователям.

Кто переключает фича-флаги

Переключать фича-флаги может владелец функциональности, знакомый с её внутренней реализацией. Переключение — сложный процесс: необходимо учитывать состояние кластера, зависимости между возможностями и совместимость версий и форматов данных.

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

Экспериментальная функциональность

Почему флаг может быть выключен

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

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

Наличие описания возможности в документации или её кода в релизе ещё не означает, что она включена на кластере вашей базы.

Чем опасно включение экспериментальной функциональности

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

• ошибкам при выполнении запросов или нестабильной работе кластера;
• снижению производительности;
• записи данных в формате, который не поддерживается предыдущей версией YDB.

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

Не включайте экспериментальную функциональность в production-кластерах. Для проверки используйте отдельный тестовый кластер с данными, которые не жалко потерять.

Как узнать, доступна ли функциональность

При проверке доступности учитывайте установленную версию YDB и конфигурацию кластера.

1. Прочитайте документацию нужной версии и release notes. Проверьте ограничения функциональности и указания на её экспериментальный статус.
2. Сгенерируйте конечную конфигурацию для узлов, которые обслуживают нужную базу данных, и проверьте значение соответствующего флага. Описание флагов приведено в справочнике конфигурации.

Значение флага по умолчанию определяется кодом соответствующей версии YDB. В конфигурации кластера значение может отличаться от значения по умолчанию. Поэтому справочник флагов не заменяет проверку фактической доступности на вашем кластере.

Как функциональность становится общедоступной

Когда экспериментальная функциональность готова к общему использованию, её флаг включают по умолчанию в соответствующей версии YDB. Из документации этой версии убирают предупреждение об экспериментальном статусе, а в release notes появляется запись о доступности функциональности.

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

Настройка флагов

Секция feature_flags включает или отключает отдельные возможности YDB в основной конфигурации кластера. С помощью селекторов динамической конфигурации можно переопределить флаги для отдельных баз данных или групп узлов. Чтобы включить возможность, установите соответствующий фича-флаг в значение true. Например, для включения поддержки автопартиционирования топиков в CDC добавьте следующие строки в конфигурацию:

feature_flags:
  enable_topic_autopartitioning_for_cdc: true

Функциональные флаги