Información general sobre los registros de decisiones de arquitectura

Last reviewed 2024-08-16 UTC

Para explicar por qué los equipos de infraestructura o de aplicaciones toman determinadas decisiones de diseño, puedes usar registros de decisiones de arquitectura (ADRs). En este documento se explica cuándo y cómo usar los ADRs al crear y ejecutar aplicaciones enGoogle Cloud.

Un ADR recoge las opciones clave disponibles, los requisitos principales que impulsan una decisión y las decisiones de diseño en sí. A menudo, las ADRs se almacenan en un archivo Markdown cerca de la base de código pertinente para esa decisión. Si alguien necesita entender los antecedentes de una decisión arquitectónica específica, como por qué usas un clúster regional de Google Kubernetes Engine (GKE), puede consultar el ADR y, después, el código asociado.

Las ADRs también pueden ayudarte a ejecutar aplicaciones y servicios más fiables. El ADR te ayuda a conocer tu estado actual y a solucionar problemas. Las ADRs también crean una colección de decisiones de ingeniería para ayudar a tomar decisiones y realizar implementaciones en el futuro.

Cuándo usar ADRs

Las ADRs se usan para monitorizar las áreas clave que consideras importantes para tu implementación. Tu respuesta predefinida puede incluir las siguientes categorías:

  • Elecciones de productos específicos, como la elección entre Pub/Sub y Cloud Tasks.
  • Opciones y configuraciones de productos específicos, como el uso de clústeres de GKE regionales con Ingress de varios clústeres para aplicaciones de alta disponibilidad.
  • Directrices generales sobre arquitectura, como las prácticas recomendadas para los manifiestos de Dockerfile.

Estos son algunos ejemplos concretos que pueden llevarte a crear un ADR:

  • ¿Cómo y por qué se configura la alta disponibilidad en las instancias de Cloud SQL?
  • ¿Cómo aborda el tiempo de actividad de los clústeres de GKE? ¿Utilizas clústeres regionales? ¿Usas lanzamientos canary? ¿Por qué o por qué no?

Mientras evalúas los productos que vas a usar, el ADR te ayuda a explicar cada una de tus decisiones. Puedes volver a consultar el ADR a medida que el equipo evoluciona y obtiene más información sobre la pila, y se toman o ajustan decisiones adicionales. Si haces ajustes, incluye la decisión anterior y el motivo del cambio. Este historial registra cómo ha cambiado la arquitectura a medida que evolucionan las necesidades empresariales o cuando hay nuevos requisitos técnicos o soluciones disponibles.

Las siguientes peticiones te ayudarán a saber cuándo crear ADRs:

  • Cuando tengas un problema técnico o una pregunta y no haya una base para tomar una decisión, como una solución recomendada, un procedimiento operativo estándar, un plan o una base de código.
  • Cuando tú o tu equipo ofrecéis una solución que no está documentada en un lugar al que pueda acceder el equipo.
  • Cuando haya dos o más opciones de ingeniería y quieras documentar tus reflexiones y los motivos de la selección.

Cuando escribas un ADR, te será útil tener en cuenta a los lectores potenciales. Los lectores principales son los miembros del equipo que trabajan en la tecnología que abarca el ADR. Entre los grupos más amplios de lectores potenciales de la ADR se pueden incluir equipos adyacentes que quieran entender tus decisiones, como los equipos de arquitectura y seguridad.

También debes tener en cuenta que la aplicación puede cambiar de propietario o incluir nuevos miembros del equipo. Un ADR ayuda a los nuevos colaboradores a entender el contexto de las decisiones de ingeniería que se han tomado. Además, un ADR facilita la planificación de futuros cambios.

Formato de un ADR

Un ADR típico incluye un conjunto de capítulos. Los ADRs deben ayudarte a registrar lo que consideres importante para la aplicación y tu organización. Algunas ADRs pueden tener una página, mientras que otras requieren una explicación más larga.

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

  • Autores y equipo
  • Contexto y problema que quieres resolver
  • Requisitos funcionales y no funcionales que quieras abordar
  • Recorrido de usuario crítico (CUJ) potencial al que afecta la decisión
  • Descripción general de las opciones de clave
  • Tu decisión y los motivos de la opción aceptada

Para llevar un registro de las decisiones, puedes incluir una marca de tiempo en cada una de ellas para mostrar cuándo se tomó.

Cómo funcionan las ADRs

Las ADRs funcionan mejor cuando los ingenieros, los desarrolladores o los propietarios de aplicaciones pueden acceder fácilmente a la información que contienen. Si tienen alguna duda sobre por qué se hace algo de una forma determinada, pueden consultar el ADR para encontrar la respuesta.

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

Las ADRs funcionan bien en los siguientes casos:

  • Incorporación: los nuevos miembros del equipo pueden obtener información sobre el proyecto fácilmente y consultar el ADR si tienen alguna duda mientras aprenden a usar una nueva base de código.
  • Evolución de la arquitectura: si se transfiere la pila tecnológica entre equipos, los nuevos propietarios pueden revisar las decisiones anteriores para comprender el estado actual. El equipo también puede revisar decisiones anteriores cuando haya una nueva tecnología disponible. El registro de decisiones de arquitectura puede ayudar a los equipos a evitar que se repitan los mismos puntos de debate y a proporcionar contexto histórico cuando los equipos vuelvan a tratar temas.
  • Compartir prácticas recomendadas: los equipos pueden ponerse de acuerdo sobre las prácticas recomendadas de toda la organización cuando los ADRs detallan por qué se tomaron determinadas decisiones y por qué se descartaron otras alternativas.

Una ADR se suele escribir en Markdown para que sea ligera y se base en texto. Los archivos Markdown se pueden incluir en el repositorio de control de código fuente con el código de tu aplicación.

Guarda tus ADRs cerca del código de tu aplicación, preferiblemente en el mismo sistema de control de versiones. A medida que vayas haciendo cambios en tu ADR, podrás consultar las versiones anteriores del control de origen según sea necesario.

También puedes usar otro medio, como un documento de Google compartido o una wiki interna. Puede que estas ubicaciones alternativas sean más accesibles para los usuarios que no forman parte del equipo de la ADR. Otra opción es crear tu ADR en un repositorio de control de código fuente, pero reflejar las decisiones clave en una wiki más accesible.

Siguientes pasos