Panoramica dei record decisionali dell'architettura

Last reviewed 2023-04-11 UTC

Per spiegare perché i team dell'infrastruttura o delle applicazioni fanno determinate scelte di progettazione, puoi utilizzare i record di decisione 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 acquisisce le opzioni chiave disponibili, i requisiti principali che determinano una decisione e le decisioni di progettazione stesse. Spesso gli ADR vengono memorizzati in un file Markdown vicino al codebase pertinente a quella decisione. Se qualcuno ha bisogno di comprendere il contesto di una specifica decisione sull'architettura, ad esempio perché utilizzi un cluster Google Kubernetes Engine (GKE) a livello di regione, può esaminare l'ADR e il codice associato.

Gli ADR possono anche aiutarti a eseguire applicazioni e servizi più affidabili. L'ADR ti aiuta a capire lo stato attuale e a risolvere eventuali problemi. Gli ADR creano anche una raccolta di decisioni ingegneristiche per aiutare le scelte decisionali e i deployment futuri.

Quando utilizzare gli ADR

Gli ADR vengono utilizzati per monitorare le aree chiave che ritieni importanti per l'implementazione. Le seguenti categorie potrebbero essere incluse negli ADR:

  • Scelte di prodotti specifici, ad esempio Pub/Sub e Pub/Sub Lite.
  • Opzioni e configurazioni di prodotto specifiche, come l'utilizzo di cluster GKE a livello di regione con Ingress multi-cluster per applicazioni ad alta disponibilità.
  • Linee guida generali sull'architettura, ad esempio le best practice per i manifest Dockerfile.

Ecco alcuni esempi specifici che potrebbero richiedere la creazione di un ADR per 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 cluster regionali? Utilizzi le versioni canary? Perché sì o perché no?

Durante la valutazione dei prodotti da utilizzare, l'ADR aiuta a spiegare ogni decisione. Puoi rivedere l'ADR man mano che il team si evolve e apprende più informazioni sullo stack e vengono prese o modificate ulteriori decisioni. Se apporti modifiche, includi la decisione precedente e il motivo della modifica. Questa storia conserva un registro di come l'architettura è cambiata con l'evolversi delle esigenze aziendali o dove sono presenti nuovi requisiti tecnici o soluzioni disponibili.

Le seguenti indicazioni ti aiutano a capire quando creare gli ADR:

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

Quando scrivi un ADR, è utile tenere in considerazione i potenziali lettori. I lettori principali sono i membri del team che si occupa della tecnologia prevista 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 presente che l'applicazione potrebbe modificare i proprietari o includere nuovi membri del team. Un ADR aiuta i nuovi collaboratori a comprendere il background delle scelte ingegneristiche effettuate. L'ADR semplifica anche la pianificazione dei cambiamenti futuri.

Formato di un ADR

Un tipico ADR include una serie di capitoli. Gli ADR dovrebbero aiutarti ad acquisire 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 ADR mostra come formattare un ADR per includere le informazioni importanti per il tuo ambiente:

  • Autori e il team
  • Contesto e problema da risolvere
  • Requisiti funzionali e non funzionali da rispettare
  • Potenziale impatto critico dell'utente (CUJ) sulle decisioni
  • 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 in modo da mostrare quando è stata presa la scelta.

Come funzionano gli ADR

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

Per rendere accessibile l'ADR, alcuni team lo ospitano in un wiki centrale accessibile anche ai proprietari delle aziende, anziché nel loro repository di controllo del codice sorgente. Quando qualcuno ha una domanda su una specifica decisione di ingegneria, l'ADR è a disposizione per fornire le risposte.

Gli ADR funzionano bene nei seguenti scenari:

  • Onboarding: i nuovi membri del team possono ottenere facilmente informazioni sul progetto e rivedere l'ADR in caso di domande, mentre esaminano il codice dell'applicazione o altre implementazioni.
  • Trasferimento della proprietà: in caso di trasferimento dello stack tecnologico tra i team, i nuovi proprietari possono rivedere le decisioni passate per comprendere lo stato attuale. L'ADR può anche aiutare a evitare di ripetere gli stessi punti di discussione o a rivedere gli argomenti in futuro con conoscenza del contesto storico.
  • Allineamento: i team possono allinearsi alle best practice dell'organizzazione quando le ADR descrivono nel dettaglio perché sono state prese determinate decisioni e le alternative sono state decise contro.

Un ADR è spesso scritto in Markdown per mantenerlo leggero e basato su testo. I file di markdown possono essere inclusi nel repository del controllo del codice sorgente con il codice dell'applicazione.

Memorizza gli ADR vicino al codice dell'applicazione, possibilmente 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 un wiki interno. Queste sedi 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 sorgente, ma di replicare le decisioni chiave in un wiki più accessibile.

Passaggi successivi