Twelve Factor — Cheat Sheet

Tag: twelve-factor, devops, cloud-native, microservices, architecture, deployment, docker

Livello: intermedio

TL;DR: Metodologia in dodici principi per creare applicazioni SaaS e cloud-native resilienti, portabili, scalabili orizzontalmente e pronte per il deploy continuo.

Concetti chiave

I. Codebase: un solo repository tracciato su version control, molti deploy attivi contemporaneamente (prod, staging, dev).

II. Dependencies: isolamento e dichiarazione esplicita di tutte le dipendenze; nessun pacchetto implicito a livello di sistema.

III. Config: separazione rigorosa della configurazione dal codice; memorizzazione delle variabili di configurazione nell'ambiente (ENV).

IV. Backing services: database, code e servizi terzi trattati come risorse agganciabili tramite URL o credenziali configurabili.

V. Build, release, run: rigida separazione tra fase di build (artefatto), release (artefatto + config) ed esecuzione (run).

VI. Processes: l'applicazione gira come uno o più processi stateless e share-nothing; stato persistito su backing services.

VII. Port binding: l'applicazione è autonoma ed espone i propri servizi direttamente tramite binding a una porta HTTP/TCP.

VIII. Concurrency: scalabilità orizzontale tramite il modello a processi; diversificazione tra web worker e background worker.

IX. Disposability: processi veloci ad avviarsi e pronti a terminare con grazia gestendo segnali SIGTERM.

X. Dev/prod parity: massima convergenza tra sviluppo e produzione per tempi, persone e tecnologie adottate.

XI. Logs: flussi continui di eventi trattati come event stream e scritti su stdout/stderr senza routing interno.

XII. Admin processes: compiti di manutenzione, migrazioni database e script one-off eseguiti nello stesso ambiente del codice applicativo.

Domande tipiche e risposte pronte

Q: Perché il fattore III vieta di memorizzare le configurazioni in file versionati?R: La configurazione varia tra ambienti diversi (dev, staging, prod), mentre il codice resta immutato; versionarla rischia leak di credenziali e impedisce deploy indipendenti.

Q: Come si gestisce la persistenza se i processi devono essere stateless (fattore VI)?R: Qualsiasi dato da mantenere nel tempo o condividere tra richieste viene delegato a datastore esterni o storage distribuiti (PostgreSQL, Redis, S3).

Q: Cosa significa "disposability" in ambiente cloud o containerizzato?R: Significa che le istanze si avviano in secondi e intercettano correttamente il SIGTERM, completando le richieste in volo prima di arrestarsi senza corrompere dati.

Insidie e errori comuni

Scrivere file temporanei o memorizzare sessioni utente su filesystem locale anziché su Redis o database.

Incorporare file di configurazione con credenziali di produzione dentro immagini Docker o pacchetti di build.

Usare server applicativi pesanti gestiti esternamente (Tomcat, IIS) invece di un web server integrato con port binding.

Usare SQLite o engine differenti in sviluppo rispetto al database reale (PostgreSQL/MySQL) in produzione, rompendo la parità dev/prod.

Gestire la rotazione o l'archiviazione dei file di log all'interno dell'app anziché demandarla all'infrastruttura di runtime.

Snippet e comandi

# Esempio: esecuzione one-off di migrazioni nello stesso environment del release (Fattore XII)
docker run --rm --env-file .env.production myapp:release-v1.4 npm run db:migrate

TypeScript

// Esempio: graceful shutdown su SIGTERM (Fattore IX)
process.on('SIGTERM', () => {
  server.close(() => {
    db.disconnect();
    process.exit(0);
  });
});

Da ripassare

[ ] Meccanismo di propagazione e intercettazione segnali POSIX (SIGTERM, SIGINT) in Docker e Kubernetes

[ ] Pattern di separazione tra artefatto immutabile e configurazione runtime

[x] Configurazione tramite variabili di ambiente (process.env)

Riferimenti

The Twelve-Factor App (Adam Wiggins, 12factor.net)

Jarvis Interviews
Jarvis