AWS 리소스 이름과 배포 정보를 문서화해야 하는 이유

AWS 실전 운영 시리즈 8/12

AWS 콘솔에는 리소스가 많다.

Lambda, API Gateway, S3 bucket, CloudFront distribution, IAM role, EC2 instance, ECR repository, CloudWatch log group.

처음 만든 사람은 어디에 무엇이 있는지 안다.

하지만 시간이 지나거나 담당자가 바뀌면 리소스 이름을 찾는 것부터 일이 된다.

그래서 AWS 리소스 이름과 배포 정보는 반드시 문서화해야 한다.

문제 상황

운영 콘솔은 여러 AWS 리소스를 사용했다.

• 정적 파일을 저장하는 S3 bucket
• 데이터를 저장하는 S3 bucket
• CloudFront distribution
• API Gateway REST API
• Lambda function
• Lambda Layer
• IAM role
• EC2 instance
• Docker image repository
• CloudWatch log group

문제가 생겼을 때 이 리소스들을 빠르게 찾아야 한다.

그런데 문서가 없으면 AWS 콘솔에서 이름을 하나씩 검색해야 한다.

비슷한 이름의 리소스가 많으면 더 어렵다.

내부 문서에는 실제 이름이 필요하다

블로그 글에서는 실제 리소스명을 제거해야 한다.

하지만 내부 운영 문서에는 실제 이름이 필요하다.

예를 들어 다음 정보다.

리소스	문서에 남길 정보
Lambda	함수명, runtime, memory, timeout, Layer
API Gateway	API 이름, ID, stage, 주요 path
S3	bucket 이름, 주요 prefix
CloudFront	distribution ID, domain, origin
IAM	role 이름, 주요 권한 범위
EC2	instance 이름, 접속 방법, 실행 container
ECR	repository 이름, image tag 규칙
CloudWatch	log group 이름

이 정보가 있어야 장애 때 바로 이동할 수 있다.

보안과 문서화는 충돌하지 않는다

리소스 이름을 문서화하면 보안상 위험하지 않느냐고 생각할 수 있다.

구분이 필요하다.

내부 운영 문서에는 리소스 이름이 필요하다.

공개 문서에는 제거해야 한다.

보안상 문서에 넣으면 안 되는 것은 secret 값이다.

• Access Key
• Secret Key
• DB password
• token
• private key
• session cookie 값

반면 리소스 이름, ARN, log group, stage 이름은 내부 담당자가 운영하려면 알아야 한다.

문제는 문서화 자체가 아니라 공개 범위 관리다.

배포 정보도 함께 남긴다

리소스 이름만으로는 부족하다.

어떻게 배포하는지도 함께 남겨야 한다.

예를 들어 Lambda라면:

• 배포 명령어
• zip 파일에 포함할 파일
• Layer는 별도로 관리되는지
• 배포 후 확인할 API
• timeout과 memory 설정
• 환경 변수 목록

CloudFront라면:

• origin이 어디인지
• 어떤 경로가 어떤 origin으로 가는지
• 캐시 정책
• invalidation 방법
• 커스텀 도메인과 인증서 정보

EC2 + Docker라면:

• image build 방법
• ECR push 방법
• EC2에서 pull/run 방법
• container 이름
• 로그 확인 방법
• 재시작 방법

운영 문서는 리소스 목록과 배포 절차가 연결되어야 한다.

로그 위치는 리소스 정보의 일부다

장애 대응에서 가장 중요한 것은 로그 위치다.

Lambda 함수명을 알아도 log group을 모르면 시간이 걸린다.

API Gateway stage를 알아도 access log 위치를 모르면 요청이 들어왔는지 확인하기 어렵다.

따라서 다음을 문서화한다.

Lambda function: report-api-function
Log group: /aws/lambda/report-api-function

API Gateway: operations-api
Stage: prod
Access log: CloudWatch log group name

CloudFront:
Access log bucket/prefix: cloudfront-logs/

공개 글에서는 예시 이름으로 바꾸면 된다.

리소스 관계를 함께 적는다

리소스는 따로 존재하지 않는다.

서로 연결되어 있다.

예를 들어:

CloudFront
-> S3 static origin

API Gateway
-> Lambda function
-> S3 data bucket
-> RDS

이 관계를 문서에 남기면 장애 구간을 좁히기 쉽다.

CloudFront가 S3를 보고 있는지, API Gateway가 어떤 Lambda와 연결되어 있는지, Lambda가 어떤 bucket과 DB에 접근하는지 한눈에 알아야 한다.

문서에는 이 관계를 다이어그램으로도 남기는 편이 좋다.

장애 때는 "리소스 이름"보다 "어디서 어디로 연결되는지"가 먼저 필요할 때가 많다. 관계도가 있으면 콘솔에서 다음에 눌러야 할 곳을 빠르게 찾을 수 있다.

환경별 리소스를 구분한다

운영 환경과 개발 환경이 있다면 반드시 구분한다.

prod
staging
dev

환경이 섞이면 위험하다.

개발 환경에 배포하려다 운영 Lambda를 덮어쓸 수 있고, 운영 데이터를 개발 테스트로 수정할 수 있다.

문서에는 환경별 리소스 이름과 배포 대상 확인 방법을 적어야 한다.

공개 글로 바꿀 때

AWS 리소스 문서는 블로그 글로 바꿀 때 가장 조심해야 한다.

제거할 것:

• 실제 bucket 이름
• 실제 distribution ID
• 실제 API Gateway ID
• 실제 Lambda 함수명
• 실제 IAM role 이름
• 실제 account ID
• 실제 domain
• 실제 log group

남길 수 있는 것:

• 어떤 리소스를 문서화해야 하는지
• 왜 문서화해야 하는지
• 리소스 관계를 어떻게 그리는지
• 배포 정보와 로그 위치를 같이 남기는 원칙

정리

AWS 리소스 이름과 배포 정보는 내부 운영 문서에 반드시 필요하다.

리소스 이름을 모르면 장애 대응은 AWS 콘솔 검색부터 시작된다.

좋은 문서는 다음을 남긴다.

• 리소스 이름
• 역할
• 연결 관계
• 배포 방법
• 로그 위치
• 환경별 차이
• 주의사항

공개 글에서는 식별 정보를 제거해야 한다.

하지만 내부 문서에서는 정확해야 한다.

문서화는 보안과 충돌하지 않는다. 공개 범위를 나누면 된다.

함께 볼 GitHub 저장소

• aws-console-operations-notes