StudyDad

AWS 실전 운영 시리즈 8/12AWS 콘솔에는 리소스가 많다.Lambda, API Gateway, S3 bucket, CloudFront distribution, IAM role, EC2 instance, ECR repository, CloudWatch log group.처음 만든 사람은 어디에 무엇이 있는지 안다.하지만 시간이 지나거나 담당자가 바뀌면 리소스 이름을 찾는 것부터 일이 된다.그래서 AWS 리소스 이름과 배포 정보는 반드시 문서화해야 한다.문제 상황운영 콘솔은 여러 AWS 리소스를 사용했다.정적 파일을 저장하는 S3 bucket데이터를 저장하는 S3 bucketCloudFront distributionAPI Gateway REST APILambda functionLambda LayerIA..

자동화 워크플로우 시리즈 8/8자동화의 목표는 사람이 하지 않아도 되는 일을 줄이는 것이다.하지만 좋은 자동화는 사람을 완전히 배제하지 않는다.오히려 실패했을 때 사람이 어디를 보고, 무엇을 다시 실행하고, 어떤 상태로 되돌릴 수 있는지 준비해둔다.자동화는 언젠가 실패한다. 네트워크가 끊길 수 있고, API가 실패할 수 있고, 스크립트 제한에 걸릴 수 있고, 원천 데이터가 잘못될 수도 있다.그래서 자동화 시스템에는 수동 복구 경로가 필요하다.문제 상황스프레드시트 기반 자동화 흐름은 여러 계층을 지난다.폼 제출-> 스프레드시트 기록-> Apps Script 실행-> API 호출-> Lambda 처리-> S3 JSON 저장-> 화면 반영이 중 하나만 실패해도 화면 데이터가 갱신되지 않거나, 공개 데이터가 오..

문서화와 인수인계 시리즈 9/9기술 블로그를 쓰려고 하면 종종 막막해진다.무엇을 써야 할지, 어디까지 공개해도 되는지, 이미 다른 사람이 더 잘 설명한 기술을 다시 써도 되는지 고민하게 된다.그럴 때 가장 좋은 재료 중 하나가 내가 실제로 남긴 실무 문서다.HANDOVER, 아키텍처 문서, ADR, 용어집, 트러블슈팅 가이드, 배포 가이드에는 내가 어떤 문제를 겪었고 어떻게 판단했는지가 들어 있다.이 문서들이 쌓이면 단순 기록을 넘어 개인의 일하는 방식을 보여주는 자산이 된다.기술 블로그는 지식 자랑이 아니다기술 블로그를 단순히 "내가 아는 것을 설명하는 공간"으로 보면 부담이 커진다.이미 공식 문서가 있고, 더 깊은 전문가의 글도 많다.하지만 실무 글의 가치는 다른 곳에 있다.내가 어떤 조건에서 어떤 ..

문서화와 인수인계 시리즈 8/9실무에서 만든 문서는 좋은 블로그 재료가 된다.아키텍처 문서, HANDOVER, 트러블슈팅 가이드, 배포 가이드, 용어집에는 실제 경험이 들어 있다. 검색해서 만든 글보다 훨씬 구체적이고, 판단의 흔적이 남아 있다.하지만 내부 문서를 그대로 공개하면 안 된다.실제 회사명, 도메인, 리소스 이름, API 경로, 인증 방식, 장애 날짜, 운영 데이터가 노출될 수 있다. 그래서 공개 글로 바꾸기 전에 익명화 과정이 필요하다.공개할 수 있는 것과 없는 것먼저 구분해야 한다.공개해도 좋은 것은 보편적인 판단 기준이다.왜 콘솔을 분리했는가왜 S3와 CloudFront를 썼는가왜 Lambda와 상주 서버를 나눴는가왜 job table로 비동기 작업을 관리했는가왜 CORS를 Gateway..

문서화와 인수인계 시리즈 7/9배포 가이드를 쓰다 보면 명령어만 나열하기 쉽다.npm run buildaws s3 sync build/ ...aws cloudfront create-invalidation ...물론 명령어는 필요하다. 하지만 배포 가이드가 명령어 모음으로 끝나면 위험하다.좋은 배포 가이드는 "무엇을 실행할지"뿐 아니라 "언제 실행하고, 무엇을 조심하고, 어떻게 확인하고, 실패하면 어떻게 되돌릴지"를 설명해야 한다.문제 상황운영 콘솔 배포에는 여러 종류가 있었다.React SPA 빌드 후 S3 업로드CloudFront 캐시 무효화Lambda 함수 코드 업데이트Lambda Layer 유지EC2의 Node API 서버 배포Google Apps Script 배포API Gateway stage 배..

문서화와 인수인계 시리즈 6/9장애가 나면 사람은 급해진다. 어디를 봐야 할지 기억나지 않고, 이전에 해결했던 문제도 다시 검색하게 된다. 로그 위치를 찾다가 시간을 쓰고, 같은 명령어를 다시 조합한다.그래서 트러블슈팅 문서는 장애가 난 뒤 쓰면 늦다.물론 실제 장애를 겪은 뒤 보강되는 부분은 있다. 하지만 최소한 자주 발생할 수 있는 증상과 확인 순서는 미리 정리해두는 것이 좋다.문제 상황운영 콘솔에서 반복적으로 나올 수 있는 문제는 대체로 정해져 있다.화면이 로딩되지 않는다.API 호출이 CORS 오류로 실패한다.데이터가 갱신되지 않는다.다운로드 작업이 끝나지 않는다.Lambda가 timeout 된다.DB 연결이 실패한다.배포했는데 이전 화면이 계속 보인다.이런 문제는 원인이 하나가 아니다. 화면이 ..

문서화와 인수인계 시리즈 5/9프로젝트 문서에 용어집이 필요한가?처음에는 과해 보일 수 있다. CORS, Lambda, CloudFront, API Gateway 같은 용어는 검색하면 정의가 나온다. 공식 문서도 있고, 블로그 글도 많다.하지만 프로젝트 안에서의 용어집은 일반 사전과 역할이 다르다.일반 사전은 "무엇인가"를 설명한다.프로젝트 용어집은 "이 프로젝트에서 왜 중요한가"를 설명한다.문제 상황운영 콘솔 문서를 정리하면서 여러 기술 용어가 반복해서 등장했다.CORSpreflightAPI GatewayLambda Function URLLambda LayerCloudFrontCache TTLinvalidationSSO cookiewithCredentialsSource of Truthjob tablec..

문서화와 인수인계 시리즈 4/9아키텍처 결정 기록, 흔히 ADR이라고 부르는 문서는 거창해 보인다. 대규모 조직이나 플랫폼 팀에서나 쓰는 문서처럼 느껴질 수도 있다.하지만 작은 운영 도구를 만들 때도 ADR은 필요하다.이유는 단순하다. 시간이 지나면 왜 그렇게 만들었는지 잊어버리기 때문이다.코드는 최종 결과만 보여준다. 하지만 그 결과에 도달하기까지의 선택지, 제약, 포기한 것, 다시 검토해야 할 조건은 코드에 남지 않는다.문제 상황운영 콘솔을 만들면서 여러 결정을 내려야 했다.React SPA를 어디에 배포할 것인가API 앞에 Gateway를 둘 것인가Lambda만 쓸 것인가, 상주 서버도 둘 것인가RDB를 둘 것인가, 파일 기반 저장소로 충분한가오래 걸리는 엑셀 생성은 동기 API로 처리할 것인가CO..

문서화와 인수인계 시리즈 3/9프로젝트 문서를 정리하다 보면 모든 내용을 README에 넣고 싶어진다. 가장 눈에 잘 띄고, 새로 들어온 사람이 먼저 열어보는 파일이기 때문이다.하지만 운영 중인 시스템에서는 README 하나로 충분하지 않다. 개발 시작을 돕는 문서, 시스템 구조를 설명하는 문서, 운영 인수인계를 위한 문서는 목적이 다르다.문서가 목적별로 나뉘지 않으면 두 가지 문제가 생긴다.첫째, README가 너무 길어져 아무도 끝까지 읽지 않는다.둘째, 중요한 운영 정보가 개발 가이드 사이에 묻힌다.세 문서의 차이가장 단순하게 나누면 이렇다.문서주요 독자답해야 하는 질문README처음 실행하는 개발자어떻게 설치하고 실행하는가아키텍처 문서구조를 이해하려는 개발자시스템이 어떻게 나뉘어 있고 왜 그런가H..

문서화와 인수인계 시리즈 2/9인수인계 문서를 쓰려고 하면 막막하다. 무엇을 어디까지 적어야 할지 애매하다. 너무 적으면 쓸모가 없고, 너무 많이 적으면 아무도 읽지 않는다.운영 시스템의 HANDOVER는 목적이 분명해야 한다. 새 담당자가 시스템을 이해하고, 배포하고, 장애를 확인하고, 위험한 변경을 피할 수 있어야 한다.이 글은 운영 콘솔을 정리하면서 사용한 HANDOVER 문서 구조를 일반화한 것이다.1. 시스템 개요문서의 시작은 기술 스택이 아니라 시스템의 목적이어야 한다.예를 들어 다음 질문에 답한다.이 시스템은 누구를 위한 것인가어떤 업무를 처리하는가내부 사용자만 쓰는가, 외부 사용자도 보는가데이터 원천은 어디인가운영상 가장 중요한 기능은 무엇인가좋은 개요는 한 문단으로 시스템을 설명할 수 있..