Env-переменные: передача конфигурации приложению

Прямой ответ

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

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    log_level: str = "INFO"
    
    class Config:
        env_prefix = "APP_"

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

Приоритет, проверка и разделение

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

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

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

Разделение по окружениям. Значения разработки, тестирования и продакшена различаются, поэтому окружения разделяются.

Практическое следствие: отсутствие приоритета приводит к неоднозначности, поэтому значение, используемое приложением, не определяется однозначно.

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

Три признака некорректного использования переменных окружения.

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

Отсутствие проверки при запуске. Некорректное значение обнаруживается во время выполнения, поэтому сбой возникает после запуска.

Смешение значений окружений. Значения разработки и продакшена смешиваются, поэтому компрометация одного затрагивает другое.

О 12‑factor подходе — в статье про конфигурацию 12‑factor; о хранении секретов — в статье про секреты в разработке.

Приоритет и разделение по окружениям

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

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

Разделение по окружениям. Значения разработки, тестирования и продакшена различаются, поэтому окружения разделяются.

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

Практическое следствие: отсутствие приоритета приводит к неоднозначности, поэтому значение, используемое приложением, не определяется однозначно.

Практика: настройка переменных окружения

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

2. Проверяйте переменные при запуске. Некорректное значение обнаруживается до начала обработки, поэтому сбой не возникает после запуска.

3. Разделяйте переменные по окружениям. Значения разработки, тестирования и продакшена различаются, поэтому окружения разделяются.

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

5. Фиксируйте источник значения в логе. Источник позволяет определить, откуда получено значение при диагностике.

6. Ограничивайте доступ к переменным продакшена. Доступ к значениям продакшена ограничивается, поэтому изменение выполняется контролируемо.

7. Не храните секреты в переменных разработки. Секреты в переменных разработки попадают в систему контроля версий, поэтому доступ к ним не ограничивается.

Рекомендации:

1. Не храните секреты в переменных разработки. Секреты в переменных попадают в систему контроля версий, поэтому доступ к ним не ограничивается.
2. Учитывайте приоритет при диагностике. Значение, используемое приложением, определяется приоритетом источников.
3. Сопоставляйте переменные с окружением. Значения продакшена отличаются от разработки, поэтому окружения разделяются.
4. Фиксируйте источник значения в ошибке. Источник в записи ошибки позволяет определить, откуда получено некорректное значение.
5. Пересматриваем переменные при изменении окружения. Новое окружение требует разделения значений.

Практический сценарий: значение переменной не применилось

Контекст: изменение переменной окружения не применилось, поэтому приложение использовало старое значение.

1. Диагностика. Проверка показала, что переменная окружения не была задана в окружении запуска. Файл конфигурации содержал старое значение, поэтому оно использовалось вместо нового.
2. Причина. Переменная окружения не была задана, поэтому значение из файла конфигурации использовалось.
3. Действия. (а) Задали переменную окружения в окружении запуска; (б) проверили приоритет источников и убедились, что переменная переопределяет файл; (в) добавили фиксацию источника значения в логе для диагностики; (г) проверили применение значения после задания переменной; (д) разделили переменные по окружениям, чтобы значения не смешивались.
4. Результат. Значение переменной окружения применяется однозначно, поэтому поведение приложения предсказуемо.

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

Практический сценарий: значение переменной не применилось

Контекст: изменение переменной окружения не применилось, поэтому приложение использовало старое значение.

1. Диагностика. Проверка показала, что переменная окружения не была задана в окружении запуска. Файл конфигурации содержал старое значение, поэтому оно использовалось вместо нового.
2. Причина. Переменная окружения не была задана, поэтому значение из файла конфигурации использовалось.
3. Действия. (а) Задали переменную окружения в окружении запуска; (б) проверили приоритет источников и убедились, что переменная переопределяет файл; (в) добавили фиксацию источника значения в логе для диагностики; (г) проверили применение значения после задания переменной; (д) разделили переменные по окружениям, чтобы значения не смешивались.
4. Результат. Значение переменной окружения применяется однозначно, поэтому поведение приложения предсказуемо.

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

FAQ

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

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

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

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

Источники: 12factor.net, pydantic-settings, Kubernetes environment variables — ссылки в шапке.