# 업그레이드 안내 — 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.yml` placeholder 이름이다. Spring relaxed 이름도 같은 속성을 덮고, 둘 다 있으면 relaxed 이름이 이긴다. - `APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL` — gRPC 모듈을 켠 배포가 기동하려면 `true`로 명시하는 값이다. - `.env.example`에 `MANAGEMENT_SERVER_ADDRESS=127.0.0.1`을 더했다. Kubernetes 프로브와 Prometheus는 pod IP로 붙으므로 원격에서 읽으려면 이 값을 바꾼다.