vault

12-Factor App Methodology

34 min read

12-Factor App Methodology

The Twelve-Factor App methodology is a set of twelve conventions for building software-as-a-service (SaaS) applications that are portable across cloud platforms, scalable horizontally, and operationally consistent across development, staging, and production environments. It was authored by Adam Wiggins at Heroku in 2011 (refined through 2012 and posted at https://12factor.net) as a distillation of patterns Heroku had observed across thousands of customer applications running on its platform. The methodology pre-dates the term “cloud-native” by several years but encodes nearly every assumption that modern cloud-native infrastructure (Kubernetes, AWS Elastic Container Service, Cloud Run, Heroku, Fly.io, Render, et al.) makes about the apps it runs. A 12-factor application can be picked up and dropped into any compliant platform with at most a handful of configuration changes; an application that violates several factors typically cannot be containerized or autoscaled without significant rework. The methodology is not a style (it does not say “use microservices”) and is not a framework (it ships no code); it is a set of operational conventions that any application — monolithic or microservice, Java or Go or Python — should satisfy to be cloud-portable. This note covers the twelve factors with their original wording, the engineering rationale for each one, the common violations and their consequences, the Beyond the Twelve-Factor App (Hoffman 2016) extensions that bring the count to fifteen, and the role of the methodology in modern interview discussions.

1. Origin and Why the Methodology Exists

In 2007 Heroku launched as a Platform-as-a-Service (PaaS) for Ruby web applications. Its core proposition was that a developer could git push heroku master and have a running web app reachable on the public internet — no server provisioning, no Apache configuration, no manual deployment steps. By 2011 Heroku had run thousands of customer applications and had observed which apps thrived on the platform and which apps fought it. The apps that thrived shared a set of operational assumptions; the apps that struggled violated those assumptions in predictable ways.

Adam Wiggins, one of Heroku’s co-founders and engineers, captured those assumptions as a numbered list and published them at 12factor.net in 2011. The numbering and the rhythm of “factor” terminology was inspired partly by Geoffrey Moore’s Crossing the Chasm style of business writing and partly by enumeration patterns common in IETF Best Current Practice documents. The list is opinionated and prescriptive — each factor names a single operational invariant — and the document is short (a few pages per factor). It became influential for three reasons:

  1. It was timely. AWS EC2 was three years old, the term DevOps was three years old, Docker was two years away, and Kubernetes was four years away. The industry was starting to understand cloud deployment but had no shared vocabulary for the operational requirements of an app that wanted to run in that environment. The 12-factor list provided that vocabulary just before it was needed.
  2. It was vendor-neutral. Wiggins explicitly framed the factors as platform-portable — applicable to Heroku, AWS, Engine Yard, dotCloud, or self-hosted. This was important because adopting the factors did not lock you into Heroku.
  3. It was operationally grounded. Each factor reflected a real failure mode Heroku had seen, not an abstract architectural preference. The “Config in environment” factor existed because Heroku had seen apps with database passwords hard-coded into git repositories, the “Stateless processes” factor existed because Heroku had seen apps that crashed when scaled horizontally, etc.

The methodology has been revised periodically — the canonical version is the one currently posted at 12factor.net — and a 2016 Pivotal-published book by Kevin Hoffman (Beyond the Twelve-Factor App) extended it with three additional factors aimed at deeper cloud-native maturity. Subsequent platforms — Cloud Foundry, Kubernetes, Docker Swarm, Apache Mesos, AWS ECS, Google Cloud Run, Azure Container Apps, Fly.io, Railway, Render — have all in effect required compliance with most of the factors. The Cloud Native Computing Foundation’s working definition of “cloud-native” overlaps the 12-factor list almost completely. The methodology is now the de facto baseline for what an application running on any modern container orchestrator is expected to look like.

2. The Twelve Factors — In Order

The 12-factor list is intentionally numbered and ordered, with the early factors being foundational (they enable the later factors). Each factor has a one-sentence form and a short (one to two paragraphs) original text on 12factor.net. This section covers each factor in 1–2 paragraphs of explanation followed by the “why” — the engineering rationale and the common violation pattern.

Factor 1: Codebase — One Codebase Tracked in Revision Control, Many Deploys

Statement. A 12-factor app is always tracked in a version control system (typically Git). There is exactly one codebase per app. The same codebase is deployed to multiple environments: development, staging, production, with each deploy running a different version (typically a different commit) of the codebase but always from the same source-of-truth repository.

Why this matters. If multiple codebases produce a single app (e.g., one codebase for production, a separately-maintained codebase for development), they will inevitably drift. Bug fixes will land in one but not the other; environment-specific code paths will multiply; the app’s behavior will become unpredictable as deploys swap between codebases. Conversely, if a single codebase produces multiple apps (e.g., one repo containing two distinct services that share a lib/ directory), the apps’ release lifecycles entangle — you cannot release one without the other unless you discipline the build to produce them independently.

The factor is conceptually straightforward but is violated all the time. The most common violation is the “shared library checked into multiple service repos” pattern, where the supposedly-shared library is forked into multiple repos and drifts. The fix is to publish the shared library as a versioned artifact (npm package, Maven artifact, PyPI wheel) and have each app depend on a specific version.

The factor also implicitly requires that production deploy from the same codebase as staging — no “production hotfix” applied directly to the production server without going through the codebase. This is why every modern CI/CD pipeline insists that all production changes go through the codebase first.

Factor 2: Dependencies — Explicitly Declare and Isolate Dependencies

Statement. A 12-factor app never relies on the implicit existence of system-wide packages. Dependencies are declared completely and explicitly in a manifest (e.g., requirements.txt, Gemfile, package.json, pom.xml, go.mod, Cargo.toml) and isolated from the surrounding system (via a virtualenv, bundle, container image, or equivalent).

Why this matters. “Implicit dependency on the system” is the canonical “works on my machine” failure. A Ruby app that uses curl via shell-out depends on curl being installed; if production servers don’t have curl, the app fails. Worse, it might appear to work because some default fallback path masks the missing dependency, until a feature triggers it. Explicit dependency declaration plus dependency isolation makes the app self-contained: deploying the app means deploying the codebase plus the manifest, and the platform installs everything from there.

This factor is what containers — Docker, OCI images — were built to enforce. A Dockerfile is, conceptually, a fully explicit dependency manifest plus an isolation envelope. A 12-factor app is “naturally containerizable”; an app that violates this factor (e.g., assumes ImageMagick is on the system, or that a specific NSS library is present) typically cannot be containerized without first being modified to bring those dependencies inside the manifest.

The original factor pre-dates Docker (Docker first appeared in 2013, two years after the 12-factor doc). The intent in 2011 was that language-specific dependency tools (Bundler for Ruby, virtualenv + pip for Python, Maven for Java) would handle the isolation. Containers later made the isolation more thorough and language-agnostic. Both fulfill the factor.

Factor 3: Config — Store Config in the Environment

Statement. Configuration that varies between deploys (development, staging, production) — database URLs, API keys, feature flags, log verbosity — must be stored in environment variables, not in code or in committed config files.

Why this matters. This is the factor with the most engineering rationale and the most pushback. The original 12-factor argument was:

  1. Environment variables are language-agnostic. Every modern OS and runtime exposes them. A Ruby app, a Python app, and a Java app on the same platform can all consume environment variables with no per-language adapter.
  2. Environment variables are platform-portable. Heroku, AWS, Kubernetes, Docker Compose, your laptop’s shell — all set environment variables in the same way (the API differs, but the consumed result is the same).
  3. Environment variables are external to the codebase, so credentials are never accidentally committed to git. (The infamous “I committed my AWS keys to GitHub and got billed $50,000” failure mode is prevented by this factor.)
  4. Environment variables make it clear what is per-deploy versus per-environment. The codebase has no per-environment branches.

Common pushback: environment variables are a global namespace; they don’t support nested data; they don’t have types. The Wiggins position is that this is a feature: configuration should be flat, simple, and readable, not a nested DSL that grows its own complexity.

The most common violation is per-environment config files committed to the repo (config/development.yml, config/production.yml). This works initially but breaks down: the production secrets either get committed (bad) or the production config file gets out-of-sync from the staging config file (worse). The 12-factor fix is “one codebase, environment-variable-driven config; all secrets external to the codebase.”

Modern compromises: many teams use a tool like dotenv or direnv to populate environment variables locally and a secrets manager (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets) to populate them in production. The factor is satisfied: at runtime, the app reads from os.environ and doesn’t know or care how the variables got there.

Factor 4: Backing Services — Treat Backing Services as Attached Resources

Statement. A backing service is any service the app consumes over the network — databases (PostgreSQL, MySQL, Redis), message brokers (Kafka, RabbitMQ), caching layers (Memcached), email services (SendGrid, Postmark), object stores (S3, GCS), payment processors (Stripe). The 12-factor app makes no distinction between local backing services (a Postgres instance on the same machine) and third-party backing services (an external SaaS API). All are accessed via URL/credentials in environment variables (per Factor 3).

Why this matters. The factor’s specific operational claim is that swapping a backing service should require only a configuration change, not a code change. If the production Postgres database fails and you need to attach a new one, the app’s deploy should work by changing the DATABASE_URL environment variable; no code redeploy. If you migrate from local Memcached to Amazon ElastiCache, you change the CACHE_URL; the code is unchanged.

The mechanism: the app has no opinions about where the backing service runs. It only consumes the URL/credentials. Any code that special-cases “is this localhost?” violates the factor; any code that assumes the database is on the same machine violates the factor; any hard-coded port number or hostname violates the factor.

The factor enables several operational patterns:

  • Blue-green deploys with a fresh database attached.
  • Service migration — moving from self-hosted Postgres to RDS to Aurora to a Postgres-compatible cloud-native DB — without code change.
  • Environment isolation — staging uses a different database from production with the same code.

Violations: code that hard-codes connection strings, code that decides between local-vs-remote based on some environment-variable-of-Booleans, code that opens local-Unix-socket connections.

Factor 5: Build, Release, Run — Strictly Separate Build and Run Stages

Statement. The deployment process has three distinct stages: build (compile the codebase + dependencies into an executable bundle), release (combine the build with environment config into an immutable release artifact, tagged with a release ID), and run (execute the release in the runtime environment). These stages are strictly separated; runtime cannot modify the build, and the build cannot consume runtime config.

Why this matters. If the build and run stages are entangled — for example, if the runtime container compiles its own code on startup, or if the app modifies its own files to apply runtime config — then the running app is not a deterministic image of the codebase + config. Two replicas of the same release could end up in different states. Rollback becomes messy: which file state are you rolling back to?

The 12-factor model: build produces an immutable artifact (today, almost always a container image, in 2011 it was a “slug” or a tarball). Release combines that artifact with a config snapshot to produce a tagged release (e.g., release-3742). Runtime takes a release and runs it. Rollbacks are “release” operations: pick a previous release ID and run it again. No file-system mutation is part of the running app’s lifecycle.

This factor underlies the whole CI/CD discipline. The CI pipeline is the build stage; the CD pipeline is the release stage; the orchestrator’s kubectl apply or heroku release:create is the run stage. Most modern pipelines satisfy this factor by construction. The failure mode this factor prevents — “the production server’s filesystem has been modified by an SSH session and we don’t know how to reproduce it” — is rare enough now that the factor feels obvious, but it was a real pain in 2011.

Factor 6: Processes — Execute the App as One or More Stateless Processes

Statement. The app is executed as one or more processes. Each process is stateless and share-nothing — any data that needs to persist beyond a single request must be stored in a stateful backing service (database, cache, object store). The local filesystem and the in-memory state of the process are transient; they may be wiped at any time.

Why this matters. This is the most-often-violated factor and the most-asked-about in interviews. The implication is that horizontal scaling is trivial — to handle more load, just start more processes. They share nothing, so adding one more contributes one more capacity unit’s worth of throughput. Crashes and restarts are non-disruptive — if a process dies, the orchestrator just starts another one, and any in-flight request can be retried (idempotently).

The common violations:

  • Storing user session state in process memory. This means a user’s request must always go to the same process (sticky sessions). Horizontal scaling and failover both break unless the load balancer is sticky. The fix: store session state in Redis, Memcached, or signed cookies.
  • Caching data in process memory without invalidation. Two replicas have two different caches; consistency suffers. The fix: shared cache (Redis), or accept eventual consistency with explicit TTLs.
  • Writing temp files to the local filesystem and assuming they persist. Containers may have ephemeral storage; processes may be killed and restarted. The fix: write to S3 / GCS / object store; treat local disk as transient.
  • Long-lived in-process schedulers. A cron-like loop running inside the app process. If the process dies, the schedule stops. The fix: external scheduler (Kubernetes CronJob, Cloud Scheduler, AWS EventBridge).

The factor does not say the app cannot have state — it says the state cannot live in the process. State lives in backing services. A 12-factor stateful service is one whose state is in a backing database, not on the local disk.

This factor is the structural enabler of Factor 8 (Concurrency) and Factor 9 (Disposability). Without statelessness, neither works.

Factor 7: Port Binding — Export Services via Port Binding

Statement. The app is self-contained: it does not require an external web server (Apache, Nginx, IIS) to be its host process. Instead, the app itself binds to a port and serves HTTP (or other protocols) directly. The port is specified via environment variable. The platform’s load balancer or reverse proxy routes external traffic to the app’s bound port.

Why this matters. The pre-12-factor model (especially in PHP-Apache, Java-Tomcat, or Java-WAR-deployed-to-WebSphere setups) was: the app is a plugin in some external server. To deploy the app, you copy a WAR file into a Tomcat directory; Tomcat is the long-running process; the app is just configuration to Tomcat. This model means the platform provides the web server and the app is a passenger.

The 12-factor model inverts this: the app embeds its own web server (e.g., Tornado, Gunicorn, Tomcat-as-library, Netty, Express). The app process listens on a port; the platform routes traffic to that port. Now the app and its web server are deployed together as one unit; there is no external “host” environment to configure. The deployment artifact is the app and everything it needs.

The factor extends naturally to non-HTTP protocols. A 12-factor service that exposes gRPC binds to a port and serves gRPC; one that processes background jobs from a queue does not bind to a port at all (and is fine — the factor says “if you have a network-facing service, expose it via port binding,” not “every service must bind to a port”).

The downstream consequence: the app can be both a service and a consumer. A 12-factor app can call other 12-factor apps as backing services (per Factor 4) by hitting their ports. There is no architectural distinction between “app” and “service” — they are the same kind of thing.

Factor 8: Concurrency — Scale Out via the Process Model

Statement. The app’s processes are first-class units of work. Different process types (web, worker, clock, etc.) handle different workloads. To scale, run more processes. The Unix process model — fork, exec, parent/child, signals — is the underlying primitive.

Why this matters. The factor is specific about the unit of scaling: it is the process, not the thread. (Threads are fine inside a process for in-process concurrency, but the unit of horizontal scaling is the process.) The reason: processes are isolated, share-nothing (per Factor 6), and crash-safe; threads share an address space and can corrupt each other.

The factor also names a process type taxonomy: web processes handle HTTP requests, worker processes consume from queues, clock processes run scheduled jobs. Each type scales independently. The original Heroku Procfile (a file declaring process types and their command lines) is the canonical implementation. Kubernetes’ Deployment + Job + CronJob are the modern equivalents — different controller types for different process types, each independently scalable.

The opposite pattern (which the factor rejects): one process that does everything via internal threads or async event loops. That single process becomes the unit of scaling, and you have to scale up the whole heterogeneous workload together. The 12-factor model says: split by process type, scale each type independently.

Factor 9: Disposability — Maximize Robustness with Fast Startup and Graceful Shutdown

Statement. Processes can be started or stopped at a moment’s notice. Startup should be fast (seconds, not minutes). Shutdown should be graceful — the process catches SIGTERM, finishes any in-flight requests, and exits cleanly. Sudden termination (SIGKILL, machine crash) should also be safe — the system should be designed so that a process killed mid-request does not corrupt state.

Why this matters. Modern orchestrators (Kubernetes, AWS ECS, Cloud Run) start and stop processes constantly: rolling updates, autoscaling, node replacement, spot-instance pre-emption. If the process takes 5 minutes to start up, every rolling update is slow; every autoscaling event lags; every node failure leaves capacity short for minutes. If the process does not handle SIGTERM, every shutdown drops in-flight requests; users see 502 errors during routine deploys.

Practical implementations:

  • Fast startup: avoid loading large state on startup; use lazy initialization; pre-warm in a separate readiness check rather than blocking startup.
  • Graceful shutdown: register a SIGTERM handler that closes the listener (so no new requests arrive), waits for in-flight requests to complete (up to a timeout), then exits.
  • Crash safety: use database transactions and idempotent operations so that a process killed mid-write either rolls back or is safely retried.

This factor is what makes Kubernetes’ terminationGracePeriodSeconds work: when the orchestrator wants to kill a pod, it sends SIGTERM, waits the grace period, then sends SIGKILL. A 12-factor app uses the grace period correctly.

Factor 10: Dev/Prod Parity — Keep Development, Staging, and Production as Similar as Possible

Statement. The gaps between development, staging, and production should be minimized along three axes: time gap (deploy frequently, so dev’s code is always close to prod’s), personnel gap (developers should be involved in deploys, not handed off to a separate ops team), tools gap (use the same backing services in dev as in prod — same Postgres, same Redis, not SQLite-in-dev-and-Postgres-in-prod).

Why this matters. Every gap between dev and prod is a place where bugs hide. SQLite-in-dev-and-Postgres-in-prod misses Postgres-specific behavior (different SQL dialect, different transaction semantics). A 6-month deploy cadence means devs lose context on the code by the time it ships. A separate ops team means developers don’t experience their own production failures.

The factor pushes toward containerized local development (the same Docker image runs in dev as in prod), frequent deploys (continuous deployment, with code shipping minutes after merge), and DevOps (developers responsible for production). All three were aspirational in 2011 and are now industry-standard.

The factor is where the methodology connects most directly to the modern DevOps movement (Patrick Debois coined “DevOps” in 2009; the 12-factor doc launched in 2011). Forsgren, Humble, & Kim’s Accelerate (2018) shows that the metrics most predictive of high-performing engineering organizations — deploy frequency, lead time, mean time to restore — are exactly the dev/prod parity metrics.

Factor 11: Logs — Treat Logs as Event Streams

Statement. A 12-factor app does not concern itself with the routing or storage of its logs. It writes log events to stdout as a sequence of newline-delimited time-ordered messages. The execution environment captures that stream, routes it, indexes it, archives it. The app never writes to a log file; the app never rotates a log; the app never tries to email logs.

Why this matters. The pre-12-factor pattern — apps managing their own log files, with their own log-rotation libraries, their own size limits — is fragile. A misconfigured rotation fills the disk; an unrotated log fills the disk; logs end up in language-specific formats that aren’t searchable; logs end up on the local filesystem where they’re lost when the process is recycled. Each of these has been a real outage cause.

The 12-factor model: the app writes to stdout. Period. Some external process (a sidecar, the container runtime, a log shipper like Fluent Bit, Vector, or the platform’s built-in collector) captures stdout, parses it (often with structured-log formats like JSON), and routes it to a centralized aggregator (Elasticsearch, Splunk, Datadog, CloudWatch). The app does not know or care.

This factor is the most often misunderstood. Many practitioners read “treat logs as event streams” and adopt only the output channel part — “write to stdout” — while ignoring the event stream part. The factor’s deeper intent is that logs are an event stream: each line is a discrete, time-ordered, structured event. Modern interpretations push for structured logging (every log line is a JSON object with consistent fields like timestamp, level, service, trace_id, message, plus arbitrary structured fields) precisely so the stream can be queried, indexed, and joined with other event streams (metrics, traces, business events). A pile of unstructured stdout text is output, not an event stream.

Some practitioners further push for treating logs as the origin of metrics and traces — a single event-stream pipeline produces all three (logs, metrics, traces) from a unified observability layer. This is the modern “observability” interpretation of Factor 11; it is consistent with Wiggins’s original intent though more thorough than the 2011 doc spelled out.

Factor 12: Admin Processes — Run Admin/Management Tasks as One-Off Processes

Statement. Administrative and management tasks (database migrations, REPL-style debugging sessions, one-off scripts to fix a corrupted record) should run as one-off processes in an environment identical to the long-running app processes — same release, same config, same backing services. They should not run in a separate “admin server,” and they should not run via SSH-into-production-and-edit-files.

Why this matters. The factor enforces consistency: if you run python manage.py migrate to apply a database migration, it must run against the same release the app is running, against the same database the app uses, with the same dependencies the app has. A separate admin server inevitably drifts from the runtime; an SSH session into production has no audit trail and no reproducibility.

The factor is operationalized in modern orchestrators as:

  • Kubernetes Jobs / OneOff — run a one-off pod with the same image as the app’s deployments.
  • Heroku one-off dynos (heroku run python manage.py migrate) — Heroku’s original implementation.
  • Database migration tools (Flyway, Liquibase, Django migrations, Alembic, Knex) — produce idempotent, versioned migration scripts that run as one-off processes.

The factor also implies that the interactive admin path (a REPL into production for debugging) runs in the same release as production. This is the operational reality at Heroku and modern cloud platforms: heroku run bash opens a one-off process with production’s environment variables; kubectl exec -it does the same in Kubernetes (though the latter is more dangerous because the exec’d shell can mutate the running process).

3. The “Beyond 12-Factor” Extensions (Hoffman 2016)

Kevin Hoffman’s Beyond the Twelve-Factor App (2016, O’Reilly, Pivotal-published) refines and extends the methodology. Hoffman reorders some factors, refines the wording of several, and adds three new factors:

Factor 13 (Hoffman): API First

Statement. The app’s API should be designed before the app itself. The contract — the OpenAPI / Swagger spec, the gRPC .proto file, the GraphQL schema — should be the source-of-truth for both the producer and the consumers, with the app’s implementation being a consumer of its own contract.

Why. API-first decouples the contract from the implementation, enabling parallel development of consumers and producers and clean versioning. It is the natural extension of Factor 4 (Backing Services as Attached Resources) — if other apps are going to consume yours as a backing service, they need a contract.

Factor 14 (Hoffman): Telemetry

Statement. A 12-factor app must emit metrics, traces, and operational signals — not just logs — because in production the app is one of many invisible processes; without telemetry, the only debugging signal is logs, which are not enough.

Why. Logs alone (Factor 11) tell you what happened; telemetry tells you how often, how slow, correlated with what. A modern cloud-native app must emit metrics (Prometheus / OpenTelemetry / StatsD) and distributed traces (W3C Trace Context, Zipkin, Jaeger, OpenTelemetry traces) for the platform’s observability stack to be useful.

Factor 15 (Hoffman): Authentication and Authorization

Statement. Every endpoint, every backing-service connection, every admin process must be authenticated and authorized. Production cannot have unauthenticated network paths.

Why. The original 12-factor doc was silent on security; in 2011 the assumption was that the perimeter (the load balancer, the firewall) handled auth. In 2016, with zero-trust networking and microservices’ east-west traffic, every service-to-service call needs auth. The extension is required for modern compliance (SOC 2, HIPAA, PCI, ISO 27001).

These three factors are widely accepted in the cloud-native community as the modern “completion” of the original twelve. The CNCF’s various working groups treat the 15-factor list as the working baseline for cloud-native applications.

4. Adoption — Where the Methodology Sits Today

The methodology has been so thoroughly absorbed into modern cloud-native infrastructure that most apps that run on Kubernetes-like platforms satisfy 8+ of the 12 factors by construction. The platform itself enforces:

  • Codebase (one codebase): Git is the version-control assumption.
  • Dependencies (explicit): the Dockerfile + image is the manifest.
  • Config (in environment): Kubernetes ConfigMaps and Secrets become environment variables.
  • Backing Services (as attached resources): Kubernetes Services and external CNAMEs.
  • Build/Release/Run separation: CI/CD pipeline → image registry → kubelet pull-and-run.
  • Processes (stateless): Pods are usually stateless; persistent state goes in PersistentVolumeClaims or external services.
  • Port Binding: containers expose ports; Services route to them.
  • Concurrency: Deployment replicas are the process-count knob.
  • Disposability: Pods can be killed; SIGTERM + grace period is the lifecycle.
  • Dev/Prod Parity: containers run identically in dev and prod (the “it works in my Docker” property).
  • Logs: container stdout/stderr are captured by the platform’s log infrastructure (Fluent Bit, Loki, etc.).
  • Admin processes: Kubernetes Jobs and kubectl exec.

The factors that remain hand-on even on modern platforms:

  • Factor 6 (Stateless) — This is on the application code, not the platform. The platform cannot enforce statelessness; the app developer must.
  • Factor 11 (Logs as event streams) — Writing structured logs (rather than free-text) is on the developer.
  • Factors 13–15 (API First, Telemetry, AuthN/Z) — All on the developer.

Modern cloud-native development is essentially: pick a platform that gives you most of the 12 factors for free; do the rest yourself.

The platforms that strongly assume 12-factor compliance:

  • Heroku — the original, still the most opinionated.
  • Cloud Foundry / Tanzu Application Service — Pivotal’s enterprise PaaS, explicitly designed around the 12 factors.
  • AWS Elastic Beanstalk — relaxed but generally 12-factor-compatible.
  • Google App Engine (Standard / Flex) — strongly 12-factor.
  • Google Cloud Run — fully 12-factor; the constraints are a checklist of the factors.
  • AWS App Runner, Azure Container Apps, Fly.io, Render, Railway — all 12-factor-baseline.
  • Kubernetes — relaxed (you can violate factors and still run, e.g., StatefulSets allow stateful pods), but the canonical workload is 12-factor.

An app that violates several factors typically cannot run on these platforms without significant rework. The methodology has, in effect, become the definition of “cloud-portable application.”

5. Common Violations and Their Consequences

A short catalog of the most common factor violations observed in production:

5.1 The In-Process Cache (Factor 6 violation)

The app caches user data in a process-local dict. Two replicas have inconsistent caches; users see flapping behavior depending on which replica handles a request. Fix: external cache (Redis, Memcached) or accept and document staleness.

5.2 The Local-Disk Upload (Factor 6 violation)

Users upload files; the app writes them to /tmp/uploads. Containers are recycled; files vanish. Fix: object storage (S3, GCS).

5.3 The Hard-Coded Connection String (Factor 3 violation)

db_url = "postgres://prod-db.internal:5432/myapp". Cannot deploy to staging without a code change. Fix: read from os.environ["DATABASE_URL"].

5.4 The Custom Log Rotation (Factor 11 violation)

The app writes to /var/log/myapp.log and rotates with logrotate. Logs are lost on container recycle. Fix: write to stdout; let the platform handle aggregation.

5.5 The Long-Lived Worker Process That Holds State (Factor 9 violation)

A worker process holds a 10-minute computation in memory. If killed, the work is lost. Fix: checkpoint to a backing store; on restart, resume from the checkpoint.

5.6 The 5-Minute Startup (Factor 9 violation)

The app loads a 2GB ML model on startup, blocking the readiness probe for 5 minutes. Rolling updates take an hour. Fix: lazy-load the model; or pre-warm in a sidecar; or cache the loaded model in a shared volume.

5.7 The Database in a Different Codebase (Factor 1 violation)

The app’s schema lives in a separate repo, maintained by a DBA team. Migrations drift from the app’s expectations. Fix: schema migrations live in the same codebase, applied as one-off processes (Factor 12).

5.8 The Sticky-Session Load Balancer (Factor 6 / Factor 8 violation)

The load balancer routes the same user to the same replica because the replica holds session state. Scaling out is harder; failover requires session migration. Fix: external session store (Redis, signed cookies, JWT).

6. Prerequisites — What You Need to Adopt 12-Factor

The methodology assumes:

  • A process supervisor. Something to keep processes running, restart them on crash, send signals correctly. systemd, runit, foreman, the container runtime, or Kubernetes.
  • A platform that consumes environment-variable config. Heroku, Kubernetes, Docker Compose, AWS ECS, Cloud Run. Or a custom platform that reads ENV correctly.
  • Stateless app design. This is on the developer. The methodology cannot retrofit stateless onto a stateful app — that’s a rewrite.
  • External backing services for state. Postgres or another RDBMS, Redis or another cache, object storage. The app cannot satisfy Factor 6 without somewhere to put the state.
  • A CI/CD pipeline. For Factor 5 (Build/Release/Run separation).
  • A secrets manager. For Factor 3 (config in environment without committing secrets to git).
  • A log aggregator. For Factor 11 (logs as event streams).
  • An observability stack (for the Hoffman extensions). Prometheus, OpenTelemetry, a tracing backend, a metrics backend.

The 12-factor methodology is the application-side contract; the platform side is what makes the contract operational. Both sides have to be in place.

7. Interview Discussion Points

The 12-factor list comes up in interviews in several characteristic ways:

  • “Make this application cloud-native.” The 12-factor list is a structured answer. Walk through the factors that the proposed app satisfies and the factors it violates. This signals you have a checklist for cloud-native readiness.
  • “How would you containerize this app?” Containerization is essentially Factor 2 (Dependencies) plus Factor 6 (Stateless processes) plus Factor 9 (Disposability). The interviewer is looking for awareness of the runtime implications, not just docker build.
  • “What’s wrong with this application?” (given a sample). The answer is almost always a 12-factor violation. Mention which factor and why the violation is a problem.
  • “What does ‘stateless’ mean?” This is a Factor 6 question. Be precise: stateless means the process holds no state across requests; state is in backing services. It does not mean the app has no state at all (cloud-native apps obviously have state — it just lives elsewhere).
  • “How do you handle configuration?” The 12-factor answer is environment variables, populated by a secrets manager. Avoid mentioning per-environment config files (a violation).
  • “How does autoscaling work for this service?” Autoscaling depends on Factor 6 (Stateless) and Factor 8 (Concurrency via process model). If the app has in-memory state, autoscaling works only with sticky sessions (degraded). If the app is stateless, autoscaling adds replicas freely.
  • “Why is logging to a file a problem?” Factor 11 question. Logs to file lose ephemeral container state, miss platform aggregation, miss structured-log indexing.
  • “Compare the 12 factors to cloud-native principles.” Most cloud-native principles are restatements of 12-factor factors plus the Hoffman extensions (telemetry, API-first, auth). The CNCF’s working definition of cloud-native overlaps the 15-factor list almost completely.

The signal value: a candidate who can name and discuss specific factors is signaling that they have built and operated cloud-native apps; a candidate who hand-waves “yeah we follow cloud-native best practices” is not.

8. Pitfalls

8.1 Cargo-Culting All 12

Some teams adopt all 12 factors because the methodology is fashionable, even when one or two don’t fit their use case. Example: a desktop application is not a SaaS app. Factor 7 (Port Binding) is irrelevant for a CLI tool. Factor 11 (Logs as event streams) is overkill for a single-user desktop app. Adopting these factors in unsuitable contexts adds complexity without benefit. The factors are for cloud-deployed SaaS apps; outside that context, they should be applied selectively.

8.2 Stateful Apps That Pretend To Be Stateless

A stateful app (e.g., a database, a game server, a stateful workflow engine) cannot satisfy Factor 6 in the literal sense — it has state, and the state must persist on local storage. Forcing it into the 12-factor mold by externalizing all state to a remote service can produce intolerable latency. The pragmatic answer: stateful apps run on Kubernetes’ StatefulSets (or equivalents) with persistent volumes; they satisfy most factors but legitimately violate Factor 6. Treat the violation explicitly rather than hiding it.

8.3 The “Logs Are Event Streams” Misreading

The misreading: “Factor 11 says write to stdout, period.” The correct reading: “Factor 11 says treat logs as a queryable event stream, and stdout is the simplest channel for that.” A team that writes unstructured prose to stdout is output-compliant but not event-stream-compliant. Modern interpretation requires structured logging.

8.4 Environment Variables as a Configuration DSL

Some teams overuse environment variables — passing complex nested data as JSON-encoded environment variables, environment variables that reference other environment variables, environment-variable-driven feature flags whose values are tiny DSLs. Factor 3 says environment variables for deploy-varying config, not for everything. Complex configuration belongs in a configuration service (Consul, etcd, ZooKeeper, Spring Cloud Config) accessed at startup or runtime.

8.5 Treating the Methodology as Architecture

The methodology is operational conventions, not an architecture. A team that adopts the 12 factors has not chosen Microservices Architecture or Monolithic Architecture — both can be 12-factor-compliant. The methodology is orthogonal to architectural style. (This is a common confusion: many engineers conflate “12-factor” with “microservices” because both are cloud-native concerns.)

8.6 Skipping Factor 10 (Dev/Prod Parity)

The most-skipped factor in the original twelve. Teams use SQLite in dev and Postgres in prod because it’s faster locally; they use a different message broker; they use a different cache. The dev/prod gap accumulates. Bugs hide in the gap. Containerized local development (Docker Compose mirroring the production stack) closes most of the gap; it should be baseline practice.

8.7 Ignoring the Hoffman Extensions

The original twelve do not address API-first design, telemetry, or auth. A team that treats the original twelve as complete will produce apps that satisfy the 2011 baseline but are not actually cloud-native by 2026 standards. The 15-factor list is the working baseline for new development.

9. Diagram — The Twelve Factors as Operational Layers

flowchart TB
    subgraph Code["Codebase Layer"]
        F1["1. Codebase<br/>(one repo, many deploys)"]
        F2["2. Dependencies<br/>(explicit, isolated)"]
    end
    subgraph Pipeline["Build/Release Pipeline"]
        F5["5. Build / Release / Run<br/>(strict separation)"]
    end
    subgraph Runtime["Runtime Layer"]
        F6["6. Processes<br/>(stateless)"]
        F7["7. Port Binding<br/>(self-contained server)"]
        F8["8. Concurrency<br/>(scale via processes)"]
        F9["9. Disposability<br/>(fast startup, graceful shutdown)"]
    end
    subgraph Config["Configuration"]
        F3["3. Config<br/>(environment vars)"]
        F4["4. Backing Services<br/>(attached resources)"]
    end
    subgraph Ops["Operational Discipline"]
        F10["10. Dev/Prod Parity"]
        F11["11. Logs<br/>(event streams to stdout)"]
        F12["12. Admin Processes<br/>(one-off, same release)"]
    end
    Code --> Pipeline
    Pipeline --> Runtime
    Config --> Runtime
    Runtime --> Ops

What this diagram shows. The twelve factors group into five operational layers, each providing a precondition for the next. The codebase layer (Factors 1–2) is the source-of-truth; the pipeline layer (Factor 5) translates codebase + config into runtime artifacts; the configuration layer (Factors 3–4) feeds per-environment data into the pipeline; the runtime layer (Factors 6–9) describes how the running app behaves; the operational discipline (Factors 10–12) describes how the team operates the running app. The arrows show dependency: you cannot have a Build/Release/Run separation (Factor 5) without first having a single codebase (Factor 1) and explicit dependencies (Factor 2); you cannot have stateless processes (Factor 6) without backing services (Factor 4) to hold the state. The grouping is not the original 12-factor doc’s grouping (Wiggins lists them flat) but is a useful pedagogical organization that makes clear which factors enable which others. The Hoffman extensions (API First, Telemetry, AuthN/Z) belong above the Operational Discipline layer as a thin “external contract” layer.

10. Comparison With Sibling Concepts

  • Cloud-Native (CNCF working definition). The CNCF defines cloud-native as “containerized, dynamically orchestrated, microservices-oriented” with declarative APIs. Roughly: 12-factor + microservices + observability + Kubernetes-style platform. The 12 factors are the application-side of the CNCF definition; CNCF adds infrastructure-side conventions.
  • Microservices. Microservices is an architectural style (see Architecture Styles vs Patterns vs Frameworks); 12-factor is a set of operational conventions. They are orthogonal but compatible — a microservices system whose services are not 12-factor will have operational pain. A 12-factor monolith is a perfectly fine architecture.
  • DevOps. DevOps is a cultural and practice movement; 12-factor is a technical methodology. Factor 10 (Dev/Prod Parity) and Factor 5 (Build/Release/Run) are DevOps requirements stated as application properties.
  • Kubernetes. Kubernetes is a platform that strongly assumes 12-factor apps. A 12-factor app runs unmodified on Kubernetes (modulo container packaging). A non-12-factor app needs adaptation.
  • Serverless / FaaS. FaaS imposes the 12 factors more strictly than Heroku-style PaaS — functions are mandatorily stateless, ephemeral, and config-via-environment. A 12-factor app is generally a candidate for serverless without redesign; a non-12-factor app needs a rewrite.

11. Open Questions

  • Does Factor 11 (Logs as event streams) need to be re-read in 2026 to explicitly include traces and metrics, given the rise of OpenTelemetry as a unified observability data model?
  • Is Factor 6 (Stateless Processes) still the right baseline for stateful workloads (databases, queues, ML training)? Modern Kubernetes accepts stateful apps via StatefulSets; should the methodology have a “stateful equivalent” companion?
  • Do the Hoffman extensions (Factors 13–15) need a 2026 update for AI workloads (model serving, fine-tuning, RAG pipelines)?
  • How should the methodology handle event-driven and streaming applications, where the “request lifecycle” assumption underlying Factor 9 (graceful shutdown of in-flight requests) doesn’t apply?
  • Is there a 16th factor for security baselines beyond authentication/authorization — secret rotation, supply-chain integrity, runtime threat detection?

12. See Also

Graph View

Backlinks