---
type: knowledge
domain: infra
status: active
last-reviewed: 2026-07-27
---

# 환경 구성과 시크릿 관리

> 한 줄 정의
> 환경은 "서버가 여러 대 있는 것"이 아니라 **같은 코드가 다른 설정으로 도는 격리 단위**다. 시크릿 3원칙(코드 금지·기동 시 검증·노출 즉시 로테이션)은 [[인프라 원리]]·[[보안 원리]] — 여기는 환경과 설정을 운영하는 절차다.

## 환경 목록과 동등성

| 환경 | 목적 | 동등성 요구 |
|------|------|------------|
| dev | 개발자 일상 검증 | 구조만 같으면 됨 (축소 규모 허용) |
| stage(검수) | 배포 전 최종 검증·발주사 검수 | **운영과 동형** — 버전·설정 구조·연동 대상의 종류가 같아야 함 |
| prod(운영) | 실사용자 | 기준점 |

- **stage가 prod와 다르면 검수가 무효다.** "stage에선 됐는데"의 원인은 대부분 환경 차이(버전·설정·데이터 규모·연동 대상)다. 차이를 없앨 수 없다면 최소한 **차이 목록을 문서로** 관리한다 — 모르는 차이가 사고를 만든다.
- 환경 간 격리는 물리적으로: 계정·네트워크·자격증명 분리. stage에서 운영 DB에 닿을 수 있는 구조는 격리가 아니다.
- 테스트 키로 운영 결제, 운영 키로 테스트 발송 — 환경 혼선 사고의 전형이다 → [[외부 연동과 웹훅]] 환경·시크릿 분리.

## 설정 주입 — 코드 밖, 명시적으로

- 설정은 코드 밖에서 주입한다: 환경변수 또는 설정 저장소. 코드에 환경 분기(`if prod`)를 심으면 환경 추가마다 코드가 바뀐다.
- **기본값의 함정**: 주입이 실패하면 코드의 기본값이 조용히 실효값이 된다 — 배포를 좌우하는 토글·엔드포인트는 기본값에 의존하지 말고 **명시 주입 + 기동 시 존재 검증**으로 강제한다. 주입 수단이 없는 플랫폼이라면 "코드 기본값 수정 = 설정 변경"임을 인지하고 배포로 취급한다.
- 기동 시점에 필수 설정·시크릿을 전부 검증하고 없으면 뜨지 않는다 — 런타임 중 첫 사용 시점에 발견하는 것은 지연된 폭탄이다.
- 설정의 종류를 구분한다: 빌드에 굽는 것(거의 없어야 정상) / 기동 시 주입(대부분) / 런타임 변경 가능(피처 플래그 → [[배포 전략 실전]]).

## 설정 변경도 변경 이력이다

- 설정 변경은 코드 배포와 같은 등급의 변경이다 — **누가·언제·무엇을·왜** 남지 않는 설정 변경은 장애 조사에서 보이지 않는 용의자가 된다. [[장애 대응 실전]]의 첫 질문 "방금 뭐가 바뀌었나"에 설정이 답할 수 있어야 한다.
- 방법은 환경에 맞게: 설정 저장소의 이력, IaC 저장소 커밋, 최소한 변경 대장. 콘솔에서 즉석 수정 후 기록 없음이 최악이다.
- 설정 파일(값 제외 구조)은 저장소에 — `.env.example`에 키 이름만 두고 실제 값은 두지 않는다.

## 시크릿 수명주기 — 발급·로테이션·폐기

| 단계 | 규율 |
|------|------|
| 발급 | 용도별 개별 발급 (공용 키 하나 돌려쓰기 금지) · 최소 권한 · 발급 대장 기록 |
| 보관 | 시크릿 매니저 또는 환경변수 주입. **소스·이미지·로그·채팅·티켓 절대 금지** |
| 로테이션 | 주기 로테이션 + 노출 의심 시 즉시. 인력 퇴출 시 그 인력이 알던 키 전부 |
| 폐기 | 회수·비활성화 확인까지가 폐기다 — "안 쓰는 키"는 폐기가 아니라 방치된 공격면 |

- 커밋된 시크릿의 대응은 히스토리 삭제가 아니라 **로테이션**이다 → [[보안 원리]].
- 로그에 시크릿이 찍히지 않게 하는 것은 호출부의 선의가 아니라 파이프라인 공통 계층의 마스킹으로 → [[에러 처리와 로깅 실전]].

## 로컬 개발의 시크릿

- `.env`는 로컬 전용, `.gitignore` 필수, 저장소 금지. 로컬용 시크릿도 운영과 별개 키로 발급한다 — 로컬 유출이 운영 유출로 번지지 않게.
- 개인 PC에 운영 시크릿 보관 금지 — 운영 접근은 통제된 경로(파이프라인·점프 호스트)로만.

## 외주 지점

- **발주사 계정·키는 발주사가 발급하고 발주사가 회수한다.** 수행사가 자체 발급·관리하는 발주사 시스템 키는 퇴출 시 회수 불능 상태를 만든다. 인력 교체·계약 종료 시 회수 절차(누가·무엇을·언제까지)를 착수 시점에 합의한다.
- **인수인계 시 시크릿 목록 문서화** — 값이 아니라 **목록·용도·위치·로테이션 방법**을 문서로. "그 키 어디 있어요?"에 퇴출한 수행사에게 전화하는 구조가 인수인계 실패다.
- 설정·시크릿 대장도 발주사 소유 산출물이다 — 외부 반출 금지.

## 안티패턴

- **"stage는 비용 때문에 대충"** — 아낀 인프라 비용을 검수 무효와 운영 장애로 지불한다.
- **환경변수 이름의 환경별 불일치** — 같은 의미가 dev와 prod에서 다른 키 이름이면 주입 실수가 구조적으로 유발된다.
- **설정 변경을 배포보다 가볍게 취급** — 설정 한 줄이 코드 만 줄보다 크게 시스템을 바꾼다.
- **공용 admin 키 하나로 전 서비스 운영** — 유출 시 전체가 뚫리고, 로테이션이 전체 중단이 된다.

## 관련 문서

- [[00_인프라 허브]] — 08_인프라 진입점
- [[인프라 원리]] — Secret 관리 3원칙
- [[보안 원리]] — 시크릿=커밋 즉시 유출·최소 권한
- [[CI-CD 파이프라인 실전]] — 같은 아티팩트 + 환경별 설정 주입
- [[폐쇄망·온프레미스 실전]] — 발주사 망 제약 하의 환경 구성
- [[에러 처리와 로깅 실전]] — 로그 마스킹 공통 계층