Advanced Cloud-Native #12-factor #config #backing-services #disposability #dev-prod-parity

12-Factor App Vocabulary

5 exercises — master the precise English vocabulary of the 12-Factor App methodology: environment-based config, backing services, disposability and graceful shutdown, dev/prod parity gaps, and treating logs as event streams.

0 / 5 completed

12-Factor App vocabulary quick reference

Factor III: Config — everything that varies between environments belongs in env vars, never in code
Factor IV: Backing Services — DB, queue, SMTP are attached resources; swap them by changing a URL in config, not code
Factor VI: Processes — stateless, share-nothing; persist state in backing services (DB, cache)
Factor IX: Disposability — fast startup for scale-out; graceful SIGTERM shutdown for zero dropped requests
Factor X: Dev/Prod Parity — same backing services, short deploy cycles, dev = ops; close time, personnel, and backing service gaps
Factor XI: Logs — write to stdout only; let the platform capture, route, and store the stream
Factor XII: Admin Processes — one-off admin tasks (migrations, REPL) run in the same environment as the app, as one-off processes

1 / 5

Factor III: Config — The 12-Factor methodology states: "Config that varies between deploy environments must be stored in environment variables, not in the codebase."

Why does 12-Factor specifically mandate environment variables rather than config files committed to the repository?

The core principle: config that varies per environment must never be committed to version control — not even in .env files that are "not pushed".

The dev/prod config problem that Factor III solves:

❌ Anti-pattern (config in code):
app.config.js:
  database: {
    host: 'localhost',  ← dev DB; what happens in production?
    password: 'dev123' ← committed to Git; leaked in public repos constantly
  }

✓ 12-Factor (config in environment):
app.config.js:
  database: {
    host: process.env.DB_HOST,      ← set per environment
    password: process.env.DB_PASS,  ← set via secrets manager, never in code
  }

Why environment variables specifically (not just config files outside the repo):

Approach	Risk
Config in code	Config is code; wrong environment, leaked secrets, manual changes needed per deployment
Separate config files (not committed)	Language-specific formats; easy to accidentally commit; harder to manage across many services
Environment variables	OS-level; language-agnostic; cannot be committed to Git; standard contract between app and platform (Kubernetes Secrets, AWS Parameter Store, Vault)

Modern implementation in cloud-native deployments:
• Kubernetes: envFrom: secretRef — inject from Kubernetes Secrets
• AWS: Systems Manager Parameter Store / Secrets Manager → Lambda env vars or ECS task definitions
• Vault Agent sidecar: automatically populates environment variables from Vault secrets at pod start
• Never store secrets in ConfigMaps — ConfigMaps are not encrypted at rest; use Secrets

One practical test (12-Factor litmus):
"Could you open-source your codebase right now, without compromising any credentials?" If the answer is no due to config in code, you are violating Factor III.

Key vocabulary:
• Factor III: Config — the 12-Factor principle requiring all environment-specific configuration to be stored in environment variables, not in the codebase
• Environment variable — a key-value pair provided to a process by the operating environment; language-agnostic and cannot be committed to version control
• Secrets management — securely storing, rotating, and injecting credentials using dedicated systems (Vault, AWS Secrets Manager, Kubernetes Secrets)

2 / 5

Factor IV: Backing Services — A 12-Factor application treats its PostgreSQL database, Redis cache, and email sending service as "attached resources, accessed via a URL or locator/credentials stored in config."

What does treating a dependency as a backing service operationally enable?

The backing service principle enforces loose coupling between the application and its dependencies — the application should not care whether it is talking to a local database or a managed cloud service, as long as the connection URL works.

Local vs. third-party backing services — same treatment:

Backing service type	Dev environment	Production environment
Database	`postgres://localhost:5432/myapp`	`postgres://rds.amazonaws.com:5432/myapp`
Cache	`redis://localhost:6379`	`redis://elasticache.amazonaws.com:6379`
Email	`smtp://mailhog:1025` (local catcher)	`smtp://email-smtp.us-east-1.amazonaws.com:587`
Message queue	`amqp://localhost:5672` (local RabbitMQ)	`amqps://b-xxx.mq.amazonaws.com:5671` (Amazon MQ)

What changes between environments: only the URL in the environment variable.
What does not change: application code, build artifact, Dockerfile — the binary deployed to dev and prod is identical.

Backing services and disaster recovery:
During an incident where the primary database fails, switching to a replica is a config change — update DATABASE_URL to point to the read replica and restart the app. No code change, no new deployment pipeline.

What backing services are NOT (common misconception):
File system paths are not backing services — the 12-Factor App treats the local file system as a non-backing-service, ephemeral resource. Persistent data must be stored in a proper backing service (S3, a database).

Key vocabulary:
• Backing service — any service the app consumes over the network as part of its normal operation (database, queue, SMTP, API); treated as an attached resource addressable by URL
• Attached resource — a backing service that can be attached to or detached from the application by changing config without code modification
• Loose coupling — an architecture principle where components depend on abstractions (a database URL) rather than specific implementations (hardcoded localhost)

3 / 5

Factor IX: Disposability — A DevOps engineer adds a SIGTERM handler to the API service before deploying to Kubernetes:

"When the pod receives SIGTERM, the service must stop accepting new connections, finish processing in-flight requests, and exit within 10 seconds."

Which 12-Factor concern is the engineer directly addressing?

Disposability has two equally important halves: fast startup and graceful shutdown.

Disposability in the Kubernetes context:

Kubernetes rolling update:
  1. New pod starts (fast startup → typically <5s for Go/Node, <30s for JVM)
  2. New pod passes readiness probe → added to load balancer
  3. Old pod receives SIGTERM → graceful shutdown
     ├─ Stop accepting new connections (remove from load balancer)
     ├─ Finish in-flight requests (drain period, e.g. 10s)
     ├─ Close database connections cleanly
     └─ Acknowledge queued messages that have been processed
  4. After terminationGracePeriodSeconds → SIGKILL (if still running)

What "fast startup" means in practice:
• Target: <10 seconds from process start to readiness
• Enables: rapid auto-scaling (scale out 20 pods when traffic spikes)
• Enables: fast rollback (new broken version → restart all pods quickly on last-known-good)
• Anti-patterns: 5-minute database migration runs at startup (move to init containers or separate migration job)

Disposability and message consumers:
A worker processing a job queue must:
• On SIGTERM: finish the current job, then ack it and exit (do not abandon mid-processing)
• If using SQS or RabbitMQ: use visibility timeout / ack-only-on-completion to ensure at-most-once or at-least-once delivery semantics

Why the other options are wrong:
• Factor VII (Port Binding) is about the app being self-contained and exporting services via a bound port — not about shutdown behaviour
• Factor VIII (Concurrency) is about scaling via process types (web, worker) — not about graceful shutdown
• Factor VI (Processes) is about stateless, share-nothing process execution — not about SIGTERM handling specifically

Key vocabulary:
• Factor IX: Disposability — 12-Factor principle that processes should be disposable: fast startup and graceful shutdown
• SIGTERM — Unix signal sent by Kubernetes to a container before termination; the application should shut down gracefully when received
• Graceful shutdown — a shutdown sequence where in-flight requests complete and connections are drained cleanly before the process exits
• terminationGracePeriodSeconds — the Kubernetes pod spec field defining how long to wait after SIGTERM before sending SIGKILL (default: 30s)

4 / 5

Factor X: Dev/Prod Parity — A team enforces a strict rule: "All developers must run PostgreSQL locally — SQLite is not permitted even for quick prototyping. The docker-compose.yml includes a postgres container for this reason."

Which specific type of dev/prod parity gap does this rule prevent?

Factor X identifies three types of parity gaps — the backing service gap with databases is the most operationally dangerous.

The three dev/prod parity gaps (Factor X):

Gap type	Example	Impact
Time gap	Developer works on a feature branch for 2 weeks; deploys code that assumes a schema not yet in production	Integration failures at deploy time; long-lived feature branches diverge from main
Personnel gap	"Dev writes it, ops deploys it" — engineers never see their code in production context	Developers unaware of production constraints; "works on my machine" culture
Backing service gap	SQLite in dev, PostgreSQL in production	Production-only bugs that cannot be reproduced locally

Concrete ways SQLite vs PostgreSQL diverges:
• Constraint enforcement — SQLite ignores type affinity mismatches; PostgreSQL enforces strict typing
• AUTOINCREMENT behaviour — SQLite AUTOINCREMENT and PostgreSQL SERIAL/GENERATED behave differently in edge cases
• NULL semantics — NULL != NULL in both, but aggregate functions and ordering differ subtly
• Full-text search — SQLite FTS and PostgreSQL tsvector/tsquery are completely different engines
• JSON operations — SQLite JSON support is limited vs. PostgreSQL's JSONB with GIN indexes
• Concurrent writes — SQLite uses file-level locking; PostgreSQL uses MVCC — write contention behaves completely differently

Tools for local parity without heavy setup:
• Docker Compose with official Postgres image:
docker compose up -d postgres → full PostgreSQL running locally in seconds
• LocalStack for AWS services (DynamoDB, SQS, S3) — match production backing services locally

Key vocabulary:
• Factor X: Dev/Prod Parity — keeping development, staging, and production environments as similar as possible across time, personnel, and backing services
• Backing service gap — the specific parity failure of using a different service implementation (e.g., different database engine or message broker) in development vs. production
• MVCC (Multi-Version Concurrency Control) — PostgreSQL's concurrency model; enables non-blocking reads without the file-level locks SQLite uses

5 / 5

Factor XI: Logs — The logging guidelines state: "The app writes all log output to stdout and stderr, unbuffered. It never opens log files or manages log rotation. The execution environment is responsible for capturing and routing the log stream."

Which 12-Factor principle is this, and what operational benefit does treating logs as event streams provide?

Factor XI separates the concern of log production (the app writes to stdout) from log routing and storage (the platform decides where logs go).

Why applications should not manage their own log files:

Problem with file-based logging	How stdout-based logging solves it
Disk fills up	No disk usage — log stream is consumed by the runtime and forwarded
Log rotation complexity	Not the app's problem; rotation is handled by the log aggregation infrastructure
Log location differs per environment	Same code everywhere; platform routes stdout to whatever backend is configured
Switching log aggregator	Change the Fluentd/Fluent Bit config, not the application code or its dependencies
Container ephemeral filesystem	Logs written to container filesystem are lost when the pod restarts — stdout is captured before that

How the log pipeline works in Kubernetes:

App → writes to stdout
  → container runtime (containerd) captures stdout
  → writes to /var/log/containers/<pod>.log on the node
  → Fluent Bit DaemonSet reads the file
  → parses, enriches (adds pod name, namespace, labels)
  → forwards to Elasticsearch / CloudWatch / Datadog / Splunk

Log levels and structured logging (related best practice):
Logs should be structured (JSON) rather than unstructured text lines — structured stdout enables the aggregation layer to index fields for efficient querying:

{"level":"info","timestamp":"2026-04-11T10:22:00Z","service":"orders","order_id":"ORD-8847","msg":"payment confirmed"}

Key vocabulary:
• Factor XI: Logs — 12-Factor principle treating logs as an ordered stream of time-stamped events written to stdout; the app never manages log files
• Log stream — a continuous sequence of log events produced by a running process; consumed by the platform infrastructure
• Log aggregator — infrastructure (Fluentd, Fluent Bit, Logstash) that collects stdout streams from all pods and routes them to a centralised storage backend
• Structured logging — writing logs as JSON or key-value pairs rather than free-form text, enabling efficient querying and alerting in log aggregation systems