문제: docs/registries/env-keys.yaml·.env.example·배포 설정(profile 밖의
application.yml, config/*.yml, 모듈 module-defaults)이 서로 갈렸고
verifyEnvKeys는 그 차이를 보지 못했다.
- .env.example을 복사하면 기동이 실패하는 값이 있었다:
APP_DATASOURCE_CONNECTION_TIMEOUT=5s(Hikari long ms, registry 주석이
"기동 실패"라고 적은 그 값), APP_SECURITY_CORS_MAX_AGE=600s(long 초).
- 기본값과 다른 예시 값: cache·rate-limit Redis command timeout(2s·1s vs
200ms), APP_LOG_LEVEL_SQL(WARN vs INFO), FORWARD_HEADERS_STRATEGY(native
vs none — 프록시 없는 배포에서 forwarded 헤더를 믿게 된다),
POSITIVE_SOFT_TTL(빈 줄 — 빈 문자열이 기본값을 덮는다).
- registry가 폐기(deprecated_orphaned)로 적은 키 셋을 cache-redis 모듈 설정이
읽는다(COMMAND_TIMEOUT, SEMANTIC_REGION, KEY_HMAC_SECRET 참조).
- 폐기 키 45개가 .env.example에 값과 함께 남아, 복사하면 아무 일도 하지 않는
값을 켠 것으로 믿는다. 검사가 오히려 registry의 모든 APP_ 행을 예시에
요구해 폐기 행도 넣게 했다.
- 배포 설정이 읽는 APP_ 밖 placeholder 11개(SECURITY_PUBLIC_PATHS,
PRESENTATION_API_BASE_PATH, SPRING_JACKSON_DESER_* 등)에 registry 행이
없었다. 검사가 APP_ 이름만 보고, registry 파서도 APP_ 행만 읽어
MANAGEMENT_SERVER_ADDRESS 같은 행이 보이지 않았다.
- .env.example 머리말은 "빈 키는 기본값을 쓴다", "Seven values"라고 적었다.
고른 방법: 런타임 동작은 바꾸지 않고 registry와 예시를 배포 설정에 맞춘다.
그리고 verifyEnvKeys가 다섯을 더 본다.
1. registry 행은 접두어와 상관없이 읽는다.
2. 배포 설정의 placeholder는 접두어와 상관없이 행이 있어야 한다.
3. deprecated_orphaned 행은 배포 설정이 읽지 않고 .env.example에 없다.
4. .env.example 값은 registry default(행에 example이 있으면 그 값)와 같다.
빈 줄은 빈 문자열로 본다.
5. profile 밖 배포 설정의 placeholder 기본값은 registry default와 같다.
registry에 example 칸을 두었다(SMTP 587·timeout처럼 기본값이 아닌 권장값).
APP_ 밖 이름 11개는 지금 이름 그대로 등록했다. 바꾸면 파생 서비스의 배포
env가 소리 없이 무시된다. 이름 변경은 소유자 결정이다. registry 머리말을
실제 규칙(SPRING_·MANAGEMENT_·SERVER_·OTEL_ 이름공간과 옛 이름 둘)으로
고쳤다. gRPC를 켜려면 꼭 두는 APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL과
.env.example의 MANAGEMENT_SERVER_ADDRESS를 더했다.
버린 대안: SECURITY_PUBLIC_PATHS·PRESENTATION_API_BASE_PATH를 APP_로 바꾸고
옛 이름을 fallback으로 두기 — 공개 경로 기본값이 4중 placeholder가 되고
공개 경로 스냅숏 파서까지 바꿔야 한다. 이름 정리는 따로 정한다.
위험·한계: 파생 서비스가 자기 placeholder를 등록하지 않았거나 예시 값이
기본값과 다르면 이제 verifyEnvKeys(mainCheck)가 실패한다(upgrade 안내 5·6).
예시 값이 바뀌어 옛 예시를 복사한 .env는 그대로 둔다 — 안내 1~4가 고칠
값을 적는다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 시험만으로 EnvContractVerifierTest 22건 중 7건 실패
(새 검사 6건 + 메시지를 바꾼 기존 1건). 새 지킴 시험(example 행 통과)은
기준에서도 통과.
- GREEN: -p build-logic test, :app-bootstrap:verifyEnvKeys(314 env keys, 6
required placeholders, 370 rows), :app-bootstrap:test·repositoryContractTest·
documentContractTest, registry·예시를 읽는 leaf 시험(httpclient env
manifest, notification mode, redis-runtime required_when, support,
fileserver·notification platform, graphql registry parity, web CORS)
682건 실패 0, skip 5. rc=0.
BREAKING CHANGE: verifyEnvKeys가 접두어 밖 placeholder, 폐기 행의 사용,
예시·기본값 차이를 실패로 본다. .env.example에서 폐기 키가 빠지고 값 여덟이
기본값으로 바뀌었다. 할 일은 docs/upgrade/2026-11-round9-env-keys.md.
4.2 KiB
4.2 KiB
업그레이드 안내 — 2026-11 env 키 계약 정리
- 범위:
docs/registries/env-keys.yaml·.env.example·verifyEnvKeys를 배포 설정의 실제 동작에 맞춘 변경. 앱이 읽는 키와 그 기본값은 바뀌지 않았다. 바뀐 것은 예시 파일의 값, registry 행, 그리고 검사가 실패로 보는 범위다. - 근거: 2026-11-12 전체 리뷰(
docs/reviews/2026-11-12-round9-review/)의 env 계약 발견
1. 누가 읽나
이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 예전 .env.example을 복사해 .env나
배포 env를 만든 서비스, 자기 배포 설정에 placeholder를 더한 서비스다.
2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
|---|---|---|---|
| 1 | 옛 .env.example에서 복사한 APP_DATASOURCE_CONNECTION_TIMEOUT=5s를 5000(밀리초)으로 바꾼다 |
JPA를 켠 배포가 Hikari 바인딩 실패로 기동하지 않는다 | persistence-jpa 선택 |
| 2 | 옛 예시의 APP_SECURITY_CORS_MAX_AGE=600s를 600(초)으로 바꾼다 |
dev·prod 기동이 app.cors.max-age-seconds 바인딩 실패로 멈춘다(local은 profile 리터럴이 덮어 안 보인다) |
예시를 복사한 서비스 |
| 3 | 옛 예시에서 복사한 값 다섯을 확인한다: APP_CACHE_REDIS_COMMAND_TIMEOUT=2s, APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT=1s, APP_LOG_LEVEL_SQL=WARN, APP_SERVER_FORWARD_HEADERS_STRATEGY=native, APP_CACHE_REDIS_POSITIVE_SOFT_TTL=(빈 값). 새 예시는 기본값(200ms, 200ms, INFO, none, 30s)을 쓴다 |
그 값들이 env가 없을 때와 다르게 동작한다. 특히 native는 프록시를 거치지 않는 배포에서 호출자가 보낸 forwarded 헤더를 믿는다 |
예시를 복사한 서비스 |
| 4 | .env·배포 env에 남은 deprecated_orphaned 키(예: APP_CACHE_REDIS_TTL_JITTER, APP_SESSION_IDLE_TIMEOUT, APP_CACHE_REDIS_L1_*)를 지운다. 무엇이 대신하는지는 registry 행 주석에 있다 |
아무 일도 하지 않는 값을 켠 것으로 믿는다 | 예시를 복사한 서비스 |
| 5 | 서비스가 배포 설정(profile 파일 밖의 application.yml, config/*.yml, 모듈 config/module-defaults/*.yml)에 더한 placeholder는 접두어와 상관없이 registry에 행을 더하고, 행의 default를 placeholder 기본값과 같게 둔다 |
:app-bootstrap:verifyEnvKeys(mainCheck 안)가 실패한다 |
자기 placeholder를 더한 서비스 |
| 6 | .env.example의 값을 registry default(또는 행의 example)와 같게 둔다. 기본값이 있는 키를 빈 줄로 두지 않는다 |
같은 검사가 실패한다 | 자기 키를 예시에 더한 서비스 |
3. 다시 살린 registry 행
아래 셋은 2026-08-10 폐기로 적혀 있었지만, 2026-09-25 capability 포장 뒤로 cache-redis 모듈 설정이 다시 읽는다.
deprecated_orphaned를 지우고 기본값을 모듈 설정에 맞췄다.
| 키 | 읽는 곳 | 기본값 |
|---|---|---|
APP_CACHE_REDIS_COMMAND_TIMEOUT |
app.capabilities.cache.command-timeout |
200ms(registry가 2s라고 적었다) |
APP_CACHE_REDIS_SEMANTIC_REGION |
app.capabilities.cache.semantic-region |
default |
APP_CACHE_REDIS_KEY_HMAC_SECRET |
secret://environment/APP_CACHE_REDIS_KEY_HMAC_SECRET 참조 |
없음(비밀) |
4. 새로 등록한 이름
배포 설정이 읽는데 registry에 없던 이름이다. 이름은 그대로이고 동작도 같다.
SECURITY_PUBLIC_PATHS,PRESENTATION_API_BASE_PATH— APP_ 통일 전에 퍼진 이름이다. 바꾸면 파생 서비스의 배포 env가 소리 없이 무시되어 그대로 둔다.SPRING_BANNER_MODE,SPRING_JACKSON_DESER_*넷,SPRING_JACKSON_SER_WRITE_DATES_AS_TIMESTAMPS,SPRING_MAIN_LAZY_INITIALIZATION,SPRING_MAIN_LOG_STARTUP_INFO,SPRING_THREADS_VIRTUAL_ENABLED—application.ymlplaceholder 이름이다. Spring relaxed 이름도 같은 속성을 덮고, 둘 다 있으면 relaxed 이름이 이긴다.APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL— gRPC 모듈을 켠 배포가 기동하려면true로 명시하는 값이다..env.example에MANAGEMENT_SERVER_ADDRESS=127.0.0.1을 더했다. Kubernetes 프로브와 Prometheus는 pod IP로 붙으므로 원격에서 읽으려면 이 값을 바꾼다.