Per spiegare perché i team dedicati all'infrastruttura o alle applicazioni effettuano determinate attività di progettazione puoi usare i record decisionali dell'architettura (ADR). Questo documento spiega quando e come utilizzare gli ADR durante la creazione e l'esecuzione di applicazioni su Google Cloud.
Un ADR cattura le opzioni chiave disponibili, i requisiti principali che determinano 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 background di una specifica decisione architetturale, ad esempio perché usa un cluster Google Kubernetes Engine (GKE) a livello di regione, 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 lo stato attuale e a risolvere eventuali problemi. Gli ADR creano anche una raccolta di decisioni di ingegneria per supportare le scelte e i deployment futuri.
Quando utilizzare gli annunci dinamici della rete di ricerca
Utilizzi le ADR per monitorare le aree chiave che ritieni importanti per il tuo e deployment continuo. Gli ADR potrebbero contenere le seguenti categorie:
- Scelte specifiche del prodotto, 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à.
- Linee guida generali sull'architettura, ad esempio le best practice per Dockerfile e i file manifest.
Alcuni esempi specifici che potrebbero richiedere la creazione di un ADR potrebbero essere le seguenti opzioni:
- Come e perché configuri l'alta disponibilità (HA) per il tuo Cloud SQL di Compute Engine?
- Come gestisci il tempo di attività dei cluster GKE? Usi a livello di regione? Utilizzi le versioni canary? Perché sì o perché no?
Durante la valutazione dei prodotti da usare, l'ADR aiuta a spiegare ogni prendono le loro decisioni. Puoi rivedere l'ADR man mano che il team si evolve e apprende di più sulle e altre decisioni vengono prese o modificate. 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 le ADR:
- Se hai una domanda o un problema di natura tecnica e non di base per una decisione, ad esempio una soluzione consigliata, un'operazione procedura, progetto o codebase.
- 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. Il principale I lettori sono membri del team che si occupa 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
Una tipica funzione ADR 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 struttura ADR mostra come formattare un ADR in modo che includa le informazioni importanti per il tuo ambiente:
- Autori e team
- Contesto e problema che vuoi risolvere
- Requisiti funzionali e non funzionali da 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 le ADR
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 lo ospitano in un wiki centrale che accessibili ai proprietari delle attività, invece che nel loro repository di controllo del codice sorgente. Quando qualcuno ha una domanda su una specifica decisione di progettazione, l'ADR viene disponibili per fornire risposte.
Gli annunci adattabili alla rete di ricerca funzionano bene nei seguenti scenari:
- Operazioni preliminari: i nuovi membri del team possono ottenere facilmente informazioni sul progetto e possono rivedere l'ADR se hanno domande durante l'apprendimento codebase.
- Evoluzione dell'architettura: in caso di trasferimento dello stack tecnologico tra i team, i nuovi proprietari possono rivedere le decisioni passate per comprendere lo stato attuale. Il team può anche rivedere le decisioni passate in caso di nuove la tecnologia a loro disposizione. 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 è spesso scritto in Annotazione per mantenerlo leggero e basato su testo. I file di Markdown possono essere inclusi nella repository di controllo dei file sorgente con il codice della tua 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 riflettere 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.