12-Factor App

Tags

12-Factor App

"The twelve-factor app is a methodology for building software-as-a-service apps that can be deployed to modern cloud platforms, are easily scalable, and are independent of host environments." -- Wiggins et al., 12factor.net, 2012

Intent

This is a reference note documenting the 12-factor methodology, not a design pattern. The 12 factors are a set of principles for building cloud-native SaaS applications that were codified by the team behind the Heroku platform in 2012 from observations across many production deployments. They address the mechanics of code, dependencies, configuration, backing services, build pipelines, processes, concurrency, and operational behavior that make applications portable, scalable, and deployable on modern cloud infrastructure.

The 12 factors are prerequisites that make Blue/Green, Canary, Rolling, and Feature Flags viable. Factor VI (stateless processes) is the direct enabler of Rolling deployment. Factor III (config from environment) is the enabler of externalized Feature Flag state. Factor X (dev/prod parity) is the enabler of Blue/Green confidence. Understanding the 12 factors explains why cloud-native release patterns are structured as they are -- the patterns assume a 12-factor application as their substrate.

12-Factor Reference Table

FactorNamePrincipleCloud-Native Relevance
ICodebaseOne codebase tracked in revision control, many deploysEnables Blue/Green: the same codebase artifact is deployed to both Blue and Green environments; no environment-specific code branches
IIDependenciesExplicitly declare and isolate dependenciesReproducible builds ensure consistent Blue/Green environments; dependency drift between Blue and Green is a deployment defect, not an environment issue
IIIConfigStore config in the environment, not in the codebaseEnables Feature-Flags-Pattern: flag state is config, not code -- flags read from environment variables or a config service, not from deployed artifacts
IVBacking ServicesTreat backing services as attached resourcesDatabase as attached resource enables Blue/Green DB sharing: both Blue and Green connect to the same database; schema must be backward-compatible during the coexistence window
VBuild, Release, RunStrictly separate build and run stagesCanary and Blue/Green require distinct release artifacts per version; the Release stage combines a Build with its Config, producing an immutable artifact used across environments
VIProcessesExecute the app as one or more stateless processesDirectly enables Rolling-Deployment: stateless processes can be replaced one-by-one without session loss; in-memory state is incompatible with rolling replacement
VIIPort BindingExport services via port bindingSelf-contained port binding enables service discovery for Canary traffic splitting: the load balancer routes by port to stable vs canary instances without application awareness
VIIIConcurrencyScale out via the process modelHorizontal scaling is a prerequisite for Canary slice isolation: a canary slice is a subset of the total process pool, not a separate application deployment
IXDisposabilityMaximize robustness with fast startup and graceful shutdownRolling deployment requires fast instance replacement; slow startup extends the coexistence window between old and new versions; graceful shutdown prevents in-flight request loss during replacement
XDev/Prod ParityKeep development, staging, and production as similar as possibleEnables Blue-Green-Deployment: Green must be production-identical for the pre-switch validation to be meaningful; parity gaps between Green and production invalidate Canary analysis
XILogsTreat logs as event streamsCanary analysis requires centralized log streams for metric comparison between stable and canary instances; logs as events (not files) enables real-time aggregation across the mixed-version fleet
XIIAdmin ProcessesRun admin/management tasks as one-off processesDB migrations run as one-off processes (not tied to app startup) -- a prerequisite for the Expand/Contract migration pattern required by Blue/Green and Canary deployments

Cloud-Native Pattern Dependencies

The 12 factors collectively form the substrate that makes cloud-native release strategies viable. No single factor is sufficient; the patterns depend on the factors in combination.

Blue-Green-Deployment depends on Factors I (same codebase artifact for both environments), IV (shared backing service), X (dev/prod parity means Green is trustworthy), and XII (migrations run as one-off processes, not application startup). A Blue/Green deployment on an application that violates Factor X provides false confidence -- Green passes pre-switch validation in a staging environment that differs from production.

Canary-Release-Pattern depends on Factors VI (stateless processes so any instance can be canary), VII (port binding enables load balancer routing), VIII (process model supports running a small canary pool alongside the stable pool), and XI (centralized logs enable metric comparison between canary and stable). Automated Canary analysis (Argo Rollouts, Kayenta) is impossible without Factor XI.

Rolling-Deployment has the strictest dependency: Factor VI (stateless processes) is a hard requirement, not a recommendation. A stateful application on a rolling deployment loses user sessions when old instances are replaced mid-rollout. Factor IX (fast startup) determines how long the mixed-version window lasts during the rollout.

Feature-Flags-Pattern depends on Factor III (config from environment). Flag state must be externalized to a config service (LaunchDarkly, Unleash, AWS AppConfig), not embedded in deployed artifacts. If flag state lives in code, changing it requires a deployment -- defeating the purpose of feature flags. Factor III is the architectural principle that makes runtime flag evaluation without redeployment possible.

The Deployment-Patterns-MOC covers the full deployment pattern graph; all Phase 14 and Phase 15 patterns assume 12-factor compliance as their baseline.

Factor Grouping Diagram

flowchart LR
    subgraph Build["Build Stage"]
        F1["I. Codebase<br/>one repo, many deploys"]
        F2["II. Dependencies<br/>explicitly declared"]
        F5["V. Build, Release, Run<br/>strict separation"]
    end

    subgraph Config["Configuration"]
        F3["III. Config<br/>in the environment"]
        F4["IV. Backing Services<br/>attached resources"]
    end

    subgraph Runtime["Runtime Behavior"]
        F6["VI. Processes<br/>stateless"]
        F7["VII. Port Binding<br/>self-contained"]
        F8["VIII. Concurrency<br/>scale via process model"]
        F9["IX. Disposability<br/>fast startup + graceful shutdown"]
    end

    subgraph Ops["Operations"]
        F10["X. Dev/Prod Parity"]
        F11["XI. Logs as event streams"]
        F12["XII. Admin processes<br/>one-off tasks"]
    end

    Build -->|"immutable artifact"| Config
    Config -->|"configured release"| Runtime
    Runtime -->|"observable in"| Ops

    BG["Blue/Green"] -.-> F1 & F4 & F10 & F12
    CAN["Canary"] -.-> F6 & F7 & F8 & F11
    ROLL["Rolling"] -.-> F6 & F9
    FF["Feature Flags"] -.-> F3

    style Build fill:#e6f3ff,stroke:#4a90d9
    style Config fill:#fff3e6,stroke:#d98c00
    style Runtime fill:#e6ffe6,stroke:#4a9d4a
    style Ops fill:#f0e6ff,stroke:#9a4ad9

Suitability Caveat

The 12 factors are a guide, not a checklist. Some factors are inapplicable to specific contexts. Factor XII (admin processes as one-off tasks) does not apply to batch processing systems where the job IS the process. Factor VII (port binding) assumes HTTP services; message consumer processes that pull from a queue have no port to bind. Factor VIII (scale out via process model) is inapplicable to stateful systems that cannot be horizontally scaled (some legacy databases, some licensed monoliths).

Applying all 12 factors mechanically to every system context is cargo-culting. The correct use is to read each factor as a question: "Does this apply to our context? If not, why not, and what are we doing instead?" A deliberate non-compliance with a documented rationale is an architectural decision. An accidental non-compliance is a technical debt item.

  • Secrets-Management — Factor III (config from environment) is necessary but insufficient for secrets; Secrets-Management covers centralized secret stores with dynamic generation and dual-credential rotation that go beyond simple environment variable injection
  • Structured-Logging — Factor XI (treat logs as event streams) is the 12-factor principle; Structured-Logging defines the JSON field schema and async context propagation that make Factor XI actionable in distributed systems

Sources

  • Wiggins, Adam et al. "The Twelve-Factor App" -- 12factor.net, 2012 -- canonical primary source; all 12 factors with original explanations
  • Kim, Gene; Humble, Jez; Debois, Patrick; Willis, John. The DevOps Handbook, IT Revolution Press, 2016 -- deployment and release context; 12-factor principles applied to continuous delivery

Notes that link here: Rolling-Deployment, Feature-Flags-Pattern, Deployment-Patterns-MOC

Linked mentions