Infra 개발자를 위한 시스템 운영 및 배포 문서화 가이드
Infra 개발자를 위한 시스템 운영 및 배포 문서화 가이드. 복잡한 시스템 환경에서의 문서화 어려움을 CLAUDE.md로 해결하는 방법을 공유합니다.
배포 시스템 운영 및 자동화 관련 문서가 엉망이라 뭘 어떻게 해야 할지 막막했던 경험, 다들 있으시죠? 특히 여러 시스템이 복잡하게 얽혀있을 때, 각기 다른 운영 방식과 배포 과정을 일일이 파악하고 기록하는 건 정말 쉽지 않더라고요. 이 글은 그런 혼란 속에서 연구실 S2의 다양한 시스템 운영 및 배포 관련 문서화 작업을 어떻게 진행했는지, 그 과정을 공유하려고 합니다.
시도와 함정
처음에는 각 시스템별로 흩어진 정보를 모아 CLAUDE.md라는 하나의 파일에 정리하기 시작했어요. devto 순수 로직 검증부터 GitHub 트리거 자동배포, riel_agent push 자동배포, poller 자동 컨테이너 배포, Cloud Build 컨테이너화 준비, GCE 운영 안정화, 로컬 Postgres DB 백업까지. 정말 많은 주제를 다뤄야 했죠.
각 주제별로 기록을 추가하고 수정하는 과정에서 몇 가지 난관에 부딪혔습니다. 예를 들어, poller 자동 컨테이너 배포 시도는 예상대로 되지 않아 되돌려야 했고, 이 과정에서 어떤 부분을 수정해야 할지 파악하는 데 시간이 좀 걸렸어요.
# 시도했던 내용 (간략화)
- devto 로직 검증 및 확장
- GitHub 트리거 자동배포 라이브/디스크 prune fix
- riel_agent push 자동배포 인프라 기록
- poller 자동 컨테이너 배포 시도 (실패 및 롤백)
- Cloud Build 컨테이너화 준비 및 증명
- GCE 운영 안정화 이력
로컬 Postgres DB 백업 기록
이런 식으로 각 내용을 CLAUDE.md에 추가하고 수정하는 작업 자체는 비교적 명확했지만, 어떤 정보를 어떤 수준으로 기록해야 할지에 대한 기준을 잡는 게 쉽지 않더라고요. 너무 상세하면 읽기 어렵고, 너무 간략하면 나중에 다시 볼 때 이해가 안 갈 수도 있으니까요.
원인
결국 가장 큰 문제는 "어디까지 기록해야 하는가" 와 "어떻게 체계적으로 정리할 것인가" 에 대한 명확한 기준이 없었다는 점이었어요. 각 시스템의 특성에 따라 필요한 정보의 깊이가 달랐고, 이를 하나의 문서에 일관성 있게 담는 것이 어려웠습니다. 또한, 각 시스템의 운영 및 배포 과정에서 발생하는 변경 사항들을 실시간으로 추적하고 반영하는 데에도 어려움이 있었습니다.
해결
이 모든 과정을 CLAUDE.md 파일에 통합하고 업데이트하는 것으로 해결했습니다. 각 시스템의 운영 및 배포 관련 기록들을 필요한 만큼의 상세함으로 추가하거나 수정하여 문서화했습니다.
# CLAUDE.md 예시 (일부 발췌)
devto 순수 로직 검증 및 확장
- 목표: devto의 순수 로직을 검증하고, 필요한 경우 확장을 위한 기반 마련.
- 주요 내용:
- [검증 스크립트]
# 실제 검증 로직 예시 (가상)
def validate_devto_logic(input_data):
if not isinstance(input_data, dict):
return False, "Invalid input type"
if "key" not in input_data or not isinstance(input_data["key"], str):
return False, "Missing or invalid 'key'"
# ... 추가적인 로직 검증 ...
return True, "Validation successful"
# 예시 사용
test_data = {"key": "sample_key", "value": 123}
is_valid, message = validate_devto_logic(test_data)
print(f"Validation result: {is_valid}, Message: {message}")
- [확장 방향] : 새로운 API 엔드포인트 추가, 데이터 처리 방식 개선 등.
GitHub 트리거 자동배포 라이브 및 디스크 prune fix
- 목표: GitHub Push 시 자동배포 파이프라인 안정화 및 불필요한 디스크 공간 정리.
- 주요 내용:
- 이슈: 특정 브랜치 푸시 시 배포 실패, 빌드 에이전트 디스크 공간 부족.
- 해결:
github_actions_workflow.yml 수정: 배포 스크립트 오류 수정.
# github_actions_workflow.yml (일부)
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.x'
- name: Deploy Application
run: |
./scripts/deploy.sh production
echo "Deployment successful!"
- 디스크 prune 스크립트 자동화:
cron 작업 추가 또는 CI/CD 파이프라인 내 포함.
# prune_disk.sh 예시
#!/bin/bash
echo "Cleaning up old Docker images..."
docker image prune -af
echo "Cleaning up old build artifacts..."
find /app/builds -type f -mtime +7 -delete
echo "Cleanup complete."
- 결과: 배포 성공률 99% 달성, 빌드 에이전트 디스크 사용량 30% 감소.
riel_agent push 자동배포 인프라
- 목표: riel_agent를 이용한 서비스 푸시 자동배포 인프라 구축 및 운영.
- 주요 내용:
- 아키텍처 다이어그램 (텍스트 기반 또는 이미지 링크)
- 설정 파일 예시 (
riel_agent.conf)
[agent]
listen_port = 8080
log_level = info
[deployment]
repository = git@github.com:your_org/your_repo.git
branch = main
deploy_script = /opt/riel/deploy.sh
- 배포 스크립트 (
/opt/riel/deploy.sh)
poller 자동 컨테이너 배포 시도 (실패 및 롤백)
- 목표: poller 서비스의 컨테이너 자동 배포 시도.
- 시도 내용: Kubernetes CronJob을 이용한 주기적 배포 시도.
- 실패 원인: 배포 설정 오류로 인한 컨테이너 시작 실패 및 롤백.
- 개선 방향: 배포 파라미터 재검토, 롤백 전략 명확화.
Cloud Build 컨테이너화 준비 및 증명
- 목표: Cloud Build를 활용한 컨테이너 이미지 빌드 및 관리 준비.
- 주요 내용:
cloudbuild.yaml 설정 예시
# cloudbuild.yaml
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-app:$COMMIT_SHA', '.']
- name: 'gcr.io/cloud-builders/docker'
args: ['push', 'gcr.io/$PROJECT_ID/my-app:$COMMIT_SHA']
images:
- 'gcr.io/$PROJECT_ID/my-app:$COMMIT_SHA'
- 컨테이너 이미지 빌드 및 푸시 테스트 결과.
GCE 운영 안정화 이력
- 목표: Google Compute Engine 인스턴스의 운영 안정성 확보.
- 주요 활동:
- 모니터링 지표 설정 및 분석 (CPU, 메모리, 네트워크 트래픽).
- 패치 적용 및 보안 업데이트 기록.
- 장애 발생 시 대응 절차 기록.
로컬 Postgres DB 백업
- 목표: 로컬 개발 환경의 Postgres 데이터베이스 정기 백업.
백업 스크립트:#!/bin/bash DB_USER="your_db_user" DB_NAME="your_db_name" BACKUP_DIR="/path/to/backups" TIMESTAMP=$(date +"%Y%m%d_%H%M%S") mkdir -p $BACKUP_DIR pg_dump -U $DB_USER -d $DB_NAME -F c -b -v -f "$BACKUP_DIR/${DB_NAME}_${TIMESTAMP}.backup" echo "Database backup created at $BACKUP_DIR/${DB_NAME}_${TIMESTAMP}.backup" # 오래된 백업 파일 삭제 (예: 7일 이상 된 파일) find $BACKUP_DIR -type f -mtime +7 -delete echo "Old backups cleaned up."백업 주기 및 보관 정책.
결과
- 연구실 S2의 배포 시스템 및 DB 운영 관련 문서가 CLAUDE.md라는 단일 파일로 통합 및 업데이트되었습니다.
- 각 시스템의 운영 방식, 배포 과정, 설정 정보 등이 체계적으로 기록되어 가독성이 향상되었습니다.
- 새로운 팀원이 합류하거나 기존 시스템을 이해해야 할 때, 참고할 수 있는 명확한 문서가 마련되었습니다.
정리 — 같은 함정 안 빠지려면
- [ ] 문서화 대상 시스템 목록을 미리 정의하세요. 어떤 시스템의 어떤 정보를 기록할지 명확히 하는 것이 첫걸음입니다.
- [ ] 문서화의 상세 수준을 결정하세요. 너무 얕거나 깊지 않게, 필요한 정보만 담도록 기준을 세우는 것이 중요합니다.
- [ ] 일관된 형식과 구조를 유지하세요. 여러 사람이 함께 작업하더라도 혼란이 없도록 템플릿을 사용하거나 규칙을 정하는 것이 좋습니다.
- [ ] 주기적인 업데이트 계획을 세우세요. 시스템 변경 사항이 발생했을 때, 문서를 즉시 업데이트하는 습관을 들이세요.
- [ ] 버전 관리를 활용하세요. Git과 같은 도구를 사용하여 문서의 변경 이력을 추적하면 좋습니다.
태그