시작

📝 신입 인프라 관리자를 위한 시작 가이드

Infra 파트에 합류하신 것을 환영합니다! 🤗 코드를 열기 전에 브랜치 규칙과 배포 트리거부터 알아두시기 바랍니다. main에 머지되는 순간 운영 서버에 배포됩니다.

1. Git Flow 브랜치 규칙

Git Flow(브랜치를 역할별로 나눠 운영하는 전략)를 기반으로 운영하며, main 브랜치에 코드가 통합될 때만 실제 서버 배포가 이루어집니다.

브랜치	역할	배포 여부	비고
main	운영(Production) 환경	O (자동)	PR Merge 직후 배포
develop	개발 통합	X	기능 개발 후 통합 테스트 용도
feature/*	개별 기능 개발	X	develop에서 분기
hotfix/*	운영 이슈 긴급 수정	O	main에서 분기, 사용 권장 X

---

2. 로컬 실행 및 Swagger 확인

config-server는 Python 3.10 slim + gunicorn(파이썬 웹 앱을 여러 프로세스로 돌리는 서버) 이미지로 빌드됩니다. 로컬에서는 Dockerfile 기반으로 띄워 API 문서를 확인할 수 있습니다.

cd admin_infra/config-server

# 이미지 빌드
docker build -t config-server:local .

# 실행 (컨테이너 포트 8000)
docker run --rm -p 8000:8000 config-server:local

• Swagger UI(API 명세를 웹 화면으로 보여주는 도구): http://localhost:8000/apidocs/
• Health Check: http://localhost:8000/health

⚠️ 로컬 실행의 한계를 알아두시기 바랍니다. config-server는 Kubernetes API(in-cluster config, Pod 안에서 자동 주입되는 쿠버네티스 접속 설정), infra-mysql(DB_HOST 등 환경변수), NFS(네트워크 너머의 저장소를 내 디스크처럼 마운트하는 프로토콜) /kube_share, NAS SSH에 의존합니다. 이 의존성이 없는 로컬에서는 Swagger 명세 확인과 코드 수정 검증 용도로만 쓰고, 실제 동작 검증은 클러스터 배포 후 승인 1건 스모크 테스트(핵심 경로 한 번 통과시켜 보는 최소 검증)로 합니다.

---

3. 클러스터 접근 전제

• 운영 config-server는 FARM 클러스터 namespace(쿠버네티스 리소스를 묶는 논리적 공간) ailab-infra에 떠 있습니다.
• kubectl은 control-plane(클러스터를 관리하는 마스터 노드)에서 실행합니다. CI/CD도 운영 서버(farm8)에 SSH로 접속해 helm upgrade를 수행합니다.
• 배포 상태 확인 명령어는 운영 가이드를 참고해 주세요.

# 배포된 config-server 확인
kubectl get pods -n ailab-infra | grep config-server

---

4. 커밋·PR 규칙 요약

1. 본인이 생성한 GitHub 이슈 번호에 맞춰 develop에서 feature/#기능번호-기능명 브랜치를 만듭니다. (e.g. feat/#155-scheduler)
2. 커밋 메시지 양식은 [분류] #issue 설명입니다. (e.g. [feat] #4 메인 기능 만들기)
3. 작업 완료 후 feature → develop으로 PR을 생성합니다.
4. 정기 배포는 develop → main PR로 진행합니다. PR 제목은 [deploy] develop -> main (부가 설명)입니다.
5. 최소 한 명 이상의 Approve를 받아야 하며, Merge 버튼을 누르는 즉시 운영 서버에 배포됩니다.

배포 전 확인 두 가지를 잊지 마세요. (1) 동결 여부 — 타인이 인프라 테스트 중이면 코드/Helm 무변경 원칙이 걸려 있을 수 있습니다. (2) 배포 브랜치 — main과 hotfix 계열이 분기된 이력이 있어, "지금 클러스터에 떠 있는 이미지가 어느 커밋인가"부터 확정합니다.

세팅을 완료하셨나요﹖

그러면 시스템 아키텍처에서 승인 한 번에 무슨 일이 벌어지는지 살펴보시기 바랍니다 ➡️