llm-wiki/raw/official-docs/config-spring-cloud-kubernetes-configmap-reload.md

---
title: Spring Cloud Kubernetes — ConfigMap PropertySource + reload 공식 문서
source_type: official-doc
url: https://docs.spring.io/spring-cloud-kubernetes/docs/current/reference/html/
archive_url:
status: raw
confidence: high
tags: [ca-tmpl, config, kubernetes, configmap, spring-cloud-kubernetes, alternative, official-doc]
related_branches: [feature-env-driven-runtime-configuration, feature-runtime-health-lifecycle-contract, feature-secrets-config-source-contract]
related_projects: [ca-skeleton]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Spring Cloud Kubernetes — ConfigMap PropertySource + Reload

> Layer: `raw/official-docs/` — Spring Cloud Kubernetes reference docs (current) 의 ConfigMap PropertySource + Reload 섹션 verbatim 발췌.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-env-driven-runtime-configuration]] | 대안 2 (Spring Cloud Kubernetes ConfigMap + auto-reload) 의 비용/이득 비교. branch 의 "no runtime reload, platform rolling restart 로 통일" 결정과 정면 비교 |
| [[raw/branch-notes/feature-runtime-health-lifecycle-contract]] | `restart_context` / `shutdown` reload 전략의 graceful restart 의미 비교 (lifecycle contract 와 정렬) |
| [[raw/branch-notes/feature-secrets-config-source-contract]] | Secrets API consumption 이 RBAC 보안 이유로 default disabled, volume mount 가 권장 — secret source-of-truth 결정 근거 |

## 컨텍스트 / 왜 저장했는지

ca-tmpl `feature-env-driven-runtime-configuration` branch 의 **대안 2**. Kubernetes ConfigMap 을 PropertySource 로 직접 바인딩하고 변경 시 hot reload 하는 메커니즘. branch 의 "no runtime reload" 결정과 정면 충돌하는 접근. 두 결정을 명확히 분리하기 위한 비교 자료.

## 출처 / Source

- 원본 URL: https://docs.spring.io/spring-cloud-kubernetes/docs/current/reference/html/
- 아카이브 URL: (미수집)
- 저자 / 조직: Spring Cloud Team (spring-projects)
- 발행일: 지속 업데이트 (current docs)
- GitHub: github.com/spring-cloud/spring-cloud-kubernetes
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Spring Cloud Kubernetes Config — intro] "The Spring Cloud Kubernetes Config project makes Kubernetes `ConfigMap` instances available during application startup and triggers hot reloading of beans or Spring context when changes are detected on observed `ConfigMap` instances."

> [§Reload feature — enable property] "By default, this feature is disabled. You can enable it by using the `spring.cloud.kubernetes.reload.enabled=true` configuration property (for example, in the `application.properties` file)."

> [§Reload feature — strategy levels] "The following levels of reload are supported (by setting the `spring.cloud.kubernetes.reload.strategy` property):
> - `refresh` (default): Only configuration beans annotated with `@ConfigurationProperties` or `@RefreshScope` are reloaded. This reload level leverages the refresh feature of Spring Cloud Context.
> - `restart_context`: the whole Spring `ApplicationContext` is gracefully restarted. Beans are recreated with the new configuration. In order for the restart context functionality to work properly you must enable and expose the restart actuator endpoint
> - `shutdown`: the Spring `ApplicationContext` is shut down to activate a restart of the container. When you use this level, make sure that the lifecycle of all non-daemon threads is bound to the `ApplicationContext` and that a replication controller or replica set is configured to restart the pod."

> [§Secrets PropertySource — API consumption] "By default, consuming Secrets through the API (points 2 and 3 above) **is not enabled** for security reasons. The permission 'list' on secrets allows clients to inspect secrets values in the specified namespace. Further, we recommend that containers share secrets through mounted volumes."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SCK-CONFIG-C1 | Spring Cloud Kubernetes Config 는 application startup 시 ConfigMap 을 사용 가능하게 만들고, 관찰 중인 ConfigMap 변경 감지 시 bean / Spring context 의 hot reload 를 trigger | [§Spring Cloud Kubernetes Config — intro] "The Spring Cloud Kubernetes Config project makes Kubernetes `ConfigMap` instances available during application startup and triggers hot reloading of beans or Spring context when changes are detected on observed `ConfigMap` instances." | `official-vendor-doc` | Spring Cloud Kubernetes Config 의존성 추가된 Spring Boot app | 변경 감지가 watch API 인지 polling 인지는 본 인용 범위 밖 (별도 페이지 확인 필요) |
| SCK-RELOAD-C1 | reload feature 는 기본 disabled. `spring.cloud.kubernetes.reload.enabled=true` 로 활성화 | [§Reload feature — enable property] "By default, this feature is disabled. You can enable it by using the `spring.cloud.kubernetes.reload.enabled=true` configuration property (for example, in the `application.properties` file)." | `official-vendor-doc` | Spring Cloud Kubernetes 의존성 사용 시 reload 옵트인 | 활성화 시 부수 효과 (RBAC 권한 요구, watch overhead) 는 본 인용 범위 밖 |
| SCK-RELOAD-C2 | reload strategy 는 3가지: `refresh` (default, `@ConfigurationProperties` / `@RefreshScope` bean 만 reload), `restart_context` (전체 `ApplicationContext` graceful restart), `shutdown` (`ApplicationContext` shutdown 으로 container 재시작 유도) | [§Reload feature — strategy levels] "The following levels of reload are supported (by setting the `spring.cloud.kubernetes.reload.strategy` property): `refresh` (default): ... / `restart_context`: ... / `shutdown`: ..." | `official-vendor-doc` | reload strategy 선택 결정 | 각 strategy 의 정확한 latency 와 in-flight request 처리 동작은 본 인용 범위 밖. `restart_context` 가 in-process 인지 process restart 인지의 차이도 본 인용으로 직접 증명 안 됨 (단 "the whole Spring ApplicationContext is gracefully restarted" 는 in-process) |
| SCK-RELOAD-C3 | `restart_context` strategy 가 동작하려면 restart actuator endpoint 를 enable + expose 해야 함 | [§Reload feature — strategy levels] "In order for the restart context functionality to work properly you must enable and expose the restart actuator endpoint" | `official-vendor-doc` | `restart_context` strategy 선택 시 | restart endpoint 노출의 보안 영향 (인증/RBAC) 은 본 인용 범위 밖 |
| SCK-RELOAD-C4 | `shutdown` strategy 사용 시 non-daemon thread lifecycle 이 `ApplicationContext` 에 bound 되어야 하고, ReplicationController / ReplicaSet 이 pod restart 를 담당해야 함 | [§Reload feature — strategy levels] "When you use this level, make sure that the lifecycle of all non-daemon threads is bound to the `ApplicationContext` and that a replication controller or replica set is configured to restart the pod." | `official-vendor-doc` | `shutdown` strategy 선택 시 | k8s Deployment (ReplicaSet 의 상위 abstraction) 도 동일하게 동작하는지는 본 인용으로 직접 증명 안 됨 (관례적으로 yes, 단 문서는 RC/RS 만 언급) |
| SCK-SECRETS-C1 | Secrets 의 API consumption 은 보안 이유로 default disabled. `list` 권한이 namespace 의 secret values 를 노출시키므로, container 가 mounted volume 으로 secret 을 공유하는 것이 권장 | [§Secrets PropertySource — API consumption] "By default, consuming Secrets through the API (points 2 and 3 above) **is not enabled** for security reasons. The permission 'list' on secrets allows clients to inspect secrets values in the specified namespace. Further, we recommend that containers share secrets through mounted volumes." | `official-vendor-doc` | Spring Cloud Kubernetes Secrets PropertySource 사용 결정 | mounted volume 방식의 reload 지원 여부 (file watch?) 는 본 인용 범위 밖 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `SCK-CONFIG-C1`: ConfigMap PropertySource 와 hot reload trigger 의 존재
  - `SCK-RELOAD-C1~C4`: 3-level reload strategy 의 정확한 이름과 활성화 조건
  - `SCK-SECRETS-C1`: Secrets API consumption 의 default-disabled + mounted volume 권장 보안 정책
- **이 자료가 증명하지 않는 것**:
  - "k8s 환경에서 hot reload 가 항상 권장된다" — 본 인용은 capability 만 제공, 권장 시점은 다루지 않음
  - ca-tmpl 의 "no runtime reload" 결정이 틀렸다는 근거 — 본 자료는 대안의 capability 만 보여줌
  - reload 가 in-flight request 를 어떻게 처리하는지의 정확한 의미론
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - `refresh` 전략에서 `@RefreshScope` 가 아닌 bean (e.g., singleton config holder) 의 stale state 노출 가능성
  - `restart_context` 의 graceful restart 가 실제로 in-flight HTTP request 를 drain 하는지
  - k8s watch API 의 권한 요구사항 (RBAC) 과 ca-tmpl 의 RBAC 정책 정렬
  - **company tech blog 사례를 "Spring 공식 best practice" 로 일반화 금지** — 본 raw 는 공식 reference docs 의 capability 만 다룸

## 메모 / Notes (내 프로젝트 해석 — PRESERVED)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- 적용 시나리오: Kubernetes 전용 배포 환경. config 변경 시 rolling restart 비용이 크고 (e.g. stateful workload) hot reload 가 필요할 때.
- 장점:
  - ConfigMap/Secret 을 Spring `Environment` 에 1급 PropertySource 로 통합.
  - 3-level reload (`refresh` / `restart_context` / `shutdown`) — refresh 전략이 default.
  - k8s watch API 기반이므로 polling 부담 적음 (단 본 raw 인용으로는 watch vs polling 명시 안 됨 — 별도 확인 필요).
- 단점:
  - **Kubernetes 종속**. ECS / Cloud Run / VM 배포에는 부적용.
  - reload 중 부분 상태 (일부 bean 만 refresh) → "silent changed behavior" 리스크. branch 가 forbidden 으로 명시한 항목.
  - Secrets API consumption 은 기본 disabled (RBAC `list secrets` 권한 위험성 때문). volume mount 가 권장.
- ca-tmpl 결정과의 차이:
  - ca-tmpl: env 주입 + no runtime reload. config 변경은 platform 의 rolling restart 로 처리.
  - Spring Cloud Kubernetes Reload: in-process reload. **`restart_context` 전략은 사실상 rolling restart 와 유사**해서 ca-tmpl 입장에서는 platform restart 로 통일하는 게 더 단순 (해석 — 본 자료 직접 증명 아님).
- branch 가 이 대안을 선택하지 않은 명시적 이유: "platform 이 rolling restart 로 config 변경을 처리" 가 12-factor 와 정합하고, in-process reload 는 partial-state 디버깅 비용이 큼.
- 신뢰도: `official-vendor-doc` 등급.

## Related / 관련

- 같은 주제 다른 raw:
  - [[raw/official-docs/config-aws-appconfig-feature-flag-deployment]] (대안 3 — AWS managed runtime config)
- 인용하는 branch:
  - [[raw/branch-notes/feature-env-driven-runtime-configuration]]
  - [[raw/branch-notes/feature-runtime-health-lifecycle-contract]]
  - [[raw/branch-notes/feature-secrets-config-source-contract]]
- 적용 contract:
  - [[raw/project-notes/ca-skeleton-operational-contract]] (Env-driven runtime configuration 그룹)
- 인용하는 wiki: (미작성)