The Twelve-Factor App

Манифест, опубликованный Heroku в 2011. Описывает принципы cloud-native приложений. Эти 12 правил — фундамент для Docker, Kubernetes, AWS, любого современного облака.

Если приложение следует 12-factor — оно легко контейнеризуется, масштабируется, деплоится. Если нет — будет постоянная боль.

I. Codebase

Один codebase, отслеживаемый в системе контроля версий, много deploys.

• Один репозиторий = одно приложение
• Несколько микросервисов — несколько репозиториев (или monorepo с чётким разделением)
• Из одного codebase — разные деплои (dev/staging/prod)

II. Dependencies

Явно декларируй и изолируй зависимости.

• Никаких implicit зависимостей от системных библиотек
• requirements.txt, package.json, go.mod — фиксируют ВСЁ
• Lockfiles обязательны (poetry.lock, package-lock.json)
• Контейнер инкапсулирует runtime + deps

III. Config

Конфигурация — в окружении.

Это самый часто нарушаемый принцип.

• Никаких config-prod.yaml в репо
• Конфиг через env vars: DATABASE_URL, REDIS_URL, API_KEY
• В Kubernetes — ConfigMap + Secret через env
• Литмус-тест: можешь ли опубликовать репо в open source прямо сейчас?

IV. Backing services

Backing services — это attached resources.

• БД, кэш, очередь — взаимозаменяемые
• Локальная Postgres и AWS RDS — одинаково для приложения, только URL меняется
• Можно подменить production БД на staging copy без изменений кода

V. Build, release, run

Строго разделяй стадии сборки и запуска.

• Build: code → executable (container image)
• Release: build + config = immutable release
• Run: запуск release в env

Каждый release — immutable, неизменяем. Откат = переключение на старый release.

VI. Processes

Приложение — один или несколько stateless процессов.

• Никаких локальных файлов/sticky sessions
• Состояние — в backing service (БД, кэш, S3)
• Любой запрос может обработать любая instance
• Это даёт scaling, rolling updates, resilience

VII. Port binding

Экспорт сервисов через port binding.

• Приложение само слушает порт (не «развёрнуто в Apache»)
• Self-contained: один процесс = один порт = один сервис
• Это идеально для контейнеров

VIII. Concurrency

Scale out через process model.

• Горизонтальное масштабирование (больше instance), а не вертикальное (больше CPU)
• Разные типы процессов: web, worker, scheduler
• Каждый scale-able независимо
• В K8s = разные Deployment

IX. Disposability

Максимизируй robustness через быстрый старт и graceful shutdown.

• Старт за < 10 секунд (для авто-scaling)
• SIGTERM → graceful shutdown:
  • Перестать принимать новые запросы
  • Завершить in-flight
  • Закрыть соединения
  • Exit
• Готовность к внезапному kill (в K8s — да)

X. Dev/prod parity

Держи dev, staging, production максимально похожими.

• Те же backing services (Postgres локально, не SQLite в dev и Postgres в prod)
• Тот же runtime (Docker = одинаково везде)
• Малый gap во времени между commit и production deploy
• Малый gap в людях — devs участвуют в operations

XI. Logs

Логи — это event streams.

• Приложение пишет в stdout — и всё
• Не открывает лог-файл, не ротирует, не отправляет в SIEM
• Infrastructure (Docker, K8s, Loki, ELK) собирает и направляет
• Структурированные логи (JSON) — best practice

// Хорошо
log.info({user_id: 42, action: "login", duration_ms: 234})

// Плохо
print("User 42 logged in (took 234ms)")

XII. Admin processes

Админ задачи — отдельные one-off процессы.

• Миграции БД — отдельный job, не часть основного приложения
• Тот же codebase, тот же release, та же конфигурация
• В K8s — Jobs / CronJobs

Расширения «15-Factor»

Некоторые добавляют 3 фактора для современных приложений:

13. API first — API определён до реализации (OpenAPI)
14. Telemetry — метрики, трейсы, логи как first-class
15. Authentication and authorization — не отложенная мысль

Чек-лист 12-factor

Источник

12factor.net — оригинальный манифест. Прочитай целиком, 30 минут.