인프라 다이어그램 빌더 이미지

그 익숙한 절망의 순간

“어, 이 API 서버 앞에 RabbitMQ 하나 더 넣지 않았나요?”

회의 중에 주니어 멤버가 무심코 이 말을 꺼냈을 때, 제 피가 얼어붙는 것 같았습니다. 사내 위키에 당당하게 떠 있는 인프라 다이어그램은 6개월 전의 업데이트 날짜를 자랑스럽게 보여주고 있었죠.

솔직히 인프라는 매일 변합니다. 여기에 Redis 캐시를 추가하고 저기에 리버스 프록시를 추가하죠. 하지만 무거운 그래픽 그리기 도구를 열고, 작은 네모 아이콘을 드래그하고, 고통스럽게 화살표를 맞추고, PNG를 내보내서 위키에 업로드하는 그 엄청난 고통을 견디는 것은… 너무나도 큰 마찰입니다. 누구나 “나중에 꼭 다이어그램을 업데이트해야지”라고 생각하지만, 물론 아무도 그렇게 하지 않습니다.

‘Diagram as Code’를 향한 갈망

이 “영원히 구식인 다이어그램” 문제를 해결하기 위해, 저는 Mermaid.js로 눈을 돌렸습니다. ‘코드로 그리는 다이어그램(Diagram as Code)‘이라는 개념은 개발자들에게 꿈과 같습니다. 텍스트를 작성하고 git에 커밋하기만 하면 아름다운 다이어그램이 마법처럼 나타나니까요.

하지만 이것을 로컬에서 하려면 나름의 괴로움이 따릅니다. 복잡한 중첩 그래프(예: AWS 클라우드 리전 내부의 VPC 내부에 있는 EC2 인스턴스)를 작성하려고 시도하는 것은 직관적이지 않은 문법을 배워야만 했습니다. 코드를 작성하고, PR 미리보기가 빌드될 때까지 기다렸다가 내 화살표가 뒤로 향하고 있다는 것을 파악하는 일도 부지기수였죠.

타이핑하면서 실시간으로 그려지는 다이어그램

“그냥 텍스트를 입력하면서 화면 반대편에서 다이어그램이 실시간으로 부드럽게 만들어지는 걸 보고 싶다.”

이 전적으로 이기적인 욕망이 바로 “인프라 다이어그램 빌더”를 탄생시킨 원동력입니다.

이 도구를 만들 때 저의 첫 번째 철칙은 서버 통신이 전혀 없어야 한다는 것이었습니다. 인프라 레이아웃은 기본적으로 회사의 금고 설계도입니다. 임의의 서버(설령 그것이 제가 만든 서버일지라도)로 데이터를 전송하는 도구에 그것을 붙여넣게 할 수는 절대 없었죠. 그래서 렌더링 파이프라인 전체를 전적으로 안전한 브라우저 측 로컬 자바스크립트에 강제로 밀어넣었습니다.

지금 인프라 문서 업데이트가 너무나도 두렵다면, 이 도구에 코드를 조금 입력해보세요. 다이어그램이 제자리를 찾아가는 것을 보는 순간, 내가 마치 엄청난 아키텍트가 된 것 같은 이상하면서도 만족스러운 광경을 경험하게 될 것입니다.

결국 오래가는 것은 ‘가벼움’이었다

만들면서 새삼 깨달은 점은, 다이어그램이 낡는 이유는 문법이 어려워서가 아니라 ‘고치는 게 귀찮아서’라는 것이었습니다. 무거운 도구를 켜고, 아이콘을 다시 배치하고, 내보내고, 다시 업로드하는 의식이 하나라도 끼면 사람은 “나중에”를 택합니다. 그리고 그 나중은 영영 오지 않죠.

그래서 이 도구에서는 “떠오른 순간 바로 열어 5초 만에 고친다”를 최우선으로 삼았습니다. 노드 이름은 짧게, 선은 주요 흐름만, 노드가 10개를 넘으면 역할별로 도면을 나눈다. 이 정도의 가벼움이 결국 가장 오래갑니다. 완벽한 한 장보다, 엉성해도 계속 갱신되는 도면이 반년 뒤의 나를 구해줍니다.

자주 묻는 질문

Mermaid 문법을 몰라도 사용할 수 있나요?

네. 노드와 연결을 하나씩 추가하면 뒤에서 Mermaid 코드가 생성됩니다. 문법을 몰라도 다이어그램을 만들 수 있고, 생성된 코드를 복사해 GitHub README에 그대로 붙여넣을 수 있습니다.

입력한 인프라 구성은 외부로 전송되나요?

아니요. 렌더링은 전부 로컬 브라우저 안에서 완결됩니다. 회사의 인프라 구성을 외부 서버로 보내는 것이 너무 위험하다고 느꼈기 때문에, 처음부터 데이터가 기기 밖으로 나가지 않도록 설계했습니다.

만든 다이어그램이 GitHub README에 표시되나요?

네. GitHub는 Mermaid 플로차트를 기본으로 렌더링하므로, 아키텍처 다이어그램을 이미지가 아닌 텍스트로 관리할 수 있습니다. 구성 변경도 코드처럼 풀 리퀘스트에서 추적할 수 있습니다.

노드가 많은 큰 다이어그램은 어떻게 그리나요?

전부 한 장에 욱여넣기보다 역할별(네트워크 / 애플리케이션 / 데이터 / 모니터링)로 나누는 것을 권합니다. 노드 10개 정도가 분할의 기준입니다. 너무 채워 넣지 않는 편이 시간이 지나도 유지보수하기 쉽습니다.