106 lines
10 KiB
Markdown
106 lines
10 KiB
Markdown
---
|
|
title: The Twelve-Factor App — III. Config (env-driven configuration 원칙)
|
|
source_type: official-doc
|
|
url: https://12factor.net/config
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-tmpl, config, env, twelve-factor, runtime-configuration]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-env-driven-runtime-configuration, feature-secrets-config-source-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# The Twelve-Factor App — III. Config
|
|
|
|
> Layer: `raw/official-docs/` — Twelve-Factor App methodology §III. Config 원문 발췌.
|
|
> ca-tmpl `feature-env-driven-runtime-configuration` branch의 이론적 근거 (canonical reference).
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-env-driven-runtime-configuration]] | env 기반 모든 운영 모드 전환 + `APP_` prefix 1택 + runtime reload 없음 결정의 1차 근거 (12-factor §III) |
|
|
| [[raw/branch-notes/feature-secrets-config-source-contract]] | secret/config 분리 결정 — 12-factor §III가 분리 자체는 정의하지 않으나 "credentials 포함 시 open source 불가" litmus test로 분리 필요성 시사 |
|
|
| [[raw/project-notes/ca-skeleton-operational-contract]] | env-driven runtime configuration 대안 평가 (5종)의 baseline 기준선 |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl `feature-env-driven-runtime-configuration` branch의 **이론적 근거 (canonical reference)**. branch는 `APP_` prefix, env로 모든 운영 모드 전환, secret/config 분리를 핵심 결정으로 두었는데, 이 모든 원칙의 출처가 12-factor §III. Config. branch가 채택한 "env-driven runtime configuration" 자체가 12-factor의 직접 적용. 대안(Spring Cloud Config Server / k8s ConfigMap / LaunchDarkly / Consul KV / AWS AppConfig) 평가의 기준선으로도 사용.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://12factor.net/config
|
|
- 아카이브 URL: (미확보)
|
|
- 저자 / 조직: Adam Wiggins (Heroku 공동창업자) — Twelve-Factor App methodology
|
|
- 발행 시기: 2011 (v1), 현재까지 사실상의 클라우드 네이티브 표준
|
|
- 라이선스: CC BY-SA 3.0
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§III. Config — opening, 2026-05-27 verified] "Config varies substantially across deploys, code does not."
|
|
|
|
> [§III. Config — env vars principle, 2026-05-27 verified] "The twelve-factor app stores config in environment variables (often shortened to env vars or env)."
|
|
|
|
> [§III. Config — env vars principle, 2026-05-27 verified] "unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard."
|
|
|
|
> [§III. Config — litmus test, 2026-05-27 verified] "A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials."
|
|
|
|
> [§III. Config — granular controls, 2026-05-27 verified] "In a twelve-factor app, env vars are granular controls, each fully orthogonal to other env vars."
|
|
|
|
> **재검증 완료 (2026-05-27)**: WebFetch 권한 복구 후 https://12factor.net/config 원본에서 위 5개 인용 모두 verbatim 일치 확인. 단 quote 3번은 원문이 소문자 "unlike"로 시작 (이전 캡처는 문장 시작점으로 추정해 대문자 "Unlike"로 적었으나 실제 원문은 앞 문장과 이어지는 형태). Strength `needs-confirmation` → `official-reference` 로 격상 (12-factor 는 Adam Wiggins 의 manifesto 로 formal W3C/ISO standard 가 아니므로 `official-standard` 가 아니라 `official-reference` 사용).
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| TWELVE-FACTOR-CONFIG-C1 | config 는 deploy 마다 크게 달라지지만 code 는 그렇지 않다 (deploy 간 가변성의 분리 원칙) | [§III. Config] "Config varies substantially across deploys, code does not." | `official-reference` | dev / staging / prod 등 여러 deploy 환경을 갖는 모든 앱 | "config 의 정의" (DB URL · credential · per-deploy hostname 등) 가 무엇인지의 정확한 경계는 본 인용에 명시 없음 — 별도 §III 본문 참조 필요 |
|
|
| TWELVE-FACTOR-CONFIG-C2 | Twelve-Factor App 은 **환경 변수 (env vars)** 에 config 를 저장한다 | [§III. Config] "The twelve-factor app stores config in environment variables (often shortened to env vars or env)." | `official-reference` | Twelve-Factor 를 따르는 모든 앱 | 다른 메커니즘 (config file, system property) 의 절대 금지가 아니라 1차 권장이라는 뉘앙스. 환경변수 외 저장이 12-factor 위반이라는 강한 진술은 본 인용 범위 밖 |
|
|
| TWELVE-FACTOR-CONFIG-C3 | env vars 는 custom config file 이나 Java System Properties 와 달리 **언어·OS 중립 표준** | [§III. Config] "unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard." | `official-reference` | 다언어 / 다플랫폼 배포 환경 | "language-agnostic" 이 항상 동일한 의미 (예: Windows 환경변수 대소문자) 라는 뜻은 아님 — POSIX 표준 기준 |
|
|
| TWELVE-FACTOR-CONFIG-C4 | config 분리의 litmus test = codebase 를 언제든 오픈소스화해도 credential 이 노출되지 않아야 한다 | [§III. Config] "A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials." | `official-reference` | secret · credential 을 포함하는 앱의 config 분리 평가 | secret 을 env vars 에 두는 것이 충분하다는 뜻은 아님 — 본 인용은 분리 기준만 정의, 안전한 secret 저장소 (Vault · Secrets Manager) 의 필요성 자체는 별도 |
|
|
| TWELVE-FACTOR-CONFIG-C5 | env vars 는 **granular controls** 이며 각 env var 는 다른 env var 와 fully orthogonal | [§III. Config] "In a twelve-factor app, env vars are granular controls, each fully orthogonal to other env vars." | `official-reference` | 모든 env var 정의 시 grouping 결정 | 명시적 grouping (예: `APP_*`, `DB_*` prefix) 권장 / 금지 진술은 본 인용 범위 밖 — 12-factor 본문은 grouping 권장하지 않으나 실무 prefix 규약은 자체 결정 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `TWELVE-FACTOR-CONFIG-C1`~`C5`: 12-factor §III 가 정의한 env-driven config 의 5개 원칙 (분리 / env vars 저장 / 언어 중립 / litmus test / granular orthogonality)
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- runtime reload 메커니즘 — 12-factor §III 본문은 reload 정책을 정의하지 않음. 환경변수가 프로세스 시작 시 1회만 읽히는 POSIX 표준 동작은 별도 사실 (POSIX 표준 다른 자료에서 확인 필요)
|
|
- secret 과 non-secret 의 분리 — `C4` 의 litmus test 는 분리 기준만 정의, 분리 메커니즘 (별도 secret manager) 은 12-factor §III 가 명시하지 않음
|
|
- prefix 규약 (`APP_*`, `DB_*`) — 12-factor 본문은 grouping 을 권장하지 않음. ca-tmpl 의 `APP_` prefix 결정은 branch 자체 정합성 규칙
|
|
- boolean / Duration 의 표기 표준 (예: `true/false` only, `30s` 1택) — 본 자료 범위 밖
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 의 `APP_` prefix 와 12-factor "orthogonal granular controls" 의 충돌 여부 검토 (prefix grouping 이 orthogonality 를 약화시키는지)
|
|
- Spring Boot 의 `application.yml` + `${ENV:default}` 패턴이 12-factor 와 정합하는 정확한 조건 (외부 yml 파일이 config file 인가 env vars 의 default 인가)
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 적용 컨텍스트 해석.
|
|
|
|
- 적용 시나리오: 모든 cloud-native 백엔드. 특히 build artifact 1개를 dev/staging/prod에 재배포(immutable build)하는 환경.
|
|
- 장점: **표준성**. 어떤 언어/런타임에서도 동일하게 적용. Kubernetes, Heroku, Docker, ECS, Cloud Run 모두 환경변수를 1차 진입점으로 둠. Spring Boot의 `application.yml` + `${ENV:default}` 패턴도 이와 정합.
|
|
- 단점: env 키가 수십~수백 개가 되면 관리가 어려워짐. 그래서 12-factor 자체는 grouping을 권장하지 않지만 실제로는 prefix 규약 (예: `APP_*`, `DB_*`)이 필요. branch가 `APP_` prefix 1택을 결정한 이유.
|
|
- 한계: 12-factor는 **runtime reload** 메커니즘을 정의하지 않음. 환경변수는 프로세스 시작 시 1회 읽힘 (POSIX 표준). 따라서 "no runtime reload" 가 사실상 12-factor의 묵시적 default이며, branch의 "reload policy = no runtime reload" 결정과 일치.
|
|
- secret과 non-secret을 같은 env 공간에 두는가? 12-factor는 분리하지 않음. 하지만 branch는 `feature-secrets-config-source-contract`로 분리. 이는 12-factor를 보강하는 결정.
|
|
- ca-tmpl branch와의 직접 매핑:
|
|
- `APP_` prefix → 12-factor §III "granular controls" + branch convention.
|
|
- Duration `30s` 1택 → 12-factor 본문에는 없음. branch가 추가한 가독성 규칙.
|
|
- boolean `true/false` only → 12-factor 본문에는 없음. branch가 추가한 정합성 규칙.
|
|
- 신뢰도: `official-doc` 등급 (12-factor manifesto = `official-reference` strength, not `official-standard` since not a formal W3C/ISO/IETF standard). 2026-05-27 WebFetch 재검증으로 5/5 quote verbatim 확인 완료.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 raw:
|
|
- [[raw/official-docs/config-spring-cloud-config-server-official]]
|
|
- [[raw/company-tech-blogs/config-launchdarkly-feature-flag-best-practice]]
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-env-driven-runtime-configuration]]
|
|
- [[raw/branch-notes/feature-secrets-config-source-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]]
|
|
- 대안 그룹: **Group G — Env-driven runtime configuration** (대안 5종: Spring Cloud Config Server / k8s ConfigMap+Spring Cloud Kubernetes / Consul KV / AWS Parameter Store·AppConfig / LaunchDarkly·Unleash)
|
|
- 본 source의 위치: **기준선 (baseline)** — 다른 모든 대안은 12-factor에 무엇을 더하고 무엇을 비싸게 하는가의 관점에서 평가.
|
|
- 인용한 wiki 요약: (미작성)
|