라이브 사이트 인벤토리 불일치 고치기

서버 검증 과정에서 실제 운영 중인 라이브 사이트 2개가 우리 문서에 빠져 있다는 걸 발견했다. 서버에는 있는데 docs/sites-detail.md 에는 없는 상황. 이번 커밋으로 그 간격을 메웠다.

왜 이런 누락이 생기나

생각해 보니 대부분의 팀에서 겪는 패턴이다. 새 사이트나 서비스를 추가할 때 보통 이렇게 흐른다:

• 인프라 엔지니어가 서버 설정을 빠르게 구성
• 개발자들은 바로 그 환경에서 작업 시작
• 문서 반영은 "다음에…" 또는 "간단한 거라 일단 건너뛰고…"
• 한두 개쯤은 그냥 임시라는 마음가짐으로 방치
• 시간이 지나면서 그게 우리의 "사실상 표준"이 돼버림

특히 사이트 개수가 5개, 10개 넘어가다 보면 이런 간극이 누적된다. 나중에 누군가 "우리가 운영하는 라이브 사이트가 정확히 몇 개야?" 하고 물어보면, 문서는 불완전한 그림을 보여주게 되는 거다. 온보딩 하는 신입 팀원 입장에선 더 혼란스러워진다.

업데이트한 것

두 파일을 손봤다:

작은 변경처럼 보이지만, 이게 미치는 영향은 꽤 크다:

• 온보딩: 새 팀원이 "우리 사이트는 몇 개고, 각각 뭐 하는 곳인가?" 를 명확히 파악 가능
• 장애 대응: 인시던트 발생 시 "이게 모든 사이트에 영향을 주나?" 를 체계적으로 확인 가능
• 마이그레이션: DB 마이그레이션, 설정 변경, 보안 업데이트 등을 진행할 때 빠뜨림 방지

인벤토리 관리의 현실

이 문제는 규모가 커질수록 심해진다. 서버 환경이 빠르게 변할수록, 문서화의 신뢰도를 유지하기 어렵다. 그래서 실무에선 보통 이렇게 대응한다:

정기적 검증 (우리가 이번에 한 것)
- 반기마다 한 번, 서버의 실제 상태와 문서를 비교
- 불일치 항목을 찾아내고 문서 갱신
- 비용이 낮지만 발견이 뒤늦음

자동화된 체크 (우리도 고려 중)
- CI/CD 파이프라인에 "문서 인벤토리 ↔ 서버 상태" 동기화 검증 추가
- 변경 전에 미리 잡을 수 있지만, 구현 초기 비용이 있음

단일 진실 공급원
- Terraform이나 인프라 코드를 기준으로, 문서는 그로부터 자동 생성
- 손으로 편집하는 순간 디버그가 끝나지 않으므로 가장 이상적

다음 우선순위

이번 발견 자체는 좋은 신호다. 검증 프로세스가 자기 역할을 하고 있다는 뜻. 하지만 근본 문제는 "자꾸 누락이 생기는" 구조다.

팀장 입장에선 여기서 의사결정이 필요하다:
- 정기 검증만으로 충분한가? (비용: 낮음, 효과: 뒤늦음)
- 자동화된 검증을 우선순위에 올릴 만한가? (비용: 중간, 효과: 사전 차단)
- 인프라 코드와 문서를 구조적으로 동기화할까? (비용: 높음, 효과: 장기 해결)

이번엔 정기 검증 레벨에서 발견했고, 문서 반영으로 마무리했다. 다음 검증 주기까지 이 패턴이 반복되는지 모니터링하면서, 그때 자동화를 진짜 우선순위로 올릴지 판단할 예정.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 인체공학마우스 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.