SFS-004 Описание переменных окружения в приложениях¶

Принимая этот стандарт у нас для пользователей приложения .env-example становится единственнымм источником правды по переменным окружения, то дальше я в каждый проект добавляю pipeline который проверяет на то что в .env-example описаны ВСЕ переменные окружения используемые в коде, а так-же что там описаны ТОЛЬКО те переменные окружения которые используются в коде. Далее при каждом комите пайплайн на разработческо-понятным языком пишет чего ему не хватает в .env-example или что там лишнее.

Таким образом мы всегда будем уверены что .env-example актуален.

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

Сейчас я как инфраструктурщик не могу верить описаниям которые есть и списку переменных окружения которых вижу в документация и в разных .env-ах. Поэтому для меня важно внедрить механизм который будет гарантировать что то что я вижу это реально актуальный описанный список переменных окружения. А также иметь такой список описанных переменных окружения который я могу подтянуть для автоматического парсинга.

Требования:¶

Данил @dapi ¶

Иметь полный список используемых в приложении переменных окружения для понимания как его запустить.
Иметь возможность вручную изменять описание переменных, компоновку документа, разделы. В том числе возможность дополнять описание, добавлять комментарии, без изменения исходного кода ПО.
Иметь примеры использования переменных окружения.
Быть уверенным что все переменные окружения используемые в приложении описаны.
Быть уверенным что в описании нет переменных окружения, которые не используются.
Список переменных окружения иметь в формате удобном для автоматической работы со списком (контроль использования переменных окружения приложений со стороны инфраструктуры). Например .env, .yaml и тп
Минимизировать со стороны разработчика движения по контролю соблюдения данных требований.
Для разработчика иметь файл с примерами переменных окружения которые он может начать использовать при разворачивании проекта с нуля.
Иметь возможность на уровне CI/CD пайплайнов заблокировать выпуск пакета если его описание не соответсвует выше изложенным требованиям.
Иметь один источник знаний об переменных окружения.

Данил @KOTI4chh ¶

Саша @knownout ¶

Саша @AlexanderMint ¶

Предлагаемые решения:¶

Решение 1. .env-example¶

Хранить список переменных окружения с примерами в файле-примере .env-example
Иметь автоматические средства контроля полноты данного списка на уровне CI/CD (github actions). Которые указывают не не хватающие или избыточные переменные окружения.

Преимущества¶

Файл .env-example уже присутсвует во всех проектах. Это типовое решение для примера используемых переменных окружения. Для внедрения не требуется изменения существующего кода.
Таким образом в файл-пример .env-example переменные окружения добавляются разработчиком вместе с описанием и документацией по мере добавления в проект. CI/CD-пайплайн помогает разработчику незабыть это сделать и подсказывает каких переменных окружения не хватает в файле-примере.
Концептуально решение расширяемое на другие языки программирования.
При входе в проект нового разработчика ему не обязательно быть знакомым с этим соглашением, он познакомится с ним через CI/CD в первый же раз добавления новой переменной.

Недостатки¶

env-checker чувствителен к способу использования переменной окружения в проекте и при внедрении нового способа требует адаптации (пару строк)