Guida completa

Guida condivisa per Jacopo e Lorenzo · aggiornata all'11 novembre 2026.

Scarica il PDF completo, con introduzione e capitoli 01–12.

Il PDF è la fotografia precedente all'allineamento della configurazione Farm; le integrazioni successive sono nelle schede Markdown 03, 05 e 11.

Questa introduzione e le dodici schede sono la sorgente completa versionata della guida. Le sintesi dei collaudi sono condivisibili; le ricevute tecniche complete restano nell’archivio operatore, senza pubblicare state o credenziali.

La base cloud esiste: rilascio Access e recupero SQL-free sono collaudati. Farm ha completato rollout, verifiche SQL e prova privata Platform→Farm con dinieghi e cleanup. Il controllo dell'ordine viene esplicitato nella CLI di approvazione; restano i controlli operativi descritti nel piano. Console e il dettaglio di tutti i futuri sistemi non sono prerequisiti.

Come funziona

Google Cloud ospita risorse e applicazioni. Terraform descrive e configura infrastruttura e permessi. GitHub conserva il codice. Cloud Build lo controlla e costruisce le immagini. Cloud Deploy distribuisce gli artefatti approvati sullo stage, eseguendo le migrazioni previste.

Nelle prove di rete, Platform→Farm indica il percorso dal progetto moonitoring-platform-stage al progetto moonitoring-farm-stage. Non esiste un servizio chiamato Platform da distribuire: i nomi e i livelli sono distinti.

L'autonomia riguarda le release ordinarie dei componenti già registrati. Jacopo e Lorenzo coordinano il primo onboarding e le nuove risorse/autorizzazioni. Lo sviluppatore mantiene Dockerfile, script, test, manifest e migrazioni; le ricette Cloud Build e i controlli privilegiati restano comuni.

Per un nuovo componente si dichiarano una volta destinazione, identità, risorse e accessi. I successivi aggiornamenti del codice riusano la pipeline. Terraform cambia quando servono nuove risorse o autorizzazioni, non per ogni versione applicativa.

Il manifest stage è il riferimento per l'esecuzione; il codice dichiara i propri requisiti. Quando questi cambiano, aggiorniamo insieme configurazione e accessi. Il nuovo controllo comune parte da Farm e blocca configurazioni mancanti prima del rilascio; la sua adozione sugli altri sistemi è esplicita, non retroattiva.

Cosa definiamo adesso

Adesso, come base comune	Durante lo sviluppo del servizio
Confini dei sistemi già noti e risorse condivise	Componenti effettivi, API, schema e migrazioni
Modello breve per dichiarare un componente	Compilazione del modello con i suoi bisogni reali
Profili riusabili di esecuzione, accesso e rilascio	Risorse e permessi specifici prima del primo deploy
Procedura e test comuni	Test del comportamento applicativo

Non occorre completare oggi le schede Farm/Releases o distribuire tutti i servizi. La configurazione autorevole rimane nei cataloghi Terraform e nei manifest; la scheda spiega le decisioni, senza duplicare tutto il codice.

Punto attuale e ultimi passi

Sono già predisposti progetti, rete, Cloud SQL, database e identità iniziali. Access ha provato backend, migrazione e telemetria. I moduli comuni esistono, ma alcuni profili hanno soltanto test locali.

Decisioni dell'11 novembre: una delivery per componente con ID di al massimo 11 caratteri e un file deploy/runtime-requirements/<delivery-id>.json per delivery (03); un ruolo SQL per componente, controllo dello schema all'avvio e nessun DDL fuori dal migratore (08); audit su un topic per sistema e segreti con il prefisso del sistema (11). I nomi di ruoli e delivery si fissano insieme prima dei baseline. Application Delivery.

Aggiornamento Farm del 10 novembre: le modifiche applicative e infrastrutturali sono su main; il publisher comune ha prodotto le due immagini. La baseline del database è stata applicata conservando la vecchia fixture e verificando il catalogo Access invariato; l'amministratore SQL temporaneo è stato rimosso. Login privato e isolamento SQL sono verificati prima e dopo le migrazioni; il primo rollout è riuscito. La finestra IAM è chiusa con grant sui workload nominati. I cinque casi S2S e il cleanup sono riusciti; metriche e una traccia correlata sono ricevute. Il migratore rieseguito non ha trovato migrazioni mancanti, con i limiti di evidenza indicati nella scheda. Stato e prossima sequenza.

Aggiornamento operativo del 9 novembre: il kit Access ha completato rilascio ordinario, migrazione prima del backend, ripresa senza duplicazioni e verifica di richieste/telemetria. È riuscito anche il retry reale di una fixture senza SQL, con lo stesso candidato approvato; sonde e cleanup sono conclusi. Il nuovo comando di approvazione verifica ordine e conflitti prima del POST; i suoi test sono distinti dai rilasci storici. Lorenzo verifica le proprie azioni al normale primo uso: una sessione dedicata non è un prerequisito. Rilasci Access · Recovery isolato.

La base comune versione 1 è a questo punto:

1. Standard allineato: mantenere coerenti modello, profili supportati ed esempi verificabili.
2. Kit e procedura pronti: rilascio ordinario e retry SQL-free sono verificati, con cleanup concluso. Il nuovo comando esplicito di approvazione è implementato e testato; il kit aggiornato è verificato offline. Il primo uso reale del nuovo comando sarà registrato al prossimo rilascio, senza ripetere appositamente i deploy già riusciti. Ogni operatore verifica le proprie azioni nel normale utilizzo.
3. Secondo sistema verificato: Farm ha superato rollout, accessi SQL, S2S e cleanup; il kit successivo è pronto. Le nuove API riusano questo profilo, verificando i propri grant e il primo rilascio. Non serve completare il prodotto Farm. Secondo sistema.
4. Da completare per la chiusura operativa: attivare e provare gli allarmi, verificare limiti e ricezione notifiche, eseguire il restore isolato della scheda 12. Il recupero v1 è definito come fix/revert compatibile su main, preservando le migrazioni applicate; retry e ripristino del database restano operazioni diverse.

La consegna iniziale rende autonomo il rilascio dei profili API accettati. Per SQL comprende il percorso backend + migratore separato: il backend modifica i dati, il migratore modifica la struttura. Un nuovo sistema con questa combinazione può riusare il percorso, dopo la propria registrazione e verifica.

Un secondo componente che scrive nello stesso schema, per esempio un consumer di Access, usa i profili runtime SQL dell'11 novembre: delivery propria, ruolo SQL proprio, nessun migratore. Il primo collaudo dal vivo avviene con i rilasci dopo il reset dello stage. Le regole per schema e componenti SQL spiegano come.

Readonly, eventi e Job restano attività da completare per profilo, nella sezione separata delle estensioni; non bloccano i quattro passi della consegna iniziale. I primi deploy controllati servono proprio a collaudare nuove capacità. Console/staff web e produzione restano consegne distinte. “Versione 1” stabilizza un contratto estendibile, non certifica ogni requisito futuro.

Percorso di lettura

Documento	Risponde a
01 — Architettura	Dove sono le risorse e chi le gestisce?
02 — Sviluppo e rilascio	Come arriva un commit sullo stage?
03 — Modello del servizio	Che cosa compiliamo e quando?
04 — Accessi	Chi può fare cosa?
05 — Stato e prossimi passi	Che cosa è pronto e quale lavoro manca?
06 — Collaudi	Come dimostriamo che la base è pronta?
07 — Fonti	Quali prove e documenti sostengono queste informazioni?
08 — Schema e componenti SQL	Chi modifica le tabelle e come rilasciamo più componenti sullo stesso schema?
09 — Collaudo del 9 novembre	Che cosa ha funzionato davvero con il nuovo kit e quali prove restano aperte?
10 — Recovery isolato	Come abbiamo verificato il retry di un deploy fallito e quali casi non copre?
11 — Onboarding Farm	Quale componente riusiamo e cosa serve prima di metterlo online?
12 — Soglie e ripristino	Quali allarmi proponiamo e come proveremo il restore senza toccare lo stage corrente?

Questa guida distingue implementazione, applicazione e collaudo. Le prove Access restano separate dal recovery e da Farm. La doc ufficiale registra il recovery nella PR #93 e la preparazione Farm nella PR #94, entrambe unite. Il registro ufficiale conserva anche l'esito Farm; questa guida collega quei risultati alla procedura comune e alle decisioni successive, senza trasformare un aggiornamento documentale in un nuovo deploy. Le fonti distinguono commit fissati e copie locali.