# 314 인프라 설정 SSOT 원칙

**상위 원칙**: [0_VALUE Infrastructure SSOT Principle](../../../../0_VALUE/02_Governance/infrastructure-ssot-principle.md)

## 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 경로 응답을 모두 통과해야 적용 완료로 본다.