AWS 스타일 아키텍처 다이어그램
개요
AWS 참조 아키텍처 다이어그램 규칙을 따르는 다이어그램을 생성합니다: 정확한 서비스 이름, 레이블이 지정된 계정/리전/VPC 경계, 짧은 흐름 레이블, 깔끔한 캔버스. "AWS 스타일"은 이러한 규칙을 설명하며, 공식 AWS 아이콘이나 Graphviz를 반드시 요구하지는 않습니다.
Mermaid와 Graphviz DOT는 동등한 작성 형식입니다. Mermaid는 인라인, 테마 인식, 텍스트 검토 가능 문서에 자주 적합합니다. DOT는 정확한 로컬 AWS 아이콘 자산, 제어된 구성, 프레젠테이션 준비 SVG/PNG에 자주 적합합니다. 하나의 형식이 전체 전달 계약을 충족할 때는 하나를 사용하고, 다른 대상 사용자나 아티팩트로 인해 추가 유지 관리가 가치 있을 때는 둘 다 사용합니다.
사용 시기
증거 기반 AWS 아키텍처, 토폴로지, 시스템 컨텍스트 또는 데이터 흐름 다이어그램에 이 스킬을 사용하세요. AWS가 아닌 시각적 요소나 테이블만으로 요청된 사실을 더 명확하게 전달할 수 있는 경우에는 사용하지 마십시오.
일반적인 오해
- "AWS 스타일은 DOT를 의미한다"는 실제 계약을 충족하는 Mermaid 렌더러를 무시합니다.
- "두 형식 모두 더 안전하다"는 두 명의 소비자 없이 동기화 비용을 발생시킵니다.
- "서비스가 아마 여기에 연결될 것이다"는 엣지에 대한 증거가 아닙니다.
위험 신호
지원되지 않는 리소스나 관계, 모호한 대상 렌더러, 누락된 아이콘 권리 또는 자산, 충돌하는 소스 증거, 또는 승인된 범위를 벗어난 요청된 리전에 대해 그리거나 라이브 인프라를 쿼리하기 전에 중지하고 해결하십시오.
미적 요소보다 우선하는 규칙
소스가 확립한 것만 그리세요. 모든 노드, 엣지, 경계, 리전 및 프로토콜은 Terraform, CloudFormation, CDK, 배포된 구성 또는 소유자의 서면 진술과 같은 실제 무언가를 추적해야 합니다. 다이어그램은 우연히 시각적인 증거 아티팩트입니다.
그림이 불균형해 보인다고 서비스, 연결, 가용 영역, VPC 또는 리전을 절대 추가하지 마십시오. 소스가 경계를 확립하지 않으면 생략하십시오. 정직한 드문 다이어그램이 장식적인 완전한 것보다 낫습니다. 무언가 배포되었지만 비활성화된 경우, 마치 활성화된 것처럼 그리지 말고 노드에 (WEB_PUSH_ENABLED=false, "배포됨, 릴리스 비활성화")라고 말하고 다른 팀이 소유한 것을 표시하여 독자가 당신이 제어한다고 생각하지 않도록 하십시오.
다이어그램 자체에 출처를 명시하십시오 — 소스를 지정하는 부제목(예: "<iac-dir>/*.tf에서 <revision>으로 추적됨" 또는 "라이브 읽기 전용 인벤토리, <date>")을 포함하고 DOT 소스의 헤더 주석에 반복하십시오.
서비스만이 아닌 리소스 이름 지정
서비스 아이콘만으로는 아무것도 식별하지 못합니다. "Operations"라고 레이블이 지정된 자홍색 DynamoDB 글리프는 테이블, 스트림 또는 인덱스일 수 있으며, 독자는 콘솔에서 이를 찾을 방법이 없습니다. 모든 노드는 세 가지 사실을 명시합니다:
- AWS에서 호출되는 이름. 실제 배포된 이름 —
acme-orders-events, "Orders"와 같은 친숙한 별칭이 아닙니다. 계정 ID는 숫자 대신<account>로 작성하십시오. 다이어그램에 비밀, 토큰 또는 엔드포인트를 절대 넣지 마십시오. - 리소스 유형. 이름 아래 회색으로 작성: "DynamoDB table", "S3 bucket", "Lambda function", "API Gateway HTTP API", "WAFv2 web ACL", "SES v2 email identity".
- 용도. 한 줄, 독자가 추론할 수 없는 경우에만.
Graphviz 출력의 경우 AWS가 게시한 리소스 아이콘을 사용하십시오 (Res_Amazon-DynamoDB_Table, Res_Amazon-Simple-Storage-Service_Bucket, Res_AWS-Lambda_Lambda-Function) — 그 외의 것은 서비스 (Arch_) 아이콘을 사용하십시오. 아이콘은 정체성을 강화합니다. 아이콘만으로 전달해서는 안 됩니다. 아이콘은 회색조, 썸네일 크기 또는 화면 판독기에서 읽을 수 없기 때문입니다.
요구 사항에서 형식 선택
전역적 승자는 없으며 기본 형식도 없습니다. 명시적으로 요청된 소스 형식을 다른 수용 기준과 충돌하지 않는 한 존중하십시오. 그렇지 않으면 실제 전달 요구를 비교하십시오:
| 요구 사항 | Mermaid가 더 적합한 경향 | Graphviz DOT가 더 적합한 경향 |
|---|---|---|
| 저장소 검토 | 인라인 Markdown 렌더링, 간결한 텍스트 diff | 검토 가능한 텍스트 소스 + 별도 렌더링 아티팩트 |
| 다이어그램 유형 | 시퀀스, 흐름, 상태, 종속성 및 간단한 아키텍처 뷰 | 밀집 토폴로지, 중첩 경계 및 의도적인 엣지 라우팅이 필요한 그래프 |
| AWS 시각적 요소 | AWS 스타일 이름, 경계, 색상 또는 렌더러 제공 아이콘 팩 | 정확한 저장소 로컬 AWS 게시 아이콘 자산 |
| 레이아웃 | 렌더러 관리 반응형 레이아웃 및 테마 적응 | 정확한 순위, 포트, 클러스터, 간격 및 고정 구성 |
| 전달 | 작성된 곳에서 렌더링되어야 하는 문서 | 프레젠테이션, 문서 및 발표 표면을 위한 제어된 SVG/PNG |
| 도구 | 대상 렌더러가 필수 Mermaid 구문 및 버전을 이미 지원 | Graphviz 및 필수 로컬 자산이 빌드 또는 작성 환경에서 사용 가능 |
요청된 내용이 실제로 표 형식인 경우 그림으로 바꾸지 말고 Markdown 테이블을 사용하십시오. 순서가 있는 참가자 교환의 경우 Mermaid sequenceDiagram이 일반적으로 자연스러운 선택입니다. 이는 다이어그램 유형의 장점이지 Mermaid에 대한 일반적인 선호도가 아닙니다.
Mermaid는 아키텍처 다이어그램 및 구성 가능한 아이콘 팩을 지원하지만, 호스팅된 렌더러가 저장소 로컬 AWS 자산, 사용자 지정 팩 등록 또는 제어된 로컬 렌더러와 동일한 Mermaid 버전을 제공한다고 가정할 수 없습니다. Graphviz는 로컬 이미지 자산을 직접 로드할 수 있으므로, 요청이 "AWS 스타일"이라고 해서가 아니라 정확한 아이콘 자산과 고정된 내보내기 구성이 수용 기준일 때 신뢰할 수 있는 선택입니다.
양쪽의 트레이드오프를 계산하십시오. Mermaid는 렌더러 버전, 사용 가능한 아이콘 팩 및 호스트 테마에 따라 달라질 수 있습니다. DOT는 렌더링 단계와 편집 가능한 소스와 동기화되어야 하는 생성된 아티팩트를 추가합니다. 도구의 장점이 보편적이라고 취급하지 말고 비용이 저장소와 대상과 일치하는 형식을 선택하십시오.
렌더러 지원, 아이콘 충실도, 고정 구성 또는 예상 출력 파일이 결과를 실질적으로 변경하고 요청이 모호한 경우 전달 계약을 명확히 하십시오. 그렇지 않으면 알려진 요구 사항을 가장 적은 프로젝트별 메커니즘으로 충족하는 형식을 선택하십시오.
Mermaid가 선택된 경우 위의 증거, 출처, 리소스 이름 지정 및 접근성 규칙을 유지하고 대상 렌더러에서 소스를 검증한 후 아래 Graphviz별 워크플로우 전에 중지하십시오.
두 형식이 모두 정당화되는 경우
Mermaid와 DOT가 서로 다른 실제 요구 사항(예: 인라인 저장소 검토 + 정확한 AWS 아이콘 프레젠테이션 출력)을 충족할 때 두 형식을 모두 생성하십시오. 이중 전달이 자동으로 더 나은 것은 아닙니다. 두 아티팩트 모두 명명된 소비자 또는 수용 기준이 있을 때만 정당화됩니다.
어떤 소스도 기본적으로 표준이 아닙니다. 동일한 검증된 리소스 및 관계 인벤토리에서 둘 다 파생하고 동일한 출처를 전달하며 노드, 엣지, 경계, 리전, 소유권 및 불확실성이 일치하는지 확인하십시오. 형식은 주장하는 아키텍처를 변경하지 않고 프레젠테이션별 구조를 추가할 수 있습니다. 사용자 또는 저장소 정책이 명시적으로 해당 역할을 할당할 때만 하나의 형식을 권위 있는 것으로 지정하십시오.
비정상적으로 밀집된 전체 시스템 맵에 정확한 AWS 아이콘, 고정 구성 또는 포트 수준 커넥터 배치가 필요한 경우 DOT와 그 SVG 및 PNG가 프레젠테이션 및 AWS 아이콘 아티팩트 역할을 할 수 있습니다. Mermaid 렌더링은 유지 관리 가능하고 인라인 검토 가능한 동반자 역할을 할 수 있습니다. 이러한 DOT별 요구 사항이 없는 집중된 흐름의 경우 Mermaid 단독으로 계약을 충족할 수 있습니다. 이는 모든 다이어그램에 대해 두 형식을 모두 생성해야 하는 이유가 아닌 요구 사항 기반 선택입니다.
Mermaid 워크플로우
1. Mermaid 다이어그램 유형 선택
아키텍처 및 토폴로지에는 architecture-beta 또는 순서도를 사용하고, 순서가 있는 교환에는 sequenceDiagram을 사용하며, 실제 상태 전환에만 상태 다이어그램을 사용하십시오. 대상 렌더러가 선택한 구문과 아이콘 팩을 지원하는지 확인하십시오. GitHub, 문서 사이트 및 로컬 Mermaid CLI가 동일한 버전이나 구성을 실행한다고 가정하지 마십시오. Iconify 기호를 사용할 때는 전체 AWS 리소스 이름과 유형을 텍스트로 유지하십시오. 아이콘은 절대 유일한 리소스 식별자가 되어서는 안 됩니다.
2. 검증된 인벤토리 인코딩
증거가 확립한 경우에만 AWS 계정, 리전, VPC, 가용 영역, 서브넷 및 소유권 경계를 표현하십시오. 전체 리소스 이름과 유형, 짧은 레이블이 있는 엣지, 허용되거나 추론된 관계에 대한 표시 주석을 사용하십시오. 근처 Markdown과 구문이 허용하는 경우 소스 주석에 출처를 유지하십시오.
3. 대상 환경에서 렌더링 및 검사
저장소의 고정된 Mermaid 명령 또는 문서 빌드를 사용하십시오. 배송될 정확한 펜스 블록 또는 .mmd 소스를 검증한 후 의도된 너비와 테마에서 렌더링된 결과를 검사하십시오. 잘린 레이블, 겹치는 엣지, 지원되지 않는 아이콘 또는 구문, 접근할 수 없는 대비 및 검증된 인벤토리와의 의미적 차이를 확인하십시오. 편집 가능한 소스를 수정하고 읽을 수 있을 때까지 다시 렌더링하십시오.
기본 제공되지 않은 아이콘 팩을 명시적으로 등록하십시오. Mermaid CLI의 경우 재현 가능한 AWS 기호 렌더링은 다음을 사용할 수 있습니다:
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
? 폴백은 미용적 저하가 아닌 실패한 렌더링으로 처리하십시오. 아이콘 팩 지원은 Mermaid 버전 및 레이아웃 렌더러에 따라 다를 수 있습니다. 실제 출력을 시각적으로 그리고 구조적으로 확인하십시오. 지원되는 한 렌더러가 등록된 아이콘을 잃는 경우 이를 유지하는 다른 지원되는 렌더러를 사용하고 레이아웃 트레이드오프를 문서화하십시오. 대상 호스트도 필수 팩을 등록하지 않는 한 인라인 이식성을 주장하지 마십시오.
4. 필수 아티팩트 전달
저장소 계약이 그러할 때 Mermaid를 인라인으로 유지하십시오. 독립 실행형 SVG 또는 PNG 출력이 필요한 경우 저장소의 고정된 Mermaid 버전으로 결정론적으로 렌더링하고 재생성 명령을 문서화하십시오.
Graphviz 워크플로우
1. 소스에서 아키텍처 확립
IaC를 읽고 그리기 전에 실제로 존재하는 것을 인벤토리하십시오. 이 프로젝트가 유지하는 디렉토리(infra/, terraform/, deploy/, CDK 앱)를 찾으십시오. 레이아웃을 가정하지 마십시오:
iac_dir=infra # 이 저장소가 실제로 사용하는 것
호출 -hoE '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
그런 다음 엣지를 실제로 만드는 세부 사항 과 노드에 표시할 이름을 가져오십시오: 함수 이름, 테이블 이름, 버킷 이름, 이벤트 규칙 및 일정, S3 알림, 권한 부여자 및 교차 계정 또는 교차 스택 권한. 이름을 변수와 로컬을 통해 실제 배포된 값으로 확인하십시오. 가정이 아닌 설정하는 변수에서 리전을 기록하십시오.
1b. IaC가 없거나 IaC가 환경의 일부만 포함하는 경우
때로는 다이어그램으로 그릴 대상이 아무도 Terraform이 없는 실행 중인 계정이거나 Terraform이 배포된 것의 일부만 포함하는 경우가 있습니다. 그러면 소스는 라이브 계정(읽기 전용)이며, 다이어그램은 그것이 무엇인지 명시해야 합니다.
서비스별 검색보다는 태그 조건에서 시작하십시오. 그것이 "이 시스템에 속하는 것"의 범위를 지정하는 유일한 방법이기 때문입니다:
aws resourcegroupstaggingapi get-resources --region <region> \
--tag-filters 'Key=<key>,Values=<v1>,<v2>'
여러 태그 키는 각각 하나의 요청이 필요하며 이후 ARN으로 결합됩니다. 두 키를 하나의 요청에 전달하면 AND가 적용되어 둘 중 하나만 있는 모든 것을 자동으로 제외합니다. 결과 개수와 날짜를 기록하십시오. 이는 스냅샷이지 확정된 사실이 아닙니다.
태깅 API는 모든 리소스 유형을 반환하지 않으며 태그는 소유권이 아닙니다. 따라서 태그 쿼리는 노드 세트를 제공하고 관계는 실제로 모델링하는 API에서 비롯됩니다:
| 확립할 사항 | 읽을 API |
|---|---|
| 수신 배선 | elbv2 describe-load-balancers, describe-target-groups |
| 허용된 경로 | ec2 describe-security-groups, describe-vpcs |
| 컴퓨팅 계층이 호출할 수 있는 것 | iam get-instance-profile, then get-policy-version |
| 데이터 계층 형태 및 복제본 | rds describe-db-instances, elasticache describe-* |
| 비동기 배선 | 대기열 재시도 정책, S3 알림, 이벤트 규칙 |
찾은 모든 CIDR을 그리기 전에 명명된 VPC로 확인하십시오. 확인되지 않은 10.16.0.0/16은 다이어그램에서 독자에게 아무것도 알려주지 않습니다.
1c. 각 엣지가 어떤 종류의 증거에 기반하는지 말하십시오
이는 라이브 계정을 읽을 때 가장 중요합니다. 두 리소스가 이름 접두사를 공유한다고 해서 선을 그리는 것이 유혹적이기 때문입니다. 시각적으로 클래스를 분리하고 다이어그램과 그 설명에서 정의하십시오:
- AWS 자체가 보고하는 배선 — 대상 그룹의 대상, 복제본의 소스. 가장 강력한 클래스입니다. AWS가 관계를 모델링하고 있습니다.
- 어떤 경로가 허용하는 것 — 보안 그룹 규칙, 버킷 정책. 이는 호출이 발생할 수 있음을 확립할 뿐, 발생한다는 것은 아닙니다. 규칙이 CIDR 범위인지 보안 그룹 범위인지 기록하십시오: 전체 범위를 승인하는 것이지 화살표를 그린 특정 워크로드가 아닙니다.
- ID가 보유한 권한 — IAM 정책 명령문. 동일한 주의 사항, 더하기 SCP, 권한 경계 및 리소스 정책이 평가될 때까지 권한은 유효하지 않습니다.
- 이름 또는 태그에서의 추론 — 점선으로 그리고 불확실성을 레이블로 표시하거나 생략하십시오. 절대 실선으로 하지 마십시오.
부재도 그릴 가치가 있는 발견입니다. 대기열과 "분명히" 통신하는 역할에 sqs:* 작업이 전혀 없는 경우, 누락된 화살표보다는 그렇게 말하는 노드가 더 유용합니다. 잘못된 가정을 차단하기 때문입니다...