Конфигурация backend-приложений¶

Требования этого документа применяются к backend-приложениям, API, worker-процессам, consumer-процессам и исполняемым data pipelines. Уровни обязательности определены в корневом README.md.

BE-CONF-001. Версионируемая базовая конфигурация¶

Уровень: MUST

Применяется к: конфигурации приложения

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

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

Обоснование¶

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

Проверка¶

review структуры проекта и pipeline поставки;
проверка запуска одного артефакта с конфигурациями разных окружений;
проверка отсутствия конфигурации, встроенной при сборке.

Исключения¶

Формат выбирает проект; несколько форматов допустимы только при однозначно определённых назначении и порядке их объединения.

BE-CONF-002. Порядок объединения источников¶

Уровень: MUST

Применяется к: загрузке конфигурации

Проект должен объявить закрытый перечень источников конфигурации и их детерминированный порядок приоритета. Изменение порядка должно быть версионируемым изменением конфигурационного контракта.

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

Секретный параметр должен заполняться из одного объявленного механизма доставки на окружение. Если значение одновременно предоставлено несколькими механизмами и приоритет явно не определён проектным контрактом, приложение должно завершить запуск с ошибкой.

Обоснование¶

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

Проверка¶

unit-тест каждого уровня приоритета;
тест точечного переопределения вложенного параметра;
тест одинакового результата при повторном запуске.

Исключения¶

Новый источник допускается после добавления в объявленный перечень и проверки его приоритета.

BE-CONF-003. Переопределение переменными окружения¶

Уровень: MUST

Применяется к: параметрам, переопределяемым переменными окружения

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

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

Обоснование¶

Однозначное отображение позволяет безопасно управлять отдельными параметрами через Docker, Kubernetes и CI/CD.

Проверка¶

contract-тест отображения имён на пути базовой конфигурации;
тест отсутствующего, пустого и некорректного значения;
проверка перечня поддерживаемых переменных окружения.

Исключения¶

Не допускаются для параметров, объявленных переопределяемыми.

BE-CONF-004. Типизация и проверка при старте¶

Уровень: MUST

Применяется к: итоговой конфигурации приложения

Приложение должно до приёма запросов и запуска фоновой обработки проверить:

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

При ошибке приложение должно завершить запуск с ненулевым кодом. Оно не должно молча использовать значение по умолчанию вместо явно переданного, но некорректного значения.

Обоснование¶

Fail-fast предотвращает запуск экземпляра с частично применённой или неверно истолкованной конфигурацией.

Проверка¶

unit-тест схемы конфигурации;
негативные тесты каждого класса ошибок;
интеграционный тест ненулевого кода завершения.

Исключения¶

Неизвестные ключи допускаются только в явно объявленном расширяемом разделе.

BE-CONF-011. Неизвестные переменные окружения¶

Уровень: SHOULD

Применяется к: переменным окружения с объявленным префиксом приложения

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

Обоснование¶

Проверка обнаруживает опечатки, но безусловный отказ может блокировать запуск из-за переменной, управляемой платформой или CI.

Проверка¶

тест неизвестной переменной приложения;
тест разрешённой служебной переменной;
review перечня исключённых имён.

Исключения¶

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

BE-CONF-012. Динамическая конфигурация и feature flags¶

Уровень: MUST

Применяется к: конфигурации backend, изменяющей поведение запущенного процесса без поставки нового артефакта

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

Для каждого feature flag должны быть определены безопасное исходное значение, поведение при недоступном, просроченном или некорректном источнике и способ удаления flag после завершения rollout. Изменение не должно обходить авторизацию, миграцию данных или обязательную проверку публичного контракта.

Обоснование¶

Динамическое изменение является исполняемым входом production-системы и без версии, проверки и отказного поведения создаёт невоспроизводимое состояние.

Проверка¶

contract-тест схемы и атомарного применения версии;
тест недоступного, просроченного и некорректного источника;
проверка аудита изменения и удаления завершённого flag.

Исключения¶

Операционный параметр MAY применяться только после перезапуска, если это явно определено его контрактом и не создаёт частично обновлённого состояния.

BE-CONF-013. Управляемый rollout feature flag¶

Уровень: MUST

Применяется к: feature flag, постепенно включаемому для части операций, пользователей или tenant

Проект должен до rollout определить стабильный ключ распределения, этапы и доли включения, минимальный объём наблюдения, критерии продолжения, остановки и отката. Одинаковый субъект должен сохранять назначенный вариант в пределах контрактного периода; случайное перераспределение при restart запрещено.

Откат flag должен выполняться без нового application artifact и сохранять совместимость данных обеих ветвей. После завершения rollout проект должен удалить flag, неактивную ветвь, временную telemetry и конфигурацию в зафиксированный срок.

Обоснование¶

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

Проверка¶

тест стабильности распределения между restart и экземплярами;
controlled rollout с нарушением критерия остановки;
тест отката после записи данных новой ветвью;
проверка срока и diff удаления flag.

Исключения¶

Одновременное включение для всех MAY использоваться, если постепенный rollout не уменьшает область отказа и rollback остаётся проверяемым.

BE-CONF-005. Секреты вне репозитория и артефакта¶

Уровень: MUST

Применяется к: секретам и аутентификационным данным

Открытые значения секретов запрещено хранить в Git, базовой конфигурации, исходном коде, Dockerfile, container image и других артефактах сборки.

Секрет должен поступать во время выполнения через объявленный проектом механизм доставки из управляемого secret store или изолированного secret input среды исполнения. Механизм должен ограничивать доступ конкретными компонентом и окружением, поддерживать ротацию и не сохранять открытое значение в артефакте.

Зашифрованный secret resource допускается хранить в Git только тогда, когда ключ расшифрования доступен исключительно доверенному контроллеру целевой среды и открытое значение не появляется в pipeline.

Обоснование¶

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

Проверка¶

secret scanning репозитория и container image;
review manifests, Dockerfile и GitLab CI/CD;
проверка источника каждого секретного параметра.

Исключения¶

Не допускаются.

BE-CONF-007. Минимизация доступа к секретам¶

Уровень: MUST

Применяется к: загрузке и использованию секретов

Приложение должно получать только необходимые ему секреты. Доступ secret store и среды запуска должен быть ограничен конкретным сервисом и окружением.

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

Обоснование¶

Минимальные привилегии и область видимости уменьшают последствия компрометации экземпляра или ошибочного диагностического вывода.

Проверка¶

review политик secret store и среды исполнения;
review области видимости секретов в приложении;
тест отсутствия секрета в телеметрии и временных файлах.

Исключения¶

Кэширование в памяти допускается в пределах процесса, если этого требует клиент секретного хранилища или внешней системы.

BE-CONF-008. Безопасная диагностика загруженной конфигурации¶

Уровень: SHOULD

Применяется к: диагностике результата загрузки конфигурации

После успешной проверки конфигурации приложению следует один раз записать структурированное событие configuration.loaded. Событие должно позволять определить версию или fingerprint конфигурации и использованные типы источников без записи открытых значений секретов.

Вывод значений параметров допускается только на уровне DEBUG, по явному allowlist несекретных полей и с ограничением размера. Полный dump конфигурации, environment или неизвестного раздела запрещён. Событие должно соответствовать OBS-LOG-001, OBS-LOG-003 и OBS-LOG-006.

Обоснование¶

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

Проверка¶

интеграционный тест старта с несколькими источниками;
проверка fingerprint, перечня источников и ограничения размера;
controlled secret scanning события;
тест запрета полного dump неизвестного раздела.

Исключения¶

Событие MAY отсутствовать, если среда поставки предоставляет эквивалентное проверяемое сопоставление экземпляра с версией конфигурации.

BE-CONF-010. Сообщения об ошибках конфигурации¶

Уровень: MUST

Применяется к: ошибкам загрузки и проверки конфигурации

Сообщение должно идентифицировать источник, путь параметра и причину ошибки, но не должно содержать открытое значение секретного параметра. Для секретного параметра допустимы только факт отсутствия, тип источника и замаскированное значение.

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

Обоснование¶

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

Проверка¶

негативные тесты отсутствующего и некорректного секрета;
проверка stdout и stderr процесса;
controlled secret scanning сообщений об ошибках.

Исключения¶

Не допускаются.