Descripción general de los registros de decisión de la arquitectura

Last reviewed 2023-04-11 UTC

Para ayudarte a explicar por qué los equipos de infraestructura o aplicaciones toman ciertas decisiones de diseño, puedes usar los registros de decisiones de la arquitectura (ADR). En este documento, se explica cuándo y cómo usar ADR mientras compilas y ejecutas aplicaciones en Google Cloud.

Un ADR captura las opciones clave disponibles, los requisitos principales que generan una decisión y las decisiones de diseño en sí mismas. A menudo, los ADR se almacenan en un archivo Markdown cerca de la base de código relevante para esa decisión. Si alguien necesita información sobre los antecedentes de una decisión de arquitectura específica, como por qué usas un clúster regional de Google Kubernetes Engine (GKE), pueden revisar el ADR y, luego, el código asociado.

Los ADR también pueden ayudarte a ejecutar aplicaciones y servicios más confiables. El ADR te ayudará a comprender tu estado actual y a solucionar problemas cuando se presente. Los ADR también compilan una colección de decisiones de ingeniería para ayudar a tomar decisiones e implementaciones futuras.

Cuándo usar los ADR

Usa los ADR para hacer un seguimiento de las áreas clave que consideras importantes para la implementación. Es posible que las siguientes categorías estén en sus ADR:

  • Opciones de producto específicas, como la opción entre Pub/Sub y Pub/Sub Lite.
  • Configuraciones y opciones de productos específicos, como el uso de clústeres de GKE regionales con Ingress de varios clústeres para aplicaciones con alta disponibilidad
  • Orientación general sobre arquitectura, como las prácticas recomendadas para los manifiestos de Dockerfile.

Estos son algunos ejemplos específicos que podrían solicitarte que crees un ADR para las siguientes opciones:

  • ¿Cómo y por qué configuras la alta disponibilidad (HA) para tus instancias de Cloud SQL?
  • ¿Cómo abordar el tiempo de actividad de los clústeres de GKE? ¿Usas clústeres regionales? ¿Usas lanzamientos Canary? ¿Por qué sí? ¿Por qué no?

A medida que evalúas los productos que deseas usar, el ADR ayuda a explicar cada una de tus decisiones. Puedes revisar el ADR a medida que el equipo evoluciona y aprende más sobre la pila y se toman o ajustan las decisiones adicionales. Si realizas ajustes, incluye la decisión anterior y el motivo por el que se realiza un cambio. Este historial mantiene un registro de cómo cambió la arquitectura a medida que evolucionan las necesidades empresariales, o dónde hay nuevos requisitos técnicos o soluciones disponibles.

Los siguientes mensajes te ayudan a saber cuándo crear los ADR:

  • Cuando tienes un desafío técnico o una pregunta y no existe una base para tomar una decisión, como una solución recomendada, un procedimiento de operación estándar, un plano o una base de código.
  • Cuando tu o tu equipo ofrecen una solución que no está documentada en un lugar accesible para el equipo
  • Cuando hay dos o más opciones de ingeniería y deseas documentar tus pensamientos y los motivos de la selección.

Cuando escribes un ADR, es útil tener en cuenta los potenciales lectores. Los lectores principales son miembros del equipo que trabajan en la tecnología que cubre el ADR. Los grupos más amplios de lectores potenciales del ADR pueden incluir equipos adyacentes que desean comprender tus decisiones, como equipos de arquitectura y seguridad.

También debes considerar que la aplicación pueda cambiar de propietarios o incluir nuevos miembros al equipo. Un ADR ayuda a los colaboradores nuevos a comprender el contexto de las decisiones de ingeniería que se tomaron. Un ADR también facilita la planificación de cambios futuros.

Formato de un ADR

Un ADR típico incluye un conjunto de capítulos. Los ADR deben ayudarte a capturar lo que consideras importante para la aplicación y la organización. Algunos ADR pueden tener una página, mientras que otros requieren una explicación más extensa.

En el siguiente esquema del ADR de ejemplo, se muestra cómo puedes formatear un ADR para incluir la información que es importante para tu entorno:

  • Autores y el equipo
  • Contexto y problema que deseas resolver
  • Requisitos funcionales y no funcionales que deseas abordar
  • El posible recorrido crítico del usuario (CUJ) que afecta la decisión
  • Descripción general de las opciones clave
  • Tu decisión y los motivos de la elección aceptada

A fin de ayudar a mantener un registro de decisiones, puedes incluir una marca de tiempo para mostrar cada decisión que se tomó.

Cómo funcionan los ADR

Los ADR funcionan mejor cuando los ingenieros, desarrolladores o propietarios de aplicaciones pueden acceder con facilidad a la información que contienen. Cuando tengan una pregunta sobre por qué algo se hace de una manera determinada, pueden ver el ADR para encontrar la respuesta.

Para que el ADR sea accesible, algunos equipos la alojan en una wiki central a la que también pueden acceder los propietarios de la empresa, en lugar de hacerlo en su repositorio de control de fuente. Cuando alguien tiene una pregunta sobre una decisión de ingeniería específica, el ADR tiene que proporcionar respuestas.

Los ADR funcionan bien en las siguientes situaciones:

  • Integración: Los nuevos miembros del equipo pueden aprender sobre el proyecto con facilidad y pueden revisar el ADR cuando tengan preguntas mientras analizan el código de la aplicación o algunas otras consecuencias.
  • Transferencia de propiedad: si hay una transferencia de pila tecnológica entre los equipos, los propietarios nuevos pueden revisar las decisiones anteriores para comprender el estado actual. El ADR también puede ayudar a evitar una repetición de los mismos puntos de discusión o a revisar los temas en el futuro con conocimiento del contexto histórico.
  • Alineación: Los equipos pueden alinear las prácticas recomendadas en toda la organización cuando los ADR detallan por qué se tomaron ciertas decisiones y se optaron por alternativas.

Un ADR se suele escribir en Markdown para mantenerlo liviano y usar texto. Los archivos de Markdown se pueden incluir en el repositorio de control de origen con el código de la aplicación.

Almacena los ADR cerca del código de la aplicación, idealmente en el mismo sistema de control de versión. A medida que realizas cambios en tu ADR, puedes revisar las versiones anteriores desde el control de origen según sea necesario.

También puedes usar otro medio, como un documento de Google compartido o una wiki interna. Estas ubicaciones alternativas pueden ser más accesibles para los usuarios que no forman parte del equipo de ADR. Otra opción es crear tu ADR en un repositorio de control de origen, pero duplicar las decisiones clave en una wiki más accesible.

¿Qué sigue?