Политика совместимости

Обновление

[update.path] Обновление между мажорными версиями гарантируется только с последней минорной версии. Обновление минорной версии может делаться с пропусками.

Пример. Существуют v12.34.0, v12.34.1, v12.34.2, v12.35.0, v12.35.1.

  • Гарантируется:
    • v12.34.2 → v12.35.0,
    • v12.34.2 → v12.35.1,
    • v12.34.0 → v12.34.2.
  • Не гарантируется:
    • v12.34.0 → v12.35.x,
    • v12.34.1 → v12.35.x.

Негарантированные обновления обычно технически возможны, но не тестируются.

[update.migration] Если при обновлении меняется формат настроек, гарантируется их миграция в новый формат с сохранением смысла, если соответствующая логика сохраняется.

Пример. Вплоть до v20.02 ключ MCR задавался как base64 в API и как текст в UI. Начиная с v20.06, ключ задается как hex-строка. При обновлении байты существующих ключей переводятся в новый формат.

Пример: см. раздел «Пороги автодетектирования».

Backend API

[api.format] В пределах мажорной версии гарантируется обратно-совместимый формат запросов.

[api.changelog] Несовместимые изменения описываются в changelog.

Пример: все запросы для v12.34.0 работают с v12.34.1.

Пример: некоторые запросы для v12.34.2 могут не работать в v12.35.0, описание изменений приводится в разделе «Changelog v12.35.0».

Пороги автодетектирования

[detect.migration] Если имена порогов меняются в новой версии, гарантируется, что значения старых порогов будут перенесены в новые пороги при обновлении, кроме случаев, когда старая логика удаляется.

Пример. В версии v12.34 был порог Threshold, при пересечении которого контрмера включалась или выключалась, ему было настроено значение 100. В версии v12.35 контрмера включается по порогу Threshold.On, выключается по Threshold.Off. При обновлении порог Threshold будет удален, вместо него будут созданы Threshold.Off и Threshold.On со одинаковыми значениями 100.

Программы BPF

Бинарный код в объектном файле для работы полагается на бинарный интерфейс (application binary interface, ABI). Нужная версия ABI указывается через имя секции в объектном файле, в коде это делается через макрос (FILTER_V1 задает ABI версии 1). Так как код программы может быть недоступен при обновлении, версия ABI отвязана от версии системы. ABI не меняется без объективных оснований (проблемы безопасности, принципиально новые возможности). Версии ABI несовместимы между собой.

Изменения ABI включают все, из-за чего программа может работать неверно при формально корректном бинарном коде:

  • Удаление функций, в том числе переименование.
  • Изменение сигнатуры функции.
  • Добавление возможных возвращаемых значений функции.
  • Изменение описания типов данных API.
  • Изменение поведения функций с существующими параметрами (не всегда).

Замена зарезервированных полей структуры или параметров функции на значимые при сохранении размера структуры или формата параметра не меняет ABI.

[bpf.abi.compat] Программы для определенной версии ABI работают на любой версии системы, где эта версия ABI поддерживается.

Пример: если v12.34.0, v12.34.1, v12.35.0 поддерживают ABI v1, программа для ABI v1 одинаково работает на любой из этих версий.

[bpf.abi.deprecation] Поддержка версий ABI удаляется только при выходе новых мажорных версий.

Пример: ABI v1, работающая в v12.34.0 не может быть удалена в v12.34.1, только в v12.35.0.