DOCS/book/300_architecture/314_infrastructure-ssot-principle.md

314 인프라 설정 SSOT 원칙

상위 원칙: 0_VALUE Infrastructure SSOT Principle

1. 목적

• 인프라 핵심 설정(IP, 포트, 업스트림, 공통 URL, 환경별 엔드포인트)을 단일 출처(Single Source of Truth)로 관리한다.
• 값 변경 1건이 다수 코드/설정/문서 수정을 유발하는 구조를 제거한다.

1.1 상위 원칙 관계

• 상위 공통 원칙의 SSOT는 0_VALUE/02_Governance/infrastructure-ssot-principle.md다.
• 본 문서는 robeing 운영 구조에 맞춘 구체화 문서다.
• 원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 남긴다.

2. 원칙

2.1 단일 출처

• 런타임 설정의 기준 파일은 /home/admin/infra-config/runtime.env 단일 파일로 한다.
• 민감 정보의 기준 파일은 /home/admin/infra-config/secrets.env 단일 파일로 한다.

2.2 분리 원칙

• runtime.env: 비민감 운영값만 포함한다.
  • 예: 내부 IP, 포트, 서비스 호스트, 모니터 URL, 기능 플래그
• secrets.env: 인증/암호/키 등 민감값만 포함한다.
  • 예: JWT secret, OAuth secret, DB password 포함 URL

2.3 참조 원칙

• 서비스 컨테이너는 docker-compose.yml의 env_file에서 위 2개 파일을 우선 참조한다.
• 서비스별 .env는 “임시 로컬 오버라이드” 용도로만 사용한다.
• 운영 기본값은 코드 하드코딩으로 두지 않는다.

2.4 네트워크 표현 원칙

• 컨테이너 간 통신은 서비스 DNS 이름을 우선 사용한다.
• 호스트 접근이 필요한 경우에만 host.docker.internal 또는 운영 표준 호스트 값을 사용한다.
• 고정 IP 직접 참조는 불가피한 경계 구간에서만 허용하고, 반드시 SSOT 변수로 선언한다.

2.5 보안 원칙

• runtime.env와 secrets.env는 git에 커밋하지 않는다.
• 권한 최소화:
  • runtime.env 640 이하
  • secrets.env 600
  • 디렉터리 권한 제한(예: 750)

2.6 문서 원칙

• 트러블슈팅 문서는 “사실/조치/검증”만 기록한다.
• 영구 규칙 변경은 본 원칙 문서에만 반영한다.
• 운영 주소 변경 시, 개별 문서에 직접 IP를 추가하지 말고 SSOT 변수명을 사용한다.

3. 적용 기준

• 신규 서비스: 최초 구성부터 본 원칙을 강제 적용한다.
• 기존 서비스: 장애 영향도가 높은 서비스부터 단계적으로 이전한다.
• 변경 검증: docker compose config, health check, 실제 API 경로 응답을 모두 통과해야 적용 완료로 본다.