11 KiB
11 KiB
title, source_type, url, archive_url, status, confidence, tags, related_branches, related_projects, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_branches | related_projects | created | last_reviewed | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Spring Cloud Kubernetes — ConfigMap PropertySource + reload 공식 문서 | official-doc | https://docs.spring.io/spring-cloud-kubernetes/docs/current/reference/html/ | raw | high |
|
|
|
2026-05-22 | 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
ConfigMapinstances available during application startup and triggers hot reloading of beans or Spring context when changes are detected on observedConfigMapinstances."
[§Reload feature — enable property] "By default, this feature is disabled. You can enable it by using the
spring.cloud.kubernetes.reload.enabled=trueconfiguration property (for example, in theapplication.propertiesfile)."
[§Reload feature — strategy levels] "The following levels of reload are supported (by setting the
spring.cloud.kubernetes.reload.strategyproperty):
refresh(default): Only configuration beans annotated with@ConfigurationPropertiesor@RefreshScopeare reloaded. This reload level leverages the refresh feature of Spring Cloud Context.restart_context: the whole SpringApplicationContextis 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 endpointshutdown: the SpringApplicationContextis 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 theApplicationContextand 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 명시 안 됨 — 별도 확인 필요).
- ConfigMap/Secret 을 Spring
- 단점:
- 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:
- 적용 contract:
- raw/project-notes/ca-skeleton-operational-contract (Env-driven runtime configuration 그룹)
- 인용하는 wiki: (미작성)