아키텍처 결정 레코드 개요

Last reviewed 2024-08-16 UTC

아키텍처 결정 레코드(ADR)를 사용하면 인프라 또는 애플리케이션팀에서 특정 디자인을 선택한 이유를 쉽게 설명할 수 있습니다. 이 문서에서는 Google Cloud에서 애플리케이션을 빌드하고 실행할 때 ADR을 언제 어떻게 사용하는지 설명합니다.

ADR에는 사용 가능한 주요 옵션, 결정에 영향을 주는 기본 요구사항, 설계 결정 자체가 포함됩니다. ADR은 해당 결정과 관련된 코드베이스와 가까운 Markdown 파일에 저장되는 경우가 많습니다. 리전별 Google Kubernetes Engine(GKE) 클러스터를 사용하는 이유와 같은 특정 아키텍처 결정의 배경 정보를 확인해야 할 경우 ADR 및 관련 코드를 검토할 수 있습니다.

ADR은 또한 애플리케이션 및 서비스를 보다 안정적으로 실행하는 데 도움을 줄 수 있습니다. ADR은 현재 상태를 확인하고 문제가 있으면 문제 해결을 수행하는 데 도움이 됩니다. ADR은 또한 이후 결정을 선택하고 배포하는 데 도움이 되는 엔지니어링 결정 모음을 빌드합니다.

ADR을 사용해야 하는 경우

ADR을 사용하면 배포에 중요하다고 여겨지는 주요 분야를 추적할 수 있습니다. ADR에는 다음 카테고리가 포함될 수 있습니다.

ADR을 만들 수 있는 일부 예시에는 다음 옵션이 포함될 수 있습니다.

  • Cloud SQL 인스턴스에 대해 고가용성 (HA)을 설정하는 방법과 이유는 무엇인가요?
  • GKE 클러스터의 업타임에 어떻게 접근하나요? 리전별 클러스터를 사용하나요? 카나리아 출시 버전을 사용하나요? 그 이유는 무엇인가요?

사용할 제품을 평가할 때 ADR은 각각의 결정을 설명하는 데 도움을 줍니다. 팀 상황이 발전되고 스택에 대한 추가 정보가 확인되고 추가 결정이 수행 또는 조정됨에 따라 ADR를 수정할 수 있습니다. 내용을 수정할 때는 이전 결정 사항과 변경이 수행된 이유를 포함합니다. 이러한 기록을 통해 비즈니스 요구가 발전됨에 따라 또는 새로운 기술 요구사항이 있거나 사용 가능한 솔루션이 있을 때 아키텍처가 변경된 내역을 유지할 수 있습니다.

다음 항목은 ADR을 만들어야 하는 경우를 식별하는 데 도움을 줍니다.

  • 기술적 도전과제 또는 질문이 있지만 권장 솔루션, 표준 운영 절차, 청사진, 코드베이스와 같은 결정을 내리는 데 도움이 되는 기존 기초 자료가 없는 경우
  • 팀이 액세스할 수 있도록 특정 위치에 기술되지 않은 솔루션을 제공하는 경우
  • 엔지니어링 옵션이 2개 이상 있고 옵션 선택에 대한 생각 및 이유를 문서로 기술하고 싶은 경우

ADR을 작성할 때는 가능한 대상 독자를 미리 염두에 두는 것이 좋습니다. 기본 독자는 해당 ADR에 포함된 기술을 사용하는 팀의 구성원들입니다. ADR에 포함될 수 있는 더 포괄적인 범위의 잠재적 대상 독자에는 아키텍처 및 보안팀과 같이 해당 결정 사항을 이해하길 원하는 인접한 팀이 포함될 수 있습니다.

또한 애플리케이션에서 소유자가 변경되거나 새로운 팀 구성원이 포함될 수 있다는 것도 고려해야 합니다. ADR은 새로운 참여자가 이전에 선택된 엔지니어링 결정의 백그라운드를 이해하는 데 도움을 줄 수 있습니다. ADR은 또한 이후 변경 사항도 쉽게 계획할 수 있게 해줍니다.

ADR 형식

일반적인 ADR에는 챕터 집합이 포함되어 있습니다. ADR은 중요하다고 여겨지는 항목을 애플리케이션 및 조직에 캡처하는 데 도움이 되어야 합니다. 일부 ADR은 1페이지 분량일 수도 있고 경우에 따라 더 긴 설명이 필요할 수도 있습니다.

다음 예시로 표시된 ADR 개요에서는 해당 환경에 중요한 정보를 포함하기 위해 ADR 형식을 지정하는 방법을 보여줍니다.

  • 작성자 및 팀
  • 컨텍스트 및 해결하고자 하는 문제
  • 확인이 필요한 기능적 및 비기능적 요구사항
  • 해당 결정의 영향을 받는 잠재적인 중요한 사용자 여정(CUJ)
  • 주요 옵션 개요
  • 결정 및 해당 결정의 이면 이유

결정 기록을 유지 관리하기 위해 해당 결정이 수행된 시간을 표시하는 타임스탬프를 각 결정에 포함할 수 있습니다.

ADR 작동 방식

ADR은 엔지니어, 개발자, 애플리케이션 소유자가 ADR에 포함된 정보에 쉽게 액세스할 수 있을 때 가장 효과적입니다. 어떤 항목이 특정 방식으로 취해진 이유에 대한 질문이 있으면 ADR을 통해 그 해답을 찾을 수 있습니다.

ADR에 대한 접근성을 높이기 위해 일부 팀은 소스 제어 저장소 대신 비즈니스 소유자에게도 제공될 수 있는 중앙 위키에 호스팅합니다. 특정 엔지니어링 결정에 대해 질문이 있으면 ADR을 통해 그 해답을 찾을 수 있습니다.

ADR은 다음과 같은 시나리오에서 효과적으로 작동합니다.

  • 온보딩: 신규 팀원이 프로젝트에 관해 쉽게 학습할 수 있으며, 새로운 코드베이스를 학습하는 동안 질문이 있으면 ADR을 검토할 수 있습니다.
  • 아키텍처의 진화: 팀 간에 기술 스택이 이전되면 새로운 소유자가 이전 결정을 검토하여 현재 상태를 파악할 수 있습니다. 또한 팀에서 사용할 수 있는 새로운 기술이 있을 때 이전 결정을 검토할 수도 있습니다. ADR은 팀이 동일한 논의를 반복하지 않도록 방지하고 팀이 주제를 다시 검토할 때 이전 컨텍스트를 제공하는 데 도움이 됩니다.
  • 권장사항 공유: 특정 결정이 수행되었고 어떤 대안이 결정되었는지에 대한 세부정보가 ADR에 기술되어 있으면 조직 내에서 팀 간에 권장사항을 조절할 수 있습니다.

ADR은 경량 및 텍스트 기반 상태를 유지하기 위해 Markdown에 기록되는 경우가 많습니다. 마크다운 파일은 해당 애플리케이션 코드와 함께 소스 제어 저장소에 포함될 수 있습니다.

ADR은 애플리케이션 코드와 가깝게, 이상적으로는 동일한 버전 제어 시스템에 저장하는 것이 좋습니다. ADR을 변경할 때는 필요에 따라 소스 제어에서 이전 버전을 검토할 수 있습니다.

또한 공유된 Google 문서 또는 내부 위키와 같은 또 다른 매체도 사용할 수 있습니다. 이러한 대체 위치를 사용하면 ADR 팀에 포함되지 않은 사용자가 더 쉽게 액세스할 수도 있습니다. 또 다른 옵션은 소스 제어 저장소에 ADR을 만들지만 주요 결정사항을 보다 접근성이 뛰어난 위키에 미러링하는 것입니다.

다음 단계