Skip to content
notes.vinhnq.com

Search

Git, DevOps & ToolingMid25 min read

The Twelve-Factor App: 12 principles for cloud-ready services, applied to Spring Boot and Kubernetes

Review 19 cards
On this page

Take the same kind of Spring Boot app: one team scales it from 2 to 20 pods in a minute and rolls back in 30 seconds; another rebuilds the jar for every environment and worries about losing sessions every time it scales. The difference lies in how the app is written, not in the tooling. This post walks through the twelve factors with Java 21 + Spring Boot 3 + Docker + Kubernetes, plus a small JDK-only app to try config from the environment and graceful shutdown (run on JDK 21).

At a glance:

flowchart LR
  A["One codebase"] --> B["Build image once"]
  B --> C["Release = image + config"]
  E["Config from environment"] --> C
  C --> D["Stateless processes"]
  F["Backing services via URL"] --> D
  D --> G["Scale out by process"]
  D --> H["Graceful SIGTERM shutdown"]
  D --> I["Logs to stdout"]
  C --> J["Admin: one-off process"]

Overview

Key idea: twelve principles written in 2011 by Adam Wiggins and other Heroku engineers, distilled from running hundreds of thousands of apps. Most of them still underpin Docker and Kubernetes: a container image that runs unchanged in every environment is a twelve-factor app.

# Factor In one line
I Codebase One codebase tracked in revision control, many deploys
II Dependencies Explicitly declare and isolate dependencies
III Config Store config in the environment
IV Backing services Treat backing services as attached resources
V Build, release, run Strictly separate build and run stages
VI Processes Execute the app as one or more stateless processes
VII Port binding Export services via port binding
VIII Concurrency Scale out via the process model
IX Disposability Fast startup and graceful shutdown
X Dev/prod parity Keep development, staging and production as similar as possible
XI Logs Treat logs as event streams
XII Admin processes Run admin tasks as one-off processes

I. Codebase: one codebase, many deploys

Key idea: one app = one repo (or one clearly bounded directory in a monorepo). Staging, production and developer machines are all deploys of the same codebase, possibly at different commits.

  • Several apps sharing code: extract it into a versioned library, don’t copy it.
  • A sign you’re breaking it: several repos that form “one app” and always have to be deployed together (really a distributed monolith).

II. Dependencies: declare and isolate

Key idea: every dependency is declared in pom.xml/build.gradle with a pinned version; the build never relies on whatever happens to be installed. A container image is the most thorough isolation there is.

Maven and Gradle make this almost the default, but three things still slip through:

  • System tools used at runtime (curl, fonts, ImageMagick) that aren’t in the image.
  • Dynamic versions (LATEST, + in Gradle) that make today’s build differ from yesterday’s. Use the wrapper and lock files.
  • “Whatever JDK is on the server” instead of one named in the image (eclipse-temurin:21-jre).

III. Config: store it in the environment

Key idea: config is everything that varies between deploys (database URLs, credentials, host names, per-environment feature flags), and it comes from the environment. The litmus test: could you open-source the repo right now without leaking any credentials?

Not config: internal wiring that’s the same everywhere (which bean is injected where, which route maps to which controller).

12factor.net argues against two approaches: constants in code, and config grouped into named “environments” (dev, test, prod). The reason: each new deploy (staging-2, a developer’s machine, a client demo) needs yet another group, and the combinations soon become unmanageable. Each setting should be independent and set per deploy.

Spring Boot fits this thanks to relaxed binding (property names are matched to environment variable names automatically): spring.datasource.url can come from SPRING_DATASOURCE_URL, app.payment.timeout from APP_PAYMENT_TIMEOUT.

# application.yml: safe defaults for local runs, production overrides via env
spring:
  datasource:
    url: ${DATABASE_URL:jdbc:postgresql://localhost:5432/booking}
    username: ${DATABASE_USER:booking}
    password: ${DATABASE_PASSWORD:}
app:
  payment:
    timeout: ${PAYMENT_TIMEOUT:5s}
// Bind config to a record and validate at startup: missing values mean no start
@Validated
@ConfigurationProperties("app.payment")
record PaymentProperties(@NotNull URI baseUrl, @NotNull Duration timeout, @NotBlank String secretKey) {}

Spring Boot’s precedence between config sources, @ConfigurationProperties and profiles: Spring Boot from the inside.

Environment variables or a secret manager for secrets

The rest of secret hygiene (scanning in CI, rotating first and cleaning Git history second when one leaks, rotating without downtime by accepting the old and new key side by side, masking secrets in logs) is in Encoding, hashing, encryption and signatures.

IV. Backing services: attached resources

Key idea: databases, Redis, Kafka, SMTP, S3 and third-party APIs are all backing services, located through URLs and credentials in config. Moving from self-hosted PostgreSQL to RDS is a change of DATABASE_URL, not of code.

The consequence: the app must cope with backing services being slow or unreachable. That means timeouts, bounded retries, circuit breakers (temporarily stop calling a dependency that keeps failing), and health checks that tell “I’m dead” apart from “the database is dead”.

You also need to know what a backing service promises when it fails itself. Redis replication, for example, is asynchronous: if the master replies “OK” and dies before the replica gets the command, that write is gone after failover. How much RDB or AOF, Sentinel or Cluster can lose is in Redis: persistence, replication, Sentinel and Cluster.

V. Build, release, run: three separate stages

Key idea: build produces an artifact, a release = artifact + config with an immutable id, run starts processes from a release. The image is built once and promoted through every environment, so what runs in production is exactly what was tested.

  • Build: turn the code at one commit into a runnable artifact (a jar, then an image). Done in CI.
  • Release: the artifact plus one environment’s config, with a fixed id (v42). Any change creates a new release.
  • Run: start processes from a release.

In practice:

  • dev → staging → prod use the same image; nothing is rebuilt.
  • Tag images by commit SHA or version (booking:a1b2c3), never latest, or you can’t tell what production runs and rollbacks are guesswork.
  • Rollback = rerun the previous release (old image + old config): kubectl rollout undo, or GitOps (Argo CD, Flux) keeping releases as commits in a config repo.

A GitHub Actions pipeline that implements these three stages (build the image once from main, promote the same digest through staging to production, roll back to the old digest) is in CI/CD for a Spring Boot backend.

VI. Processes: stateless, share-nothing

Key idea: processes hold no state that has to outlive a request; anything that must persist lives in a backing service. The next request will almost certainly hit a different process.

Local memory and disk are only a short-lived cache within one request (processing an upload before pushing it to S3, say). Common violations:

  • HttpSession in Tomcat’s memory, “fixed” with sticky sessions (the load balancer always sends a user to the same server). 12factor.net calls that a violation outright. Use stateless tokens (JWT) or Spring Session with Redis.
  • Uploads saved to /tmp/uploads and read back by a later request.
  • A local cache (Caffeine) treated as a data source: one copy per pod, drifting apart.
  • @Scheduled in a web app.

VII. Port binding: bring your own server

Key idea: the app is self-contained: it embeds its web server and binds a port, rather than being deployed into an existing one. Spring Boot with embedded Tomcat/Jetty/Netty is exactly this model (unlike the era of WARs deployed into a shared Tomcat).

  • The port comes from config: server.port=${PORT:8080}.
  • The app becomes another app’s backing service through a URL.
  • Put Actuator on its own port (management.server.port=8081) so health checks and metrics aren’t exposed to the Internet alongside the API.

VIII. Concurrency: scale out with processes

Key idea: work is divided by process type (web handles HTTP, worker drains queues), and each type scales independently by adding processes. On Kubernetes: each type is a Deployment from the same image with a different command, scaled with replicas or an HPA.

The app doesn’t daemonise itself or write PID files; the platform manages processes. Twelve-factor doesn’t forbid threads: the process is the unit you scale out with, and inside it you still use virtual threads or a pool.

Threads or processes: the detailed comparison

IX. Disposability: fast startup, graceful shutdown

Key idea: processes can be started or stopped at any moment (deploys, scaling, nodes being reclaimed). So they must start fast, shut down gracefully on SIGTERM, and survive sudden death.

  • Start fast (seconds): selective lazy initialisation, trimming unused auto-configuration, Class Data Sharing (CDS) or CRaC, native image if you really need it.
  • Shut down gracefully on SIGTERM (the “please stop” signal the platform sends first): a web process stops accepting new connections, finishes in-flight requests, then exits. A worker returns its current job to the queue (NACK, don’t commit the offset).
  • Survive sudden death: power loss, SIGKILL. Jobs must be reentrant (rerunning from the start is still correct): wrapped in a transaction or idempotent (see Idempotency part 1).

In Spring Boot, since 3.4 graceful shutdown is on by default for embedded web servers (before that you set server.shutdown=graceful). The wait per phase is spring.lifecycle.timeout-per-shutdown-phase (30s by default). The rest depends on the container and Kubernetes. How graceful shutdown, preStop and readiness work together in a rolling update is in Deployment strategies.

A JDK-only test app: config from the environment, SIGTERM and the test run

The app reads config from the environment and refuses to start if something’s missing, binds the port from PORT, and logs JSON to stdout. On SIGTERM it reports “not ready” and waits for in-flight requests before stopping.

import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.net.URI;
import java.time.Duration;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicBoolean;

public class App {

    /** All config comes from the environment and is validated once at startup. */
    record Config(int port, URI databaseUrl, Duration shutdownGrace) {
        static Config fromEnv(Map<String, String> env) {
            List<String> errors = new ArrayList<>();
            int port = 8080;
            try { port = Integer.parseInt(env.getOrDefault("PORT", "8080")); }
            catch (NumberFormatException e) { errors.add("PORT must be a number"); }
            String db = env.get("DATABASE_URL");
            if (db == null || db.isBlank()) errors.add("DATABASE_URL is required");
            Duration grace = Duration.parse(env.getOrDefault("SHUTDOWN_GRACE", "PT20S"));
            if (!errors.isEmpty()) throw new IllegalStateException("Invalid config: " + errors);
            return new Config(port, URI.create(db), grace);
        }

        @Override public String toString() {          // never log credentials
            return "Config[port=" + port + ", db=" + databaseUrl.getHost() + ", grace=" + shutdownGrace + "]";
        }
    }

    public static void main(String[] args) throws Exception {
        Config config = Config.fromEnv(System.getenv());
        log("starting " + config);

        AtomicBoolean ready = new AtomicBoolean(false);
        HttpServer server = HttpServer.create(new InetSocketAddress(config.port()), 0);
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        server.createContext("/ready", ex -> {
            ex.sendResponseHeaders(ready.get() ? 200 : 503, -1);
            ex.close();
        });
        server.createContext("/work", ex -> {          // simulates a request that takes 2 seconds
            try { Thread.sleep(2000); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
            byte[] body = "done\n".getBytes();
            ex.sendResponseHeaders(200, body.length);
            ex.getResponseBody().write(body);
            ex.close();
        });
        server.start();
        ready.set(true);
        log("listening on :" + config.port());

        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            log("SIGTERM received, failing readiness and draining");
            ready.set(false);
            // stop(n): refuse new exchanges, wait up to n seconds for in-flight ones
            server.stop((int) config.shutdownGrace().toSeconds());
            log("stopped cleanly");
        }));
    }

    static void log(String msg) {                       // logs are an event stream on stdout
        System.out.println("{\"ts\":\"" + Instant.now() + "\",\"msg\":\"" + msg + "\"}");
    }
}

With bad config it stops immediately, with one error listing every problem:

$ PORT=abc java App.java
Exception in thread "main" java.lang.IllegalStateException: Invalid config: [PORT must be a number, DATABASE_URL is required]

With valid config, I sent a /work request (2 seconds) and ran kill -TERM 0.3 seconds later:

{"ts":"...33.521Z","msg":"starting Config[port=18081, db=db.internal, grace=PT5S]"}
{"ts":"...33.543Z","msg":"listening on :18081"}
{"ts":"...35.195Z","msg":"SIGTERM received, failing readiness and draining"}
{"ts":"...36.976Z","msg":"stopped cleanly"}
work: done

The in-flight request still got done, the process exited only after it finished, and the password in DATABASE_URL never appeared in the log.

Why PID 1 is special, how exit code 143 differs from 137, and when you need a real init such as tini (docker run --init) to forward signals and reap zombies: see Operating systems for backend engineers.

X. Dev/prod parity: keep dev like production

Key idea: close three gaps between development and production: time (code written today reaches production weeks later), personnel (developers write, ops deploy), tools (H2/SQLite in development, PostgreSQL in production).

How: deploy continuously, several times a day; have the people who write the code deploy and watch it; use the same kind of backing services everywhere. The tools gap causes the nastiest bugs: tests pass on H2, production fails on different syntax, locking or data types.

My choice: Testcontainers (real PostgreSQL, Kafka, Redis in Docker during tests) for every test that touches a database or a broker.

H2 or Testcontainers: the detailed comparison

XI. Logs: an event stream to stdout

Key idea: the app doesn’t manage log files (it doesn’t write or rotate them). It writes each event to stdout, one per line; the runtime (Docker, Kubernetes, agents such as Fluent Bit, Vector or the OTel Collector) collects them, adds metadata and ships them to log storage.

Spring Boot’s Logback logs to the console by default; just don’t set logging.file.name in a container. Prefer structured JSON logs (Spring Boot 3.4: logging.structured.format.console=ecs or logstash) with the trace id, so you filter by field instead of by regex.

The same idea (the app only emits events and doesn’t decide where they go) now applies to metrics and traces as well, through OpenTelemetry; see Distributed tracing with OpenTelemetry.

XII. Admin processes: one-off tasks

Key idea: migrations, data-fix scripts and REPL consoles run as one-off processes with the same release (same image, same code) and the same config as the regular processes. Admin code lives in the same repo and ships with the app so versions never drift.

On Kubernetes: a Job (or an init container, a Helm/Argo CD hook) running the same image with a different command. Don’t SSH into a production pod to run SQL by hand: no review, no history, not repeatable.

Running migrations at startup is simple; a separate Job before rollout is safer. Either way, migrations must be backward compatible (expand → migrate → contract). How to run Flyway as its own pipeline step before the rollout is in CI/CD for a Spring Boot backend.

Migrations at startup or as a separate Job: the detailed comparison

What twelve-factor leaves out, or needs a modern reading

Key idea: the spirit holds, but some concepts need a broader reading and a few areas are missing.

  • Written in 2011 for a Heroku-style PaaS. Today Kubernetes takes care of much of factors V, VI, VIII, IX and XI at the platform level, but the app still has to be written for it (external config, no local state, proper SIGTERM handling).
  • Read “environment variables” as “provided by the environment”: ConfigMaps, Secrets mounted as files, secret managers. “Logs” has grown into telemetry: structured logs, metrics, traces.
  • Missing: health checks, service-to-service security, API contracts, resilience when backing services are slow. “Beyond the Twelve-Factor App” (Kevin Hoffman, 2016) adds API first, telemetry, and authentication and authorization.
  • In November 2024 Heroku open-sourced twelve-factor for the community to maintain; the most discussed topics are logging, telemetry and app identity.

Exercises

Exercise 1: Score an application

Task: a Spring Boot service has the traits below. Name the factor each one breaks and how to fix it. (a) An application-prod.yml in the repo holds the DB password. (b) CI builds a jar for staging, and after testing builds another jar for production. (c) Login sessions live in HttpSession, with sticky sessions on the load balancer. (d) Logs go to /app/logs/app.log. (e) A reconciliation job @Scheduled(cron = "0 0 2 * * *") lives in the same app, which runs 4 replicas. (f) Migrations are run by a developer SSHing into the server and running psql -f. (g) Tests use H2; production runs PostgreSQL 16. (h) The Dockerfile has ENTRYPOINT java -jar app.jar.

Solution to exercise 1
Factor Fix
a III Config Remove it from the repo, rotate the password (it’s in Git history), move it to a Secret/secret manager, add secret scanning to CI
b V Build, release, run Build the image once, tag it with the commit SHA, promote the same image from staging to production
c VI Processes Spring Session with Redis, or stateless tokens; turn off sticky sessions
d XI Logs Log JSON to stdout and let the platform collect it
e VI/VIII Move it to a CronJob or a 1-replica worker, or use ShedLock; make the job idempotent
f XII Admin processes Flyway in the repo, run as a Kubernetes Job from the same image before rollout
g X Dev/prod parity Testcontainers with PostgreSQL 16
h IX Disposability ENTRYPOINT ["java", "-jar", "/app/app.jar"] so the JVM gets SIGTERM

Exercise 2: Graceful shutdown on Kubernetes

Task: the service handles requests that take up to about 10 seconds. Every deploy, clients see a few dozen 502s and “connection reset” errors. Write the Spring Boot and Kubernetes config for error-free deploys.

Solution to exercise 2
# application.yml
server:
  shutdown: graceful              # default since Spring Boot 3.4, explicit for older versions
spring:
  lifecycle:
    timeout-per-shutdown-phase: 20s
management:
  endpoint:
    health:
      probes:
        enabled: true             # /actuator/health/liveness and /readiness
# deployment.yaml (excerpt)
spec:
  template:
    spec:
      terminationGracePeriodSeconds: 40     # > preStop (5) + drain (20) + margin
      containers:
        - name: booking
          image: registry.example.com/booking:a1b2c3
          readinessProbe:
            httpGet: { path: /actuator/health/readiness, port: 8081 }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /actuator/health/liveness, port: 8081 }
            periodSeconds: 10
          lifecycle:
            preStop:
              sleep: { seconds: 5 }          # Kubernetes 1.30+; older: exec ["sleep", "5"] (needs sleep in the image)

The shutdown sequence:

  1. preStop gives the ingress and kube-proxy a few seconds to drop the pod before the app closes its listener.
  2. Spring receives SIGTERM, readiness switches to REFUSING_TRAFFIC, the web server stops accepting new connections and waits up to 20 seconds for in-flight requests (twice the longest request).
  3. terminationGracePeriodSeconds covers both, plus a margin for closing the connection pool and flushing logs and spans.

Add an exec-form ENTRYPOINT and maxUnavailable: 0 in the rolling-update strategy. I haven’t run this Kubernetes config; the JVM side of graceful shutdown was tested in section IX.

Remember

  • Explain what twelve-factor config is, the “open-source the repo” test, and why an application-prod.yml with passwords breaks it.
  • Know why the image is built once, tagged with the commit SHA, and why rollback is just rerunning the previous release.
  • Name at least three “stateful process” violations in Spring Boot, including @Scheduled on many replicas, and how to fix them.
  • Describe the pod shutdown chain that drops no requests: exec ENTRYPOINT, preStop, readiness, graceful shutdown, grace period.
  • Know when to run migrations at startup vs as a Job, and why they must be expand/contract.

Interview questions

Junior

What is the Twelve-Factor App, and why does it still matter?

Twelve principles for writing apps that run well on cloud platforms, distilled by Heroku in 2011. It still matters because Docker and Kubernetes assume apps follow most of them.

Concretely: config outside the image, stateless processes that scale horizontally, logs to stdout, graceful shutdown on SIGTERM. An app that breaks them will still run on Kubernetes, but it’ll be hard to scale and hard to deploy without errors.

Why shouldn’t you write log files inside a container?

Because the container’s filesystem is temporary: logs disappear with the container, kubectl logs can’t read files, and growing files fill the node’s disk.

The app should write events to stdout and let the platform collect and ship them; the app doesn’t need to know where logs end up.

Mid

What does twelve-factor config mean? Do Spring profiles break it?

Config is whatever varies between deploys; it must live outside the code and come from the environment. Profiles holding per-environment values break it; profiles for behavioural differences are fine.

Config means URLs, credentials, host names; the test is whether you could open-source the repo right now without leaking secrets. An application-prod.yml with URLs and passwords puts secrets in Git, ties the image to environments, and needs a new file for each new environment. Values should go through env, ConfigMaps and Secrets.

What does “stateless process” mean in a Spring Boot app?

Nothing that has to outlive a request sits in the process’s memory or disk.

Sessions go to Redis or into tokens, uploads go to object storage, data goes to the database. Then any request can go to any pod, scaling and restarts lose nothing, and you don’t need sticky sessions. Local caches are allowed, as long as they’re only caches and losing them doesn’t corrupt anything.

How do build, release and run differ, and why separate them?

Build produces an artifact (an image), a release is that artifact plus one environment’s config with an immutable id, and run starts processes from a release. Separating them lets you build once and promote the same image everywhere.

That way what runs in production is exactly what was tested, rollback is just rerunning the previous release, and nobody edits code on servers. That’s why images are tagged with the commit SHA, never latest.

A slow Redis makes every request hang. What does the “backing services” factor suggest?

A backing service can be slow, down or replaced at any time, so the app must treat that as normal: short timeouts, bounded retries, a circuit breaker, a fallback if Redis is only a cache.

Health checks need the same distinction: Redis being down doesn’t mean the process is dead, so keep it out of liveness, or Kubernetes will restart a fleet of healthy pods.

Senior

How do you deploy a Spring Boot service on Kubernetes without dropping a single request?

The app must receive SIGTERM and shut down gracefully; Kubernetes must take the pod out of the load balancer before the app closes its listener, and only send traffic to new pods once they’re ready.

  • App: exec-form ENTRYPOINT, graceful shutdown (default since Boot 3.4) with a timeout longer than the longest request, readiness failing as soon as shutdown begins.
  • Kubernetes: a preStop sleep of a few seconds, terminationGracePeriodSeconds longer than preStop plus drain time, a rolling update with maxUnavailable: 0 and a meaningful readiness probe.
  • Workers: don’t commit offsets or ack until done, and keep jobs idempotent so reruns are safe.
Where should database migrations run when you have many replicas and rolling updates?

I prefer a separate Job from the same image before rollout, with an account that has DDL rights. More important than where: migrations must be backward compatible via expand/contract.

A separate Job means a failed migration blocks the rollout and the app only needs DML. Running at startup is simple and Flyway’s lock prevents double runs, but a long migration makes pods miss their startup probe. Expand/contract matters because during a rolling update old and new pods run against the new schema together.

Which parts of twelve-factor do you think are outdated or missing?

The spirit holds, but config and logs need a broader reading, and health checks, service-to-service security, API contracts and resilience to slow backing services are missing.

Config isn’t just environment variables but also Secrets mounted as files and secret managers with rotation; logs have grown into structured telemetry including metrics and traces. Kubernetes now handles process management, so the app’s job is mostly to stay stateless, keep config external and handle its lifecycle properly.

Someone adds @Scheduled to a service running 6 replicas. What do you ask in review?

First: the job will run 6 times; is that acceptable? Then idempotency, shutdown and monitoring.

  • If not acceptable: move it to a CronJob or a one-replica worker, or use a distributed lock like ShedLock.
  • Is the job idempotent, since even with a lock an expired lease or a retry can make runs overlap?
  • Does a long run block graceful shutdown, and if the pod is killed halfway, does the next run pick up correctly?
  • Are there metrics and alerts for when the job fails or doesn’t run?

Useful phrases for interviews

  • “We build the image once and promote the same artifact from staging to production.”
  • “Config that varies between deploys comes from the environment; secrets are mounted from a secret manager.”
  • “Our services are stateless, so any pod can serve any request and we don’t need sticky sessions.”
  • “On SIGTERM the app fails its readiness check, drains in-flight requests, and then exits.”
  • “We scale out by adding processes, and each process type, web or worker, scales on its own.”
  • “Logs go to stdout as structured JSON, and the platform decides where they’re shipped.”
  • “Migrations run as a one-off Job from the same image, and they’re always backward compatible.”
  • “Testcontainers gives us dev/prod parity: the tests run against the same PostgreSQL version as production.”

References


Notes based on 12factor.net and practical experience, rewritten in my own words.