Per spiegare perché i team di infrastruttura o di applicazioni fanno determinate scelte di progettazione, puoi utilizzare i record delle decisioni sull'architettura (ADR). Questo documento spiega quando e come utilizzare gli ADR durante la creazione e l'esecuzione di applicazioni su Google Cloud.
Un ADR acquisisce le opzioni chiave disponibili, i requisiti principali che determinano una decisione e le decisioni di progettazione stesse. Spesso memorizzi le ADR in un file Markdown vicino al codice di base pertinente alla decisione. Se qualcuno deve comprendere il contesto di una decisione di architettura specifica, ad esempio il motivo per cui utilizzi un cluster Google Kubernetes Engine (GKE) regionale, può esaminare l'ADR e poi il codice associato.
Gli ADR possono anche aiutarti a eseguire applicazioni e servizi più affidabili. L'ADR ti aiuta a comprendere la tua situazione attuale e a risolvere i problemi. Gli ADR creano anche una raccolta di decisioni di ingegneria per supportare le scelte e i deployment futuri.
Quando utilizzare gli annunci adattabili della rete di ricerca
Utilizzi gli ADR per monitorare le aree chiave che ritieni importanti per il tuo deployment. Le seguenti categorie potrebbero essere presenti nei tuoi annunci dinamici della rete di ricerca:
- Scelte di prodotti specifici, ad esempio la scelta tra Pub/Sub e Cloud Tasks.
- Opzioni e configurazioni di prodotti specifici, ad esempio l'utilizzo di cluster GKE regionali con Ingress multi-cluster per applicazioni ad alta disponibilità.
- Indicazioni generali sull'architettura, ad esempio best practice per i manifest di Dockerfile.
Ecco alcuni esempi specifici che potrebbero richiedere la creazione di una RPD:
- Come e perché configurare l'alta disponibilità (HA) per le tue istanze Cloud SQL?
- Come gestisci il tempo di attività dei cluster GKE? Utilizzi cluster regionali? Utilizzi le release canary? Perché sì o perché no?
Quando valuti i prodotti da utilizzare, l'ADR ti aiuta a spiegare ogni decisione. Puoi rivedere l'ADR man mano che il team si evolve e apprende di più sull'evoluzione della pila e vengono prese o modificate altre decisioni. Se apporti modifiche, includere la decisione precedente e il motivo della modifica. Questa cronologia registra come l'architettura è cambiata in base all'evoluzione delle esigenze aziendali o se esistono nuovi requisiti tecnici o soluzioni disponibili.
I seguenti prompt ti aiutano a capire quando creare gli annunci dinamici della rete di ricerca:
- Quando hai un problema o una domanda tecnica e non esiste una base per prendere una decisione, ad esempio una soluzione consigliata, una procedura operativa standard, un blueprint o una base di codice.
- Quando tu o il tuo team offrite una soluzione non documentata in un luogo accessibile al team.
- Quando sono disponibili due o più opzioni di progettazione e vuoi documentare le tue opinioni e i motivi alla base della selezione.
Quando scrivi un ADR, è utile tenere a mente i potenziali lettori. I lettori principali sono i membri del team che si occupano della tecnologia coperta dall'ADR. Gruppi più ampi di potenziali lettori dell'ADR potrebbero includere team adiacenti che vogliono comprendere le tue decisioni, ad esempio i team di architettura e sicurezza.
Tieni inoltre presente che l'applicazione potrebbe cambiare proprietario o includere nuovi membri del team. Un ADR aiuta i nuovi collaboratori a comprendere il contesto delle scelte di ingegneria che sono state fatte. Un ADR semplifica anche la pianificazione delle modifiche future.
Formato di un ADR
Un ADR tipico include una serie di capitoli. Gli ADR dovrebbero aiutarti a catturare ciò che ritieni importante per l'applicazione e la tua organizzazione. Alcuni ADR possono essere costituiti da una sola pagina, mentre altri richiedono una spiegazione più lunga.
Il seguente esempio di schema di ADR mostra come puoi formattare un ADR in modo da includere le informazioni importanti per il tuo ambiente:
- Autori e il team
- Contesto e problema che vuoi risolvere
- Requisiti funzionali e non funzionali che vuoi soddisfare
- Potenziale Critical User Journey (CUJ) interessato dalla decisione
- Panoramica delle opzioni principali
- La tua decisione e i motivi alla base della scelta accettata
Per tenere traccia delle decisioni, puoi includere un timestamp per ogni decisione per indicare quando è stata effettuata la scelta.
Come funzionano gli annunci adattabili della rete di ricerca
Gli ADR funzionano al meglio quando ingegneri, sviluppatori o proprietari di applicazioni possono accedere facilmente alle informazioni in essi contenute. Quando hanno una domanda sul perché qualcosa viene fatto in un determinato modo, possono consultare l'ADR per trovare la risposta.
Per rendere accessibile l'ADR, alcuni team la ospitano in una wiki centrale accessibile anche ai proprietari di attività, anziché nel repository di controllo del codice sorgente. Quando qualcuno ha una domanda su una decisione di ingegneria specifica, l'ADR è lì per fornire risposte.
Gli annunci adattabili alla rete di ricerca funzionano bene nei seguenti scenari:
- Onboarding: i nuovi membri del team possono acquisire facilmente informazioni sul progetto e possono esaminare l'ADR in caso di domande durante l'apprendimento di un nuovo codebase.
- Evoluzione dell'architettura: se avviene un trasferimento della tecnologia tra i team, i nuovi proprietari possono rivedere le decisioni passate per comprendere lo stato attuale. Il team può anche rivedere le decisioni prese in passato quando è disponibile una nuova tecnologia. L'ADR può aiutare i team a evitare di ripetere gli stessi punti di discussione e a fornire un contesto storico quando i team ripercorrono gli argomenti.
- Condivisione delle best practice: i team possono allinearsi alle best practice dell'intera organizzazione quando gli ADR descrivono nel dettaglio il motivo per cui sono state prese determinate decisioni e perché sono state escluse le alternative.
Un ADR viene spesso scritto in Markdown per mantenerlo leggero e basato su testo. I file Markdown possono essere inclusi nel repository di controllo del codice sorgente con il codice dell'applicazione.
Memorizza gli ADR vicino al codice dell'applicazione, idealmente nello stesso sistema di controllo della versione. Man mano che apporti modifiche all'ADR, puoi esaminare le versioni precedenti dal controllo del codice sorgente, se necessario.
Puoi anche utilizzare un altro mezzo, ad esempio un documento Google condiviso o una wiki interna. Queste posizioni alternative potrebbero essere più accessibili agli utenti che non fanno parte del team dell'ADR. Un'altra opzione è creare l'ADR in un repository di controllo del codice, ma rispecchiare le decisioni chiave in una wiki più accessibile.
Passaggi successivi
- Il Centro architetture di Google Cloud e il framework dell'architettura forniscono ulteriori indicazioni e best practice.
- Per alcune aree che potrebbero essere incluse nel tuo ADR, consulta Pattern per app scalabili e resilienti.