10 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Spring Boot Actuator — Separate management.server.port | official-doc | https://docs.spring.io/spring-boot/reference/actuator/monitoring.html | raw | high |
|
|
|
2026-05-22 | 2026-05-27 |
Spring Boot Actuator — Separate management.server.port
Layer:
raw/official-docs/— Spring Boot 공식 reference (Actuator Monitoring and Management over HTTP) 원문 발췌. ca-tmplfeature-management-actuator-security-contract의management port = 9001 (separate)결정 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-management-actuator-security-contract | management port 분리 (9001) 채택 + "single-port + ingress 보호" 도 공식 허용 옵션이라는 baseline 근거 |
컨텍스트
feature-management-actuator-security-contract ca-tmpl 이 결정한 management port = 9001 (separate) 가 Spring Boot 가 공식 지원하는 패턴인지 확인. baseline 의 "single port 는 platform ingress 보호 + 문서화 시만 허용" 결정의 근거.
출처 / Source
- 원본 URL: https://docs.spring.io/spring-boot/reference/actuator/monitoring.html
- 관련 property:
management.server.port,management.server.address,management.server.ssl.* - 아카이브 URL: (미수집)
- 저자 / 조직: Spring Team (VMware / Broadcom)
- 발행일: Spring Boot 3.x reference
- 마지막 확인일: 2026-05-27
핵심 인용 / Key quotes (verbatim)
[§Monitoring and Management over HTTP — Customizing the Management Server Port] "Exposing management endpoints by using the default HTTP port is a sensible choice for cloud-based deployments."
[§Monitoring and Management over HTTP — Customizing the Management Server Port] "If, however, your application runs inside your own data center, you may prefer to expose endpoints by using a different HTTP port."
[§Monitoring and Management over HTTP — Customizing the Management Server Port] "You can set the
management.server.portproperty to change the HTTP port, as the following example shows:"
[§Monitoring and Management over HTTP — Configuring Management-specific SSL] "When configured to use a custom port, you can also configure the management server with its own SSL by using the various
management.server.ssl.*properties."
[§Monitoring and Management over HTTP — Configuring Management-specific SSL] "For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as the following property settings show:"
[§Monitoring and Management over HTTP — Customizing the Management Server Address] "You can customize the address on which the management endpoints are available by setting the
management.server.addressproperty. Doing so can be useful if you want to listen only on an internal or ops-facing network or to listen only for connections fromlocalhost."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SB-ACT-PORT-C1 | cloud 기반 배포에서는 management endpoint 를 default HTTP port (application 과 동일) 로 노출하는 것이 sensible choice | [§Customizing the Management Server Port] "Exposing management endpoints by using the default HTTP port is a sensible choice for cloud-based deployments." | official-vendor-doc |
cloud / managed platform 배포 (heroku, app runner, k8s ingress 등) | "default port 가 모든 cloud 환경에서 보안 충분" 이라는 뜻은 아님 — ingress / network policy 측 보호 필요 |
| SB-ACT-PORT-C2 | 자체 데이터센터 운영 시 별도 HTTP port 로 management endpoint 노출이 preferable 할 수 있음 (공식 옵션) | [§Customizing the Management Server Port] "If, however, your application runs inside your own data center, you may prefer to expose endpoints by using a different HTTP port." | official-vendor-doc |
self-managed infra / data-center / on-prem | "별도 port 가 always-better" 라는 의미는 아님 — 선택지로 명시 |
| SB-ACT-PORT-C3 | management.server.port property 로 HTTP port 변경 가능 |
[§Customizing the Management Server Port] "You can set the management.server.port property to change the HTTP port, as the following example shows:" |
official-vendor-doc |
Spring Boot Actuator 가 활성된 모든 환경 | port 만 분리해도 ACL / firewall 이 별도 보장돼야 노출 위험 차단 — 본 인용은 mechanism 만 |
| SB-ACT-PORT-C4 | custom port 사용 시 management.server.ssl.* 로 main app 과 별개로 SSL 구성 가능 |
[§Configuring Management-specific SSL] "When configured to use a custom port, you can also configure the management server with its own SSL by using the various management.server.ssl.* properties." |
official-vendor-doc |
management port 가 main app port 와 다른 경우 | default port 공유 시에도 별도 SSL 가능하다는 뜻은 아님 — custom port 가 전제 |
| SB-ACT-PORT-C5 | 예: main app HTTPS + management server HTTP 분리 운영이 공식 예시로 제시됨 | [§Configuring Management-specific SSL] "For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as the following property settings show:" | official-vendor-doc |
TLS termination 정책이 management ↔ app 다른 환경 | management HTTP 가 항상 안전하다는 뜻은 아님 — 내부망 / 신뢰 ACL 전제 |
| SB-ACT-PORT-C6 | management.server.address 로 listen 주소 한정 가능 (internal / ops-facing / localhost only) |
[§Customizing the Management Server Address] "You can customize the address on which the management endpoints are available by setting the management.server.address property. Doing so can be useful if you want to listen only on an internal or ops-facing network or to listen only for connections from localhost." |
official-vendor-doc |
multi-NIC 또는 명시적 bind 가 필요한 환경 | bind address 변경이 firewall / network policy 를 대체한다는 뜻은 아님 — defense-in-depth 한 레이어 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
SB-ACT-PORT-C1~C2: default port (cloud) vs separate port (data center) 의 공식 사용 권고 양면SB-ACT-PORT-C3~C5:management.server.port+management.server.ssl.*mechanism 과 HTTPS app / HTTP management 예시SB-ACT-PORT-C6:management.server.address로 bind 주소 한정 가능
- 이 자료가 증명하지 않는 것:
- "separate port = 항상 더 안전" 같은 universal best practice (공식 문서는 두 옵션 모두 합리적이라고 명시)
- 9001 port 가 Spring Boot 의 권장 default 라는 점 (port 번호는 사용자 선택)
- mTLS for management (
SB-ACT-PORT-C4는 SSL 분리만 명시, client cert 요구는 별도) - service mesh (Istio PeerAuthentication 등) 와의 통합 권장 사항
- 내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 Kubernetes deployment 가 single Service + dual containerPort (8080 + 9001) 로 떨어지는지, 아니면 dedicated management Service 가 별도로 떠야 하는지
- 9001 port 가 LoadBalancer / NodePort 로 실수 노출되지 않도록 network policy 설정 검증 (
management.server.address=127.0.0.1또는 cluster-internal IP 만 bind) - mTLS for management 요구 시
management.server.ssl.client-auth=need와 client cert 발급 / rotation 정책
ca-tmpl 함의 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아니라 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시
wiki/projects/ca-skeleton-operational-contractsource-summary 로 이전.
- ca-tmpl 9001 결정의 공식 근거:
- 공식 문서가 "different HTTP port" 옵션을 직접 권고 (
SB-ACT-PORT-C2,C3) → ca-tmpl 9001 결정은 공식 옵션 따른 것. - cloud 환경에서는 "default port + path ACL" 도 sensible default 라고 공식이 인정 (
SB-ACT-PORT-C1) → ca-tmpl 의 "platform ingress 보호 + 문서화 시 single-port 허용" 도 정합.
- 공식 문서가 "different HTTP port" 옵션을 직접 권고 (
- 대안 그룹 (ca-tmpl 결정 비교용):
- 대안 1 (single port + path ACL): cloud / Kubernetes ingress 환경. ingress rule 이
/actuator/*를 internal LB 로 routing. - 대안 2 (separate port = ca-tmpl baseline): management port + ACL. data-center / self-managed.
- 대안 3 (mTLS for management): management port + client cert. zero-trust.
- 대안 4 (Service mesh — Istio sidecar): PeerAuthentication + AuthorizationPolicy 로 management path 만 internal traffic 허용.
- 대안 1 (single port + path ACL): cloud / Kubernetes ingress 환경. ingress rule 이
- 장점: app port (8080) 와 다른 firewall / ACL rule 적용 가능. 실수로 ingress 가 management endpoint 를 publish 할 위험 ↓. port-level monitoring 분리 (latency budget 분리).
- 단점: container / network 운영 부담 (두 port expose). Kubernetes Service 정의 한 번 더 필요. cloud LB 비용 ↑ 가능.
메모 / Notes
- 2026-05-27 재검증: 6개 핵심 인용 모두 verbatim 으로 monitoring reference 의 해당 섹션에 존재 확인. management.server.port 예시 (
management.server.port=8081) 도 공식 예시 그대로. - 다음 fetch 후보:
https://docs.spring.io/spring-boot/reference/actuator/monitoring.html#actuator.monitoring.customizing-management-server-context-path(path prefix 변경)https://docs.spring.io/spring-boot/reference/actuator/monitoring.html#actuator.monitoring.enabling-cross-origin-requests(CORS for actuator)
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/actuator-endpoint-exposure-spring-official — endpoint exposure default
- raw/official-docs/runtime-health-spring-actuator-groups — health group 모델
- 인용하는 branch:
- 인용하는 project:
- 인용한 wiki 요약: (미작성)