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

Что это и зачем это нужно?

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

Различные параметры приложения могут быть:

• жёстко зашиты в коде (внутри функций / методов) / hardcoded

• вынесены в константы модулей

  • константы намного лучше, чем "магическеские числа" и "магические строки" непосредственно в коде

  • полезно если константы меняются крайне редко, но всё же могут меняться

• вынесены в отдельные конфиг-файлы (файлы, используемые для хранения параметров и настроек приложений).

Зачем нужны: отделение логики программы от настроек:

• Логика программы остаётся в коде, а параметры — в конфигурации.

• Упрощается поддержка, обновления и перенос приложения.

• Параметры легче менять / управлять ими

Почему это важно?

• Гибкость: Меняя файл конфигурации, вы меняете поведение приложения без изменения кода.

• Разные настройки для для разных окружений (development, testing, production).

• Читаемость и простота поддержки: Проще поддерживать проект, если все настройки вынесены в конфиг.

Примеры использования:

• Настройка веб-серверов (nginx, apache)

• Параметры СУБД (MySQL, Postgresql, clickhouse и т.п.)

• Конфигурации микросервисов и т.п.

• 99% сервисов в linux настраиваются через какие-то конфиги.

У конфигурационных файлов два основных назначения:

• Для редактирования руками: чтобы менять настройки приложения напрямую работая с конфигами в текстовом редакторе или с помощью иных инструментов

• Для хранения настроек: интерфейс для работы с настройками реализован в каком-то ином виде (web-интерфейс, мобильный интерфейс, GUI интерфейс на Desktop)

Преимущества настроек через конфиг-файлы (а не иными способами):

1. Независимость от интерфейса:

   • Конфигурационные файлы не зависят от доступности GUI или веб-интерфейса.

   • Настройки можно изменять, даже если приложение не запущено.

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

   • Пример: Приложение упало из-за ошибки конфигурации? Доступа к интерфейсу нет, но файл конфигурации можно отредактировать напрямую.

   • Пример: Работа без сети или с «упавшей» системой

2. Быстрота / простота / гибкость редактирования

   • любой текстовый редактор или иные средства редактирования

3. Возможность автоматизации и скриптового управления

   • Конфиги можно редактировать с помощью скриптов и автоматизированных инструментов (например, sed, awk, jq).

   • Легко автоматизировать развертывание приложений и изменять параметры без участия человека.

4. Множества вариантов доступа к конфигам

   • через ssh / telnet

   • через сетевую файловую систему (NFS, FTP, SMB и т.п.)

   • через системы управления версиями

   • используя любые инструменты работы с файлами (scp и т.п.)

5. Поддержка версионного контроля

   • Конфигурационные файлы можно хранить в системах управления версиями (Git и т.п.)

   • Легко увидеть, кто и когда изменил файл

   • Можно откатиться к предыдущей версии файла, если что-то сломалось.

   • С GUI или веб-интерфейсом такой прозрачности и истории изменений нет (только с помощью специальных журналов или трекеров изменений).

   • Итог: У вас есть история изменений, можно откатиться к рабочей версии, понять, кто внёс изменения.

6. Простое развертывание на нескольких машинах

   • Один и тот же файл конфигурации можно развернуть на нескольких серверах.

   • Конфиг-файлы легко переносить с одного сервера на другой.

   • Упрощается миграция приложений на другие серверы или окружения (dev, test, prod)

   • Пример: Один файл config.prod.yaml можно использовать сразу на 100 серверах с одинаковыми настройками. Веб-интерфейсом настраивать 100 серверов руками — долго и рискованно.

   • Итог: Копируете конфиг на новый сервер и запускаете приложение. Быстро и надёжно.

7. Сложность реализации настроек через GUI/web интерфейс:

   • Конфиги поддерживают вложенные структуры (YAML, JSON, TOML), в т.ч. списки неограниченной длины

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

8. Скорость разработки:

   • Сделать поддержку нового параметра в конфиге — не стоит ничего (просто сослаться на этот параметр)

   • В GUI надо реализовывать поддержку этого параметра, что требует времени

Таки есть и минусы:

• Не может править конфиги тот, кто не имеет физического доступа к файлам;

• Существенно сложнее навесить какое-то адекватное управление доступом (разные права на разные ключи конфигов и т.п.);

• Файловые конфиги нужно раскладывать по нужным серверам/контейнерам (возможно, по многим), что в случае, развесистой микросервисной архитектуры может быть нетривиально.

  • Хотя есть специализированные сервисы для управления конфигами: Ansible, Chef, Puppet и т.п.

Что хранить в конфигурационных файлах?

1. Параметры подключения / credentials

   • К БД: хост, порт, логин, пароль и т.п.

   • URL API-сервисов (тем более могут отличаться production / в test)

   • Учетные данные для внешних сервисов:

     • Различные ключи, пароли, токены

   • Хотя, хранить секреты в конфигах — не всегда хорошая идея, но уж явно лучше, чем напрямую в коде )

2. Переключатели и флаги:

   • Режимы работы (prod, dev, test)

   • Режим отладки (debug) и логгирование (пути к логам, параметры логирования: уровень логирования)

   • Флаги, управляющие бизнес-логикой, включением фич, AB-тестированием и пр.

3. Настройки окружения:

   • Пути к файлам, папкам, логам

   • Временные зоны, региональные настройки (параметры локализации, язык и т.п.)

   • Пути к командам / сервисам / пути поиска для запуска команд ($PATH)

4. Конфигурации модулей:

   • Настройки для библиотек и зависимостей

   • Параметры обработки данных (например, размер пакетов)

5. Конфигурации для devops / CI/CD

   • Параметры для развертывания приложений

     • Параметры для docker и т.п.

   • Секреты и токены для сборки (github_token, aws_access_key и т.п.)

6. Пользовательские настройки

   • Предпочтения пользователя

   • Конфигурации интерфейса (темы, цвета, шрифты и т.п.)

7. Любые константы, которые могут когда-то поменяться

   • Числовые (цены, коэффициенты наценки, и т.п.)

   • Строковые (название компании, промпты для LLM)

Послойные конфиги

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

Зачем нужны послойные конфиги?

1. Гибкость и переопределение значений

   • Один и тот же основной файл конфигурации используется для всех окружений.

   • Локальные изменения можно внести в отдельный файл (например, config.local.yaml), не изменяя основной файл config.yaml.

2. Разделение окружений (dev, test, staging, prod)

   • Основной файл config.yaml содержит общие настройки для всех окружений.

   • Конфиги для разных окружений (например, config.dev.yaml, config.prod.yaml) содержат только различия.

3. Удобство разработки и тестирования

   • Разработчики могут добавлять локальные изменения в локальные конфиги, не затрагивая продакшен.

   • Конфиги для CI/CD могут отличаться от production-конфигов, но включать общие параметры.

4. Избежание дублирования конфигураций

   • В общих конфиг-файлах можно держать базовые значения, а уникальные параметры добавлять “поверх” в других файлах.

Когда использовать послойные конфиги

• Мультиокружения (dev, test, staging, production)

  • CI/CD пайплайны (разделение конфига для сборки, теста и деплоя)

• Локальная разработка (например, разработчики могут создавать config.local.yaml с личными настройками)

• Управление секретами и токенами (основной конфиг не содержит секретов, а файл secrets.yaml добавляет токены)

• Для работы с шаблонами конфигов (например, базовый config.yaml используется как шаблон, а “поверх” добавляются значения окружения)

Как это работает?

1. Базовый слой — файл config.yaml с общими значениями.

2. Средний слой — файл для окружения config.dev.yaml, config.prod.yaml.

3. Локальный слой — локальные изменения разработчика в config.local.yaml или локальные настройки для конкретного сервера

Пример послойной конфигурации (YAML)

config.yaml (базовая конфигурация):

database:
  host: "localhost"
  port: 5432
  username: "default_user"
  password: "default_pass"

logging:
  level: "info"
  file: "/var/log/app.log"

config.prod.yaml (продакшен):

database:
  host: "prod-db.company.com"
  username: "prod_user"
  password: "secure_pass"

config.local.yaml (локальные изменения):

database:
  password: "local_pass"
  port: 5433

logging:
  level: "debug"

Итоговая конфигурация после объединения слоев:

database:
  host: "prod-db.company.com" # Заменено из config.prod.yaml
  port: 5433                  # Заменено из config.local.yaml
  username: "prod_user"       # Заменено из config.prod.yaml
  password: "local_pass"      # Заменено из config.local.yaml

logging:
  level: "debug"              # Заменено из config.local.yaml
  file: "/var/log/app.log"    # Из config.yaml (так как не было замен)

Слияние конфигов с помощью готовых библиотек

Есть ряд готовых библилиотек для слияния структур данных, примеры:

from deepmerge import always_merger
from toolz import merge_with
import pydash

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

from deepmerge import always_merger
from pprint import pprint

base = {
    'database': { 'host': 'localhost', 'port': 5432, 'username': 'admin' },
    'logging': { 'file': 'app.log', 'level': 'info'}
}

override = {
    'database': { 'port': 3306, 'username': 'dev_user', 'password': 'secret' },
    'logging': { 'level': 'debug' }
}

# Используем always_merger для объединения
merged_config = always_merger.merge( base, override )
pprint( merged_config )

Где хранить конфиги?

• Прямо в модулях любого ЯП. (Python и т.п.),

• Специализированные форматы: YAML, JSON, INI, TOML, XML, HCL и др.

• Можно хранить в БД.

В файлах

Возможно хранение в репозитории.
Легко бэкапить.

1. Конфиги прямо в виде модуля любого ЯП

Плюсы:

• самый простой способ, не нужно никаких доп. библиотек и отдельных форматов

• легко делать послойные конфиги

• можно вычислять любые выражения (но это и минус в плане безопасности)

# const.py
API_ID = '21186447'
API_HASH = '1507e2222222221dc6a847dc95b294f36a'

msg_basedir = '/opt/local/var/www/tgmedia/'
tgresources_dir = '/opt/local/var/www/tgresources'
watermarks_samples_dir = os.path.join( tgresources_dir, 'samples' )

advertisement_block_patterns = [
    "#реклама", "Узнать больше", "О рекламодателе",
    r"/\+7[( ]?(?:9|800)/", r"/8[( ]?800/",
]

# myapp.py
import const
print(const.API_ID)

from const import *
print(API_ID) # '21186447'

Послойные конфиги

# const.py
API_ID = '21186448'
API_HASH = '2507edddddd...'

try:
    from myconst import *
except ImportError:
    pass

# myconst.py
API_ID = '21186448'
API_HASH = '2507e3333333...'

# myapp.py
import const
from const import API_HASH
print(const.API_ID) # '21186448'
print(API_HASH) # '2507e3333333...'

2. YAML — YAML Ain't Markup Language

YAML (рекурсивный акроним: «YAML Ain't Markup Language» — «YAML — не язык разметки»).

• отступы из пробелов (символы табуляции не допускаются) используются для обозначения структуры

• комментарии начинаются с символа «решётки» (#), могут начинаться в любом месте строки и продолжаются до конца строки

• списки обозначаются начальным дефисом (-) с одним членом списка на строку, либо члены списка заключаются в квадратные скобки ([ ]) и разделяются запятой и пробелом (, )

• ассоциативные массивы в виде key: value, по одной паре ключ-значение на строку, либо в виде пар, заключённых в { } и разделенных запятой и пробелом (, )

# comment
database:
  host: localhost
  port: 5432 # comment
  username: admin
  password: "admin123"

logging:
  level: info
  file: app.log

modules:
  data_processor:
    batch_size: 100
    retry_attempts: 3
  machine_learning:
    model: "xgboost"
    learning_rate: 0.01

ids: [1, 2, 3, 4, 5]
users:
  - { name: Alice, role: admin }
  - { name: Bob, role: editor }
  - { name: Charlie, role: viewer }

Плюсы:

• Простой и легкочитаемый формат.

• Компактный

• Поддержка сложных структур любой сложности: списки, словари, любая вложенность.

• Поддерживает комментарии.

Минусы: Неоднозначность стандартов, «разночтения» в разных библиотеках, проблемы с безопасностью.

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

  • Можно «не усложнять» и использовать только понятные конструкции, не вызывающие неоднозначной трактовки

• Булевые значения: В YAML 1.1 такие значения, как yes, no, on, off, интерпретировались как булевые литералы. Это создаёт проблемы при парсинге, так как в YAML 1.2 это поведение изменилось, но многие парсеры продолжают поддерживать старые правила

• Неявное преобразование строк в числа: Если строки не заключены в кавычки, они могут быть интерпретированы как числа. Например, версия PostgreSQL 10.23 может быть воспринята как число вместо строки

• Выполнение произвольного кода: YAML поддерживает сериализацию сложных объектов, и при загрузке YAML-файла с помощью небезопасных парсеров (например, yaml.load() в Python) злоумышленники могут внедрить вредоносный код, который будет выполнен при десериализации файла.

  • Однако, можно использовать yaml.safe_load() и будет счастье

Пример чтения:

import yaml

with open("config.yaml", "r", encoding='utf-8') as file:
    config = yaml.safe_load(file)

    print(config["database"]["host"])

Послойные конфиги

Базовый слой:

# config.yaml
database:
  host: localhost
  port: 5432
  username: admin
logging:
  level: info

Второй слой:

# config_local.yaml
database:
  port: 3306
  username: dev_user
  password: secret
logging:
  level: debug

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

from ruamel.yaml import YAML

# Функция для глубокого объединения словарей
def merge_dicts(base, override):
    for key, value in override.items():
        if isinstance(value, dict) and key in base:
            base[key] = merge_dicts(base[key], value)
        else:
            base[key] = value
    return base

# Функция для загрузки YAML
def load_yaml(file_path):
    yaml = YAML(typ="safe")
    with open(file_path, 'r') as file:
        return yaml.load(file)

# Загружаем базовый и локальный конфиг
base_config = load_yaml("config.yaml")
local_config = load_yaml("config_local.yaml")
# Объединяем конфиги
final_config = merge_dicts(base_config, local_config)
# Результат
print("Итоговая конфигурация:")
print(final_config)

Вывод:

{'database':
    {'host': 'localhost',
      'password': 'dev_secret',
      'port': 3306,
      'username': 'dev_user'},
 'logging':
    {'file': 'app.log',
     'level': 'debug'}
}

3. JSON — JavaScript Object Notation

JavaScript Object Notation — текстовый формат обмена данными, основанный на JavaScript. Как и многие другие текстовые форматы, JSON легко читается людьми.

Плюсы:

• Легко читается и поддерживается во всех ЯП.

• Строгий формат

• Лишён недостатков YAML в плане неоднозначности, разночтений и проблем с безопасностью Минусы:

• Не поддерживает комментарии.

• Не слишком удобен для «работы руками» (слишком строгий)

  • Лучше подходит, когда с конфигом не работают напрямую «руками» а есть какой-то другой интерфейс для конфигурирования

• Больше подходит как формат обмена данными нежели для хранения конфигурации (на мой вкус)

{
  "logs": {
    "actions": "/var/log/myservice/action.log",
    "errors": "/var/log/myservice/error.log",
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "username": "user",
    "password": "pass"
  },
  "array": [1, 2, 3, 4, 5]
}

import json

# Считываем конфигурацию из файла
with open('config.json', 'r') as file:
    config = json.load(file)

# Выводим конфигурацию
print(config)

4. INI — Initialization file

INI (Initialization file) — старый формат, популярный в системах Windows и для простых конфигураций.
Приведён больше для коллекции, недели реально рекомендуется.

• Широко распространён, но устаревший.

• Нет формального стандарта — менее строгий, допускает вольности.

• Нет встроенной поддержки вложенности.

  • Подходит только для простых конфигов

• Ограниченные типы данных (только строки)

  • Нужно дополнительно преобразовывать типы данных

• Поддерживает комментарии (; или #).

; hello world
[logs]
actions = /var/log/myservice/action.log
errors = /var/log/myservice/error.log
[database]
host = localhost
port = 5432
username = user
password = pass

import configparser

# Функция для чтения INI-файла
def load_ini_config(file_path):
    config = configparser.ConfigParser()
    config.read(file_path)
    return config

# Загружаем конфигурацию
config = load_ini_config("config.ini")

# Выводим конфигурацию
print(config)

5. TOML

TOML (Tom’s Obvious, Minimal Language) — это современный формат, созданный для хранения настроек и конфигураций, с фокусом на читаемости и строгой структуре.

• Современный и минималистичный формат.

• Легко читается (легче, чем JSON)

• Подходит для сложных структур.

• Строго специфицирован (TOML spec).

  • Строгий, требует точного следования правилам.

• Поддержка типов данных

• Поддерживает вложенные таблицы и массивы таблиц

• Поддерживает комментарии (#)

Поддержка типов данных

• Поддерживает строки, числа, булевы значения, массивы, даты и т.д.

• Не нужно дополнительно преобразовывать типы данных

Пример типов данных:

version = 1.2   # Число
debug = true    # Булево значение
date = 2024-11-19T12:34:56Z  # Дата

Вложенные структуры

[database]
host = "localhost"

[database.credentials]
username = "admin"
password = "secret"

Альтернативная запись вложенных структур:

[database]
host = "localhost"
port = 5432
credentials.username = "admin"
credentials.password = "secret"

Вот как будет выглядеть в python после прочтения:

{
    "database": {
        "host": "localhost",
        "credentials": {
            "username": "admin",
            "password": "secret"
        }
    }
}

Пример работы с конфигом:

# comment
[database]
host = "localhost"
port = 5432

[database.credentials]
username = "admin"
password = "secret"

[logging]
level = "info"
file = "app.log"

import tomllib  # Встроено в Python 3.11+
# import toml # — если Python < 3.11

# Функция для чтения TOML-файла
def load_toml_config(file_path):
    # Открываем в режиме 'rb'
    with open(file_path, "rb") as file:
        return tomllib.load(file)

# Загружаем конфигурацию
config = load_toml_config("config.toml")

# Выводим конфигурацию
print(config)

6. XML

XML — Extensible Markup Language.
Широко используется в старых системах.

Плюсы:

• Поддерживает сложные иерархии, хорошо подходит для структурированных данных.

• Легко выражать отношения и вложенные структуры.

• Валидация структуры: С помощью схем (XSD, DTD и т.п.) можно валидировать структуру XML-файла.

  • Хотя, схемы и инструменты валидация — не только прерогатива XML, для других форматов также есть инструменты, в т.ч. универсальные инструменты, не зависящие от формата

Минусы:

• Избыточен

• Слишком много «свободы» и вариативности способов описания

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

• Сложность в определении схемы (зоопарк схем, их сложно описывать)

• Человеку сложнее читать XML-файлы, особенно если они большие.

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

XML менее подходит, если:

• Конфигурации требуют сложной структуры с отношениями между данными.

• Нужна совместимость со старыми системами или приложениями, которые уже используют XML.

• Требуется валидация структуры (через XML-схемы типа XSD, DTD). XML не подходит, если:

• Конфигурации просты.

• Нужна компактность и читаемость (используйте YAML, JSON или TOML).

Примеры вариативности / неоднозначности описания одних и тех же данных:

<logs>
  <actions>/var/log/myservice/action.log</actions>
  <errors>/var/log/myservice/error.log</errors>
</database>
<database>
  <host>localhost</host>
  <port>5432</port>
  <username>user</username>
  <password>pass</password>
</database>

<logs>
  <log type="actions" path="/var/log/myservice/action.log" />
  <log type="errors" path="/var/log/myservice/error.log" />
</logs>
<database host="localhost" port="5432" username="user" password="pass" />

<log-actions path="/var/log/myservice/action.log" />
<log-errors path="/var/log/myservice/error.log" />
<database>
   <value name="host" val="localhost" />
   <value name="port" val="5432" />
   <value name="username" val="user" />
   <value name="password" val="pass" />
</database>

Пример чтения:

import xmltodict

# Чтение XML-файла и преобразование в словарь
def load_xml_config(file_path):
    with open(file_path, "r") as file:
        # Добавляем временный корневой элемент для корректного парсинга
        xml_with_root = f"{file.read()}"
        return xmltodict.parse(xml_with_root)["root"]

# Пример использования
config = load_xml_config("config.xml")

# Вывод результата
print(config)

7. HCL — HashiCorp Configuration Language

Добавим немного экзотики.

HCL — это декларативный язык, часто используемый в инструментах HashiCorp, таких как Terraform, Consul и Vault. Он поддерживает сложные вложенные структуры и хорошо читается человеком.

# single-line comment
/* multiline comment */
database {
  host = "localhost"
  port = 5432

  credentials {
    username = "admin"
    password = "secret"
  }
}

logging {
  level = "info"
  file = "app.log"
}

servers = [
  {
    name = "server1"
    ip   = "192.168.1.1"
  },
  {
    name = "server2"
    ip   = "192.168.1.2"
  }
]

Отличия / преимущества / особенности:

• Немного короче и немного более интуитивно понятен, чем JSON;

• Поддерживает комментарии;

• Неограниченная вложенность (в отличие от INI).

Пример чтения:

import hcl2

# Функция для загрузки HCL-файла
def load_hcl_config(file_path):
    with open(file_path, "r") as file:
        return hcl2.load(file)

# Пример использования
config = load_hcl_config("config.hcl")

# Вывод результата
print(config)

8. Хранение конфигов в БД

Может иметь смысл для хранения настроек, когда интерфейс для работы с настройками реализован в каком-то ином виде (web или GUI-интерфейс).

Два сценария, когда может иметь смысл:

1. Храним настройки на локальной машине в локальной лайтовой СУБД (например, SQLite)

2. Храним настройки системы на удалённом сервере, если мы можем заходить в систему с разных машин (и хранить настройки локально не имеет смысла). Например корпоративное приложение с доступом с разных терминалов.

Пример простой структуры таблицы для простого хранения параметров конфигурации типа ключ / значение:

CREATE TABLE configurations (
    user_id INTEGER UNIQUE KEY,
    key VARCHAR(32) NOT NULL UNIQUE,
    value TEXT NOT NULL
);

Либо храним конфиг целиком в поле типа JSON.

Лучшие практики / Полезные советы

1. Разделяйте конфигурации по окружениям

   • Могут быть разные среды: development, testing, staging, production

   • Используйте отдельные файлы: config.dev.yaml, config.prod.yaml и т.п..

2. Не сохраняйте секреты: пароли, токены и ключи API в файлах конфигурации

   • По крайней мере не в системе контроля версий

   • По крайней мере не для production ?

   • Интеграция с менеджерами секретов (AWS Secrets Manager, HashiCorp Vault).

3. Минимизируйте количество форматов для конфигов

   • Используйте один формат для всего приложения (например, только YAML или TOML).

4. Версионируйте изменения в конфигурациях

   • Если храните в системе управления версиями — уже хорошо (только не стоит там хранить секреты)

5. Возможность валидации конфигураций:

   • Отдельная утилита или опция командной строки для валидации конфигов

   • С помощью pydantic можно валидировать конфиги при загрузке.

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

• Хорошо иметь возможность валидировать конфиги без запуска приложения

• При хранении конфигов в репозитории — хорошо бы всроить проверку конфигов в CI/CD как один из этапов тестирования

Варианты / уровни проверок:

1. Соответствие синтаксису конкретного формата (валидный YAML / JSON / XML и т.п.)

2. Валидация с помощью схем

3. Проверка согласованности конфига в логике приложения

   • При запуске приложения мы в любом случае читаем / валидируем конфиг

   • При указании специального аргумента ком. сроки проводим только этап чтения / валидации конфига и дальше не идём

Основные элементы схем

• Обязательные и необязательные поля — указывает, какие поля должны присутствовать в конфигурации.

• Типы данных — задаёт тип значения поля (например, int, str, list, dict, bool).

• Допустимые значения — можно ограничивать возможные значения поля (например, level может быть только info, debug, error).

• Вложенные структуры — поддержка вложенных объектов и структур (например, секции database, logging).

• Диапазоны и длина — можно задать диапазон для числовых значений или длину строк (например, пароль должен содержать минимум 8 символов).

• Пользовательские валидаторы — можно создать свои проверки (например, проверка корректности URL или e-mail).

Примеры схем:

JSON Schema

JSON Schema — это стандарт для описания структуры и валидации JSON-документов.

{
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "integer", "minimum": 1024, "maximum": 65535},
        "username": {"type": "string"},
        "password": {"type": "string"}
      },
      "required": ["host", "port"]
    },
    "logging": {
      "type": "object",
      "properties": {
        "level": {"type": "string", "enum": ["debug", "info", "warning", "error"]},
        "file": {"type": "string"}
      }
    }
  },
  "required": ["database", "logging"]
}

XSD (XML Schema Definition) — Схема для XML

Вообще, схем для XML много:

• XSD (XML Schema Definition),

• DTD (Document Type Definition) (устарел),

• Relax NG,

• Schematron.

Пример XML Schema Definition:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="config">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="database">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="host" type="xs:string"/>
              <xs:element name="port" type="xs:integer"/>
              <xs:element name="username" type="xs:string"/>
              <xs:element name="password" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="logging">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="level" type="xs:string"/>
              <xs:element name="file" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Инструменты для проверки схем (примеры)

Для JSON (Проверка по JSON Schema)

• ajv (для JSON Schema)

• jsonschema (Python CLI)

• jtd (для JSON Type Definition)

Примеры запуска:

npx ajv validate -s schema.json -d config.json

jsonschema -i config.json schema.json

YAML (Проверка по JSON Schema или YAML Schema)

• yamllint (синтаксическая проверка YAML)

• ajv (проверка YAML как JSON)

• yamale (валидатор YAML-файлов)

yamllint config.yaml

yamale --schema schema.yaml config.yaml

XML (Проверка по XSD-схеме)

• xmllint (системная утилита для проверки синтаксиса и XSD)

• xmlstarlet (обработка и проверка XML-файлов)

• xmlschema (Python-библиотека для проверки XSD)

xmllint --schema schema.xsd --noout config.xml

xmlstarlet val --xsd schema.xsd config.xml

TOML (Проверка синтаксиса и схемы)

• tq (TOML query)

• toml-validator (валидатор TOML-файлов)

• tomlkit (Python-библиотека)

toml-validator config.toml

npm install -g toml-validator

python3 -c "import tomllib; tomllib.load(open('config.toml', 'rb'))"

HCL (проверка HCL-файлов)

• hcl2 (CLI для обработки HCL-файлов)

• terraform validate (проверка HCL-файлов для Terraform)

hcl2-lint config.hcl

terraform validate

Валидация универсальными валидаторами в python (pydantic, voluptuous)

Pydantic и Voluptuous (можно их считать универсальными валидаторами) — способны валидировать различные типы данных, хранящихся в разных форматах (JSON, YAML, INI, TOML, ENV, XML, HCL и др.).
Они работают не с конкретными файлами, а со структурами данных python (словари, списки, строки, числа и т.д.), которые можно получить из любого формата хранения данных.

Pydantic

• Работает с любым форматом (считанным например из JSON, YAML, TOML, INI, ENV, HCL, XML)

• Поддерживает вложенные структуры (например, словари внутри словарей).

• Валидирует типы данных (int, float, str, bool, list, dict) с помощью type hints.

• Поддерживает пользовательские валидаторы через декораторы @validator.

• Интеграция с FastAPI, что делает его ещё более мощным.

Простое описание схемы:

from pydantic import BaseModel, Field

class DatabaseConfig(BaseModel):
    host: str
    port: int = Field(..., ge=1024, le=65535)  # Порт от 1024 до 65535
    username: str
    password: str

class LoggingConfig(BaseModel):
    level: str
    file: str

class Config(BaseModel):
    database: DatabaseConfig
    logging: LoggingConfig

Более сложное описание схемы с различными ограничениями на значения:

from pydantic import BaseModel, Field, ValidationError

class DatabaseConfig(BaseModel):
    host: str = Field(..., description="Database hostname, required field")
    port: int = Field(..., ge=1024, le=65535, description="Port number (1024-65535)")
    username: str = Field(..., description="Database username")
    password: str = Field(..., min_length=8, description="Database password, min length 8 characters")

class LoggingConfig(BaseModel):
    level: str = Field(..., regex='^(debug|info|warning|error)$', description="Log level (debug, info, warning, error)")
    file: str

class Config(BaseModel):
    database: DatabaseConfig
    logging: LoggingConfig

Валидация конфига и обработка ошибок:

from pydantic import ValidationError

try:
    # Попытка валидации данных с ошибками
    config = Config(**data_with_errors)
except ValidationError as e:
    # Выводим ошибки на stderr
    print("❌ Ошибки валидации конфигурации:")
    print(e.json(indent=4))  # Вывод подробностей об ошибке

Должно быть выведено на экран:

❌ Ошибки валидации конфигурации:
[
    {
        "loc": ["database", "port"],
        "msg": "value is not a valid integer (must be between 1024 and 65535)",
        "type": "value_error.number.not_in_range",
        "ctx": {"limit_value": 1024}
    },
    {
        "loc": ["database", "password"],
        "msg": "ensure this value has at least 8 characters",
        "type": "value_error.any_str.min_length",
        "ctx": {"limit_value": 8}
    },
    {
        "loc": ["logging", "level"],
        "msg": "string does not match regex '^(debug|info|warning|error)$'",
        "type": "value_error.str.regex",
        "ctx": {"pattern": "^(debug|info|warning|error)$"}
    },
    {
        "loc": ["logging", "file"],
        "msg": "str type expected",
        "type": "type_error.str"
    }
]

Как вывести ошибки более «читаемым» способом:

try:
    config = Config(**data_with_errors)
except ValidationError as e:
    print("❌ Ошибки валидации:")
    for error in e.errors():
        loc = " → ".join(str(l) for l in error['loc'])
        msg = error['msg']
        print(f"Поле: {loc}\nОшибка: {msg}\n\n")

Будет выведено:

❌ Ошибки валидации:
Поле: database → port
Ошибка: value is not a valid integer (must be between 1024 and 65535)

Поле: database → password
Ошибка: ensure this value has at least 8 characters

Поле: logging → level
Ошибка: string does not match regex '^(debug|info|warning|error)$'

Поле: logging → file
Ошибка: str type expected

Voluptuous

• Минимум зависимостей: Лёгкая библиотека.

• Поддерживает валидацию словарей, массивов, вложенных структур

• Позволяет задавать кастомные валидаторы (например, проверка длины строки или формата даты).

from voluptuous import Schema, Required, All, Length, Range

# Схема для конфига
schema = Schema({
    'database': {
        'host': str,
        'port': All(int, Range(min=1024, max=65535)),
        'username': str,
        'password': str
    },
    'logging': {
        'level': All(str, Length(min=3, max=10)),
        'file': str
    }
})

# Пример конфига
config = {
    'database': {
        'host': 'localhost',
        'port': 543222,
        'username': 'admin',
        'password': 'thetopsecret'
    },
    'logging': {'level': 'info', 'file': '/var/log/app.log'}
}

# Валидация конфига
try:
    validated_data = schema(config)
    print("✅ Конфигурация валидна!", validated_data)
except Exception as e:
    print(f"❌ Ошибки: {e}")

Pydantic vs Voluptuous — Сравнение

Специальные инструменты

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

• Ansible

• Chef

• Puppet

• HashiCorp Consul

• HashiCorp Vault

• AWS AppConfig

• AWS Systems Manager (SSM) Parameter Store

• HashiCorp Vault

• ArgoCD (GitOps)

Ansible — Автоматическое развертывание и распространение конфигов на серверы.

• Позволяет размещать конфиги на нескольких серверах одновременно.

• Поддерживает динамическую генерацию конфигурационных файлов с помощью Jinja-шаблонов.

• Интеграция с SSH — нет необходимости в установке агентов на серверах.

• Использует Push-подход — изменения отправляются из центрального сервера на управляемые серверы.

Chef — Управление инфраструктурой и конфигурациями.

Chef — это инструмент для автоматизации управления конфигурацией серверов.

• Автоматизация управления конфигурацией серверов.

• Автоматическая доставка конфигураций на серверы.

• Нужен Chef Agent на серверах

• Pull-подход — сервер сам получает инструкции от центрального Chef-сервера.

Puppet — Управление конфигурацией с помощью декларативного подхода.

• Нужен Puppet Agent на всех серверах

• Декларативный подход — описывается “какой должен быть результат”, а не шаги.

• Поддержка Linux и Windows — можно управлять серверами Windows.

• Pull-подход — агенты периодически синхронизируются с сервером.

HashiCorp Consul — централизованное управление конфигурациями и сервисами

• Consul — это распределённое хранилище для управления конфигурациями и сервисами.

• Поддерживает централизованное хранение и автоматическую доставку конфигураций в распределённую среду.

• Автоматическое распространение конфигураций на подключённые серверы.

• Поддержка горячего обновления конфигурации (без перезапуска приложений).

• Мгновенное обнаружение изменений — серверы получают обновления в реальном времени.

• Поддержка Watchers — можно “слушать” изменения конфигурации и реагировать на них.

HashiCorp Vault — система управления секретами

HashiCorp Vault — это система управления секретами, которая обеспечивает безопасное хранение, доступ и управление чувствительными данными, такими как пароли, ключи API, токены и сертификаты.

• Централизованное хранилище секретов

  • Хранит пароли, токены, ключи API, учётные данные баз данных.

  • Доступ к секретам возможен через HTTP API, CLI и клиентские библиотеки.

• Динамическая генерация секретов

  • Vault может динамически создавать временные учётные данные (например, пароли для баз данных) по запросу.

  • Секреты имеют “время жизни” (TTL) и автоматически истекают.

• Аудит и контроль доступа

  • Полный контроль над доступом к секретам с помощью политик ACL.

  • Логи аудита фиксируют каждый запрос к секретам.

• Шифрование и дешифрование данных

  • Vault может шифровать данные для хранения в базе данных или журнале событий.

  • Пример: зашифровать текст до его сохранения в БД.

Статьи

• Вдогонку к предыдущему посту или О разных методах хранения конфигов

• Советы, которые могут спасти Вас от ужасов PyYAML

• Различные конфиги для режима production и режима отладки. Два в одном

• YAML из Ада