배포 게이트웨이 시스템 개발 - 테스트 주도 개발로 안정성 확보

## 들어가며 현대 소프트웨어 개발에서 배포 자동화는 필수적인 요소입니다. 하지만 자동화된 배포 시스템은 잘못된 서버에 배포하거나 포트 충돌을 일으키는 등의 위험을 내포하고 있습니다. 이번 글에서는 테스트 주도 개발(TDD) 방식으로 안전한 배포 게이트웨이 시스템을 구축한 경험을 공유합니다. ## 시스템 설계의 핵심 요구사항 배포 게이트웨이 시스템은 다음과 같은 핵심 기능을 제공해야 했습니다: ### 1. 서버 화이트리스트 관리 프로덕션 환경의 중요 서버에 실수로 배포되는 것을 방지하기 위해 배포 가능한 서버 목록을 관리하는 기능이 필요했습니다. API를 통해 허용된 서버 목록을 조회하고, 배포 요청 시 해당 목록을 검증하는 로직을 구현했습니다. ### 2. 동적 포트 할당 여러 서비스가 동일 서버에 배포될 때 포트 충돌을 방지하기 위해, 특정 범위(예: 51021-51070) 내에서 사용 가능한 포트를 자동으로 할당하는 메커니즘을 구현했습니다. ### 3. 분산 락(Distributed Lock) Fencing Token 기반의 분산 락을 구현하여 동일 리소스에 대한 동시 배포를 방지했습니다. 이는 여러 개발자가 동시에 배포를 시도할 때 발생할 수 있는 경쟁 조건(Race Condition)을 해결합니다. ### 4. 감사 로깅(Audit Logging) 모든 배포 시도와 결과를 기록하여 추적성을 확보하고, 통계 데이터를 통해 시스템 사용 현황을 모니터링할 수 있도록 했습니다. ## 테스트 주도 개발 적용 ### 테스트 커버리지 전략 100개의 테스트 케이스를 작성하여 80%의 코드 커버리지를 달성했습니다. 컴포넌트별 커버리지는 다음과 같이 차등 적용했습니다: - **데이터 모델**: 93-100% - 비즈니스 로직의 핵심이므로 거의 완벽한 커버리지 목표 - **서비스 레이어**: 32-100% - 핵심 서비스는 100%, 외부 의존성이 많은 부분은 모킹 후 단계적 개선 - **API 라우터**: 100% - 모든 엔드포인트의 정상/오류 케이스 검증 - **유틸리티**: 22-47% - SSH/Docker 등 외부 시스템 연동 부분은 통합 테스트 단계에서 보완 예정 ### 핵심 테스트 시나리오 ```python # 서버 화이트리스트 검증 테스트 예시 def test_deploy_to_blocked_server_should_fail(): response = client.post("/api/v1/deploy", json={ "server_id": "production-db-01", "service_name": "test-service" }) assert response.status_code == 403 assert "blocked" in response.json()["detail"] # 포트 자동 할당 테스트 def test_port_allocation_within_range(): response = client.post("/api/v1/ports/allocate") assert response.status_code == 200 port = response.json()["port"] assert 51021 <= port <= 51070 ``` ## 상태 머신 기반 배포 프로세스 배포 상태를 명확하게 관리하기 위해 상태 머신(State Machine) 패턴을 적용했습니다: 1. **PENDING**: 배포 요청 접수 2. **VALIDATED**: 서버 및 포트 검증 완료 3. **DEPLOYING**: 실제 배포 진행 중 4. **SUCCESS** / **FAILED**: 최종 결과 각 상태 전환 시점에 감사 로그를 생성하고, 실패 시 롤백 가능하도록 설계했습니다. ## RESTful API 설계 시스템의 주요 엔드포인트는 다음과 같습니다: - `GET /health`: 헬스체크 - `GET /api/v1/servers/allowed`: 배포 가능한 서버 목록 조회 - `POST /api/v1/deploy`: 배포 요청 (서버 검증 포함) - `POST /api/v1/ports/allocate`: 사용 가능한 포트 자동 할당 모든 API는 OpenAPI(Swagger) 문서로 자동 생성되어 개발자 경험을 개선했습니다. ## 다음 단계: 통합 및 확장 현재 완료된 것은 핵심 비즈니스 로직과 API 레이어입니다. 다음 단계에서는: - 데이터베이스 연동으로 영구 저장소 구성 - SSH 및 컨테이너 오케스트레이션 도구와의 실제 연동 - 알림 시스템 통합으로 배포 결과 실시간 통지 - 추가 보안 레이어(인증/인가) 강화 등을 진행할 예정입니다. ## 마치며 배포 자동화 시스템은 편리함만큼이나 위험성도 큽니다. 테스트 주도 개발로 핵심 로직을 먼저 검증하고, 화이트리스트와 분산 락 같은 안전 장치를 설계 단계부터 고려하는 것이 중요합니다. 80%의 코드 커버리지와 100개의 테스트 케이스는 단순한 숫자가 아니라, 시스템에 대한 신뢰를 구축하는 과정입니다. 여러분의 배포 시스템에도 이러한 안전 장치가 잘 마련되어 있는지 점검해보시기 바랍니다.

배포 게이트웨이 시스템 개발 1단계 완료 - 테스트 주도 개발로 안정성 확보하기

관련 글

Wiki.js API 권한 설정과 계정 생성 자동화 구축하기

AI 에이전트 시스템을 위한 커널 아키텍처 설계 가이드

PDF 자동 다운로더 장애 분석: 100% 실패율을 해결한 3가지 원인과 교훈

이 주제에 대해 더 알아보고 싶으신가요?