llm-wiki/raw/official-docs/actuator-management-port-spring-official.md

---
title: Spring Boot Actuator — Separate management.server.port
source_type: official-doc
url: https://docs.spring.io/spring-boot/reference/actuator/monitoring.html
archive_url:
status: raw
confidence: high
tags: [ca-actuator, spring-boot, actuator, management-port, network-isolation]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-management-actuator-security-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Spring Boot Actuator — Separate management.server.port

> Layer: `raw/official-docs/` — Spring Boot 공식 reference (Actuator Monitoring and Management over HTTP) 원문 발췌.
> ca-tmpl `feature-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.port` property 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.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`."

## 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-contract` source-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 허용" 도 정합.
- **대안 그룹 (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 허용.
- **장점**: 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:
  - [[raw/branch-notes/feature-management-actuator-security-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)