12-Factor App: Principles and Modern Cloud-Native Application

The 12-Factor App is a methodology codified by Heroku in 2011 for building SaaS applications that are easy to deploy, scale, and operate in the cloud.

The twelve factors

1. 1
   Codebase - one repo, many deploys
2. 2
   Dependencies - explicit, isolated
3. 3
   Config - in environment
4. 4
   Backing services - attached resources
5. 5
   Build, release, run - strict separation
6. 6
   Processes - stateless, share-nothing
7. 7
   Port binding - self-contained, exports via port
8. 8
   Concurrency - scale horizontally via process model
9. 9
   Disposability - fast startup, graceful shutdown
10. 10
    Dev/prod parity - keep environments similar
11. 11
    Logs - event stream to stdout
12. 12
    Admin processes - one-off commands as identical processes

Why 12-Factor exists

• Heroku engineers codified patterns from reliably-deployable SaaS apps
• Goal: apps built once, deployed anywhere, scaled horizontally, managed by simple orchestration
• Predates Kubernetes but reads like a design spec for it
• Modern cloud-native traces back to these principles

Each factor with Java/Spring application

I. Codebase

• One repo per app; many deploys from same codebase
• Git repo; tags/branches for environments, not separate repos

II. Dependencies

• Declare all deps explicitly; never system packages
• Maven/Gradle pinned versions; fat-jar packaging; distroless/JDK base images

III. Config

• Config differing between deploys in environment (env vars)
• application.yml for defaults; @ConfigurationProperties pulls SPRING_DATASOURCE_URL etc.
• Never check secrets into Git

IV. Backing services

• DBs, queues, caches as attached resources, swappable via config
• DataSource URL = dev Postgres locally or RDS in prod; Kafka brokers from env

V. Build, release, run

• Build: compile, test, package (container image)
• Release: artifact + env config = versioned release
• Run: execute release
• CI builds :1.2.3 image; CD promotes to staging/prod; rollback = prev image

VI. Processes

• Stateless, share-nothing; state goes to backing services
• No file-on-disk state; no session-in-memory (use Spring Session + Redis)

VII. Port binding

• Self-contained; exports HTTP by binding to port; no external webserver
• Embedded Tomcat/Netty; server.port from env

VIII. Concurrency

• Scale by more processes (horizontal); atomic scale units
• K8s Deployment replicas; HPA on CPU / custom metrics

IX. Disposability

• Fast startup (seconds), graceful shutdown (flush, close pools on SIGTERM)
• server.shutdown=graceful + timeout-per-shutdown-phase=30s
• K8s preStop hook + terminationGracePeriodSeconds

X. Dev/prod parity

• Same DB engine, same queue; short commit-to-deploy gap
• Testcontainers spins real Postgres/Kafka in tests; avoid H2

XI. Logs

• Event streams to stdout; aggregation = infra's job
• Logback JSON to stdout; Fluent Bit/Datadog ships to log store

XII. Admin processes

• One-off admin tasks (migrations, backfills) as identical processes against release
• Flyway on startup; K8s Jobs using same image + different command

Beyond 12 Factors - Kevin Hoffman + modern

Hoffman's additions

• API first: design contract before implementation
• Telemetry: metrics, traces, structured logs from day one
• Authn/authz: cross-cutting concern early; OAuth2/OIDC, mTLS

Modern 2020s additions

• Security by default: vault secrets, image scanning, SBOM, non-root containers, read-only rootfs
• Multi-tenant awareness: bake into data model + observability from day one
• Idempotency: HTTP idempotency keys, consumer dedup; essential for retries
• Progressive delivery: feature flags, canaries, blue/green
• Cost awareness: resource limits, autoscaling, ephemeral environments
• Graceful degradation: circuit breakers, fallbacks, cached data

Where 12-Factor strains

1. 1
   Stateful services (DBs, brokers) inherently violate 'stateless processes'
2. 2
   In-memory caches for performance violate strict statelessness
3. 3
   Long-running jobs (hours): disposability hard; use checkpoints + idempotent processing
4. 4
   Stateful workflows (sagas, sessions): state in backing service; process stateless
5. 5
   WebSocket servers: external state ideal; sticky connections as trade-off

Putting it together - 12-Factor Spring Boot service

Repo, Dockerfile, CI/CD, manifests all follow the factors

• Maven build → container image with temurin base
• application.yml placeholders for env; secrets from Vault/CSI
• K8s Deployment + HPA for scaling
• Graceful shutdown config in Spring + K8s
• Testcontainers for integration tests
• JSON logs to stdout
• Flyway migrations + K8s Jobs for admin tasks

Trade-offs and when to deviate

Why 12-Factor wins

• Portability: any k8s/PaaS
• Scalability: horizontal built-in
• Maintainability: clear separation
• Observability: consistent stdout + env

Costs

• Lots of env vars painful; use ConfigMaps + Secrets
• Secrets in env visible to pod access; use Vault/CSI/RBAC
• Strict statelessness hurts caches; pragmatic: recomputable caches
• Fast startup vs Java bootstrap cost; AOT (Spring Native), SnapStart
• High-volume stdout can overrun pipes; sample/rate-limit

Anti-patterns

1. 1
   Config in code
2. 2
   Per-env repos
3. 3
   File-based logs (stdout is k8s-native)
4. 4
   JVM memory sessions
5. 5
   DB migrations outside release
6. 6
   Long sync startup (JPA warmup)
7. 7
   Health checks not checking dependencies

When to deviate

• Data services: StatefulSets, PVCs, backup strategy
• ML inference with large models: preload, readiness probe gate traffic
• Legacy: migrate incrementally, logs first
• Monoliths modernizing: externalize config + logs first

Strategic take

• 12-Factor is floor, not ceiling
• Following doesn't make you cloud-native; makes you deployable
• Modern adds observability, resilience, security, FinOps, progressive delivery
• Biggest benefit: onboarding speed; new service understood in 30 min; pipeline boilerplate
• Deviate for good reasons; deviating without knowing = snowflake services

Interview angle

• Don't recite all 12
• Connect principles to real code/infra
• Name factor, explain meaning, give Java/K8s example, note where it strains

Bottom line

• 12-Factor = minimum for cloud-native; modern layers on observability, resilience, security
• Stateless processes + env config + stdout logs = deployable anywhere
• Interview-wise: demonstrate application to real Spring Boot + K8s