02 - Sviluppo e rilascio

Guida iniziale · Architettura

L'autonomia riguarda i rilasci ordinari dei componenti già registrati. Jacopo e Lorenzo possono sviluppare servizi diversi e riusare la stessa procedura. Il primo onboarding e le variazioni di risorse o permessi restano un lavoro coordinato fra loro; non diventano configurazioni cloud nascoste nel servizio.

Chi prepara cosa

Responsabile	Cosa mantiene
Sviluppatore del servizio	Codice, Dockerfile, script di build/test, dipendenze fissate, manifest, hook e migrazioni. Prova il servizio localmente e dichiara risorse/accessi necessari.
Jacopo e Lorenzo, per l'onboarding	Scelta del profilo già supportato, cataloghi Terraform, identità e grant minimi, baseline SQL, prima creazione, contratti applicati e kit consegnato.
Infrastruttura comune	Ricette Cloud Build, verifica degli artefatti, strumenti di release/approvazione/recupero e moduli Terraform riutilizzabili.
Operatore e approvatore abilitati	Eseguono la procedura con il proprio account, verificano il candidato, approvano esplicitamente e conservano le ricevute. I gruppi possono avere oggi le stesse persone; i ruoli restano distinti.

GitHub conserva le modifiche revisionate. Cloud Build esegue i controlli e pubblica immagini identificate dal digest; Artifact Registry le conserva. Cloud Deploy rende e distribuisce i manifest dopo l'approvazione, con la migrazione separata quando prevista. Un cloudbuild.yaml applicativo non può sostituire il percorso privilegiato comune o assegnarsi nuovi permessi.

Terraform prepara infrastruttura e accessi; Cloud Deploy gestisce le revisioni applicative. Non devono gestire contemporaneamente la stessa specifica Service/Job. I root bootstrap e stage hanno state distinti, non distribuiti agli sviluppatori.

Prima registrazione e release ordinarie

Una volta per il componente: concordare repository/profilo, destinazione, identità, risorse e capacità. Applicare i piani necessari, preparare SQL, adattare i manifest ai contratti e completare il primo rilascio. Dopo la prima creazione si chiude la finestra IAM e si consegna il kit per i workload esistenti. Onboarding.

A ogni release ordinaria: codice e test nella repository del servizio, modifica revisionata su main, poi lo stesso kit e la stessa pipeline. Nessun apply Terraform se non cambiano risorse, autorizzazioni o profilo.

1. Selezionare lo SHA revisionato di main remoto corrente. La CLI lo ricontrolla prima di pubblicare e caricare il candidato; se main avanza, predisporre un run coerente senza riscrivere gli input congelati.
2. Avviare il publisher e approvare esplicitamente la build Cloud Build.
3. Preparare candidato e bundle immutabili; approvare separatamente la build che verifica gli artefatti, crea la release e rende i manifest.
4. Ispezionare il rollout e approvarlo con il comando dedicato sotto.
5. Verificare rollout, Service Ready, migrazione, accessi e segnali previsti.

Access e Farm usano migratore separato → successo → backend. Il Job applica solo le versioni mancanti; un errore impedisce il nuovo backend, senza spegnere automaticamente quello già attivo. Un Job generico invece non viene eseguito implicitamente a ogni release: registrazione, avvio e scheduling sono distinti.

Kit e approvazione manuale

Il kit contiene i tre contratti delivery, runtime, operator e gli strumenti corrispondenti. Si verifica da un checkout fidato con l'hash ricevuto separatamente; run, ricevute, credenziali e ambiente Python restano fuori dal kit. Preparazione e verifica.

stage_release.py init/advance/status prepara e legge la release; non approva implicitamente build o rollout. Gli eventi automatici sono spenti nel percorso configurato. Per l'approvazione Cloud Deploy, l'approvatore usa esplicitamente:

python -B tools/stage_approval.py inspect --run-dir <run> --account <email-aziendale> --output <snapshot.json>
python -B tools/stage_approval.py approve --run-dir <run> --account <email-aziendale> --snapshot <snapshot.json> --coordinated-with-team

L'approvatore usa la propria identità Google, distinta dall'operatore che ha preparato il run; non si riscrive l'account nel ledger. IAM decide se può approvare. inspect e approve devono usare lo stesso account. La CLI rifiuta configurazioni SDK con impersonazione o sostituzione delle credenziali: l'approvatore resta identificato con il proprio account aziendale. Il tool verifica candidato e render, stato PENDING_APPROVAL/NEEDS_APPROVAL, snapshot recente e inventario dello stesso target nella stessa pipeline. Rifiuta rollout attivi o incerti e candidati più recenti non scartati; più recente significa rollout Cloud Deploy, non un commit Git o un bundle solo preparato. Rilegge lo stato prima della richiesta e registra l'intento per riconciliare una risposta persa. Cloud Build conserva il proprio gate esterno.

Sono controlli preventivi, non un lock distribuito o una transazione tra operatori. I permessi IAM consentono ancora altri canali, compresa la console: il tool non impedisce quel bypass. Il team mantiene un solo rollout in esecuzione per componente/ambiente e concorda quale candidato usare. --coordinated-with-team attesta tale accordo; non dimostra che l'altro operatore sia tecnicamente bloccato.

Un aggiornamento del kit serve per usare nuovi strumenti o contratti. Non sostituire i JSON di un run già iniziato né attribuire ai vecchi kit comandi che non contengono.

Ripresa, retry e ritorno al comportamento precedente

• Ripresa: conservare il run e usare status/advance; un avvio ambiguo si riconcilia prima di adopt. Non cancellare il ledger per chiedere una seconda build.
• Retry dello stesso rollout: stage_recovery.py inspect/retry mantiene gli stessi artefatti e ricontrolla target, job fallito e assenza di conflitti. Richiede il riscontro dell'Operation/Execution precedente e l'accordo del team. Il tempo trascorso o una lista vuota non provano che il lavoro sia fermo.
• Ripristino applicativo nella v1: una nuova fix o revert del codice su main, compatibile con lo schema corrente e senza eliminare le migrazioni già applicate, passa dalla normale pipeline. Non si seleziona uno SHA vecchio e non si usa il rollback Cloud Deploy a una vecchia release. Nessuna down-migration o restore dell'istanza condivisa è implicito nel rilascio.

SeaORM rifiuta una versione applicata nel database che il migratore non conosce. È una protezione già presente; i test di regressione la rendono esplicita. Perciò un revert dell'intera repository che cancella vecchie migrazioni non è una strategia valida. Schema e compatibilità.

Se il primo deploy fallisce prima di creare il workload, Jacopo e Lorenzo riconciliano risorse e prima-creazione IAM. Un 404/403 non autorizza un retry cieco. Se esiste solo il Job migratore, gli servono i grant nominali prima del retry. Un nuovo kit vale per i run successivi; la storia del run originale resta immutata.

Le prove esistenti coprono release Access/Farm, retry isolato SQL-free, SQL e S2S. Il nuovo guard di approvazione ha test propri e mantiene i limiti di concorrenza sopra indicati; non richiede di rompere nuovamente i servizi online. Runbook · Collaudi.