Panoramica dei record delle decisioni sull'architettura

Last reviewed 2024-08-16 UTC

Per spiegare perché i team dell'infrastruttura o delle applicazioni fanno determinate scelte di progettazione, puoi utilizzare i record delle decisioni di architettura (ADR). Questo documento spiega quando e come utilizzare i record ADR durante la creazione e l'esecuzione di applicazioni su Google Cloud.

Un ADR acquisisce le opzioni chiave disponibili, i requisiti principali che guidano una decisione e le decisioni di progettazione stesse. Spesso memorizzi le ADR in un file Markdown vicino al codebase pertinente alla decisione. Se qualcuno ha bisogno di comprendere il contesto di una decisione architettonica specifica, ad esempio perché 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. Il report ADR ti aiuta a comprendere lo stato attuale e a risolvere i problemi. Gli ADR creano anche una raccolta di decisioni ingegneristiche per aiutare le scelte e le implementazioni future.

Quando utilizzare i report ADR

Utilizzi i report ADR per monitorare le aree chiave che ritieni importanti per la tua implementazione. Il tuo ADR potrebbe includere le seguenti categorie:

  • Scelte di prodotti specifici, ad esempio la scelta tra Pub/Sub e Cloud Tasks.
  • Opzioni e configurazioni specifiche del prodotto, come l'utilizzo di cluster GKE regionali con Ingress multi-cluster per applicazioni a disponibilità elevata.
  • Indicazioni architetturali generali, ad esempio best practice per i manifest Dockerfile.

Alcuni esempi specifici che potrebbero spingerti a creare una ADR potrebbero riguardare le seguenti scelte:

  • Come e perché configurare l'alta disponibilità (HA) per le istanze Cloud SQL?
  • Qual è il tuo approccio all'uptime dei cluster GKE? Utilizzi i cluster regionali? Utilizzi le versioni canary? Qual è il motivo?

Man mano che valuti i prodotti da utilizzare, l'ADR ti aiuta a spiegare ogni tua decisione. Puoi rivedere la decisione di architettura man mano che il team evolve e impara di più sullo stack e vengono prese o modificate decisioni aggiuntive. Se apporti modifiche, includi la decisione precedente e il motivo della modifica. Questa cronologia tiene traccia di come l'architettura è cambiata con l'evolversi delle esigenze aziendali o di dove si trovano nuovi requisiti tecnici o soluzioni disponibili.

I seguenti prompt ti aiutano a sapere quando creare le ADR:

  • Quando hai una domanda o una sfida tecnica e non esiste una base esistente per una decisione, ad esempio una soluzione consigliata, una procedura operativa standard, un progetto o una base di codice.
  • Quando tu o il tuo team offrite una soluzione che non è documentata in un luogo accessibile al team.
  • Quando sono disponibili due o più opzioni di ingegneria e vuoi documentare i tuoi pensieri e i motivi alla base della selezione.

Quando scrivi una descrizione audio, è utile tenere a mente i potenziali lettori. I lettori principali sono i membri del team che lavorano alla tecnologia trattata nella RPD. Gruppi più ampi di potenziali lettori della proposta di decisione architettonica potrebbero includere team adiacenti che vogliono comprendere le tue decisioni, come i team di architettura e sicurezza.

Tieni inoltre presente che l'applicazione potrebbe cambiare proprietari o includere nuovi membri del team. Un ADR aiuta i nuovi collaboratori a comprendere il contesto delle scelte ingegneristiche effettuate. Inoltre, un ADR semplifica la pianificazione delle modifiche future.

Formato di un ADR

Un ADR tipico include un insieme di capitoli. Le tue ADR devono contribuire a registrare ciò che ritieni importante per l'applicazione e la tua organizzazione. Alcune ADR potrebbero essere lunghe una pagina, mentre altre richiedono una spiegazione più lunga.

Il seguente esempio di struttura di una proposta di decisione architettonica mostra come potresti formattare una proposta di decisione architettonica per includere le informazioni importanti per il tuo ambiente:

  • Autori e 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 ciascuna decisione per mostrare quando è stata presa la scelta.

Come funzionano gli ADR

Gli ADR funzionano meglio quando ingegneri, sviluppatori o proprietari di applicazioni possono accedere facilmente alle informazioni che contengono. Quando hanno una domanda sul perché qualcosa viene fatto in un certo modo, possono consultare il documento ADR per trovare la risposta.

Per rendere accessibile l'ADR, alcuni team lo 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 ingegneristica specifica, l'ADR è a disposizione per fornire risposte.

I meccanismi alternativi di risoluzione delle controversie funzionano bene nei seguenti scenari:

  • Onboarding: i nuovi membri del team possono scoprire facilmente il progetto e consultare la ADR se hanno domande mentre imparano una nuova codebase.
  • Evoluzione dell'architettura: se viene trasferito lo stack tecnologico tra i team, i nuovi proprietari possono esaminare le decisioni passate per comprendere lo stato attuale. Il team può anche rivedere le decisioni passate quando è disponibile una nuova tecnologia. Il documento ADR può aiutare i team a evitare di ripetere gli stessi punti di discussione e può fornire un contesto storico quando i team rivisitano gli argomenti.
  • Condivisione delle best practice: i team possono allinearsi sulle best practice in tutta l'organizzazione quando i documenti di decisione architetturale descrivono in dettaglio il motivo per cui sono state prese determinate decisioni e le alternative sono state scartate.

Un ADR è 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.

Conserva i tuoi ADR vicino al codice dell'applicazione, idealmente nello stesso sistema di controllo delle versioni. Man mano che apporti modifiche alla tua ADR, puoi rivedere le versioni precedenti dal controllo della versione in base alle esigenze.

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 la tua ADR in un repository di controllo del codice sorgente, ma rispecchiare le decisioni chiave in una wiki più accessibile.

Passaggi successivi