Spring Boot Actuator設定｜エンドポイント一覧と公開設定の雛形

Spring Boot Actuatorとは、動いているアプリケーションの状態（稼働状況・メトリクス・設定値など）をHTTPやJMXで取り出せるようにする機能です。 依存を1つ足すだけで使えますが、HTTPで最初から公開されるのは health だけで、ほかは「どれを公開するか」「どこまで操作を許すか」を設定で決めます。

この記事では、公式リファレンスに載っている全24エンドポイントの一覧、公開（exposure）とaccessの2段階の関係、環境別のapplication.yml全文3種、Actuatorだけを認証で守るSecurityFilterChain全文をまとめました。設定はそのまま貼って、IDやポートを書き換えて使える形にしています。

確認環境：Spring Boot 4.1.1 の公式リファレンス（docs.spring.io、確認日 2026年10月7日）で確認。掲載したYAMLはすべて Python 3.11 の PyYAML で構文チェック済みです。

Actuator設定の早見表

Actuatorを入れる手順と最初の状態

依存を1つ追加します。公式リファレンスが案内しているのはスターターの利用です。

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

追加した直後の状態は次のとおりです。「アクセスは許可されているが、HTTPに出ているのは health だけ」 という点を押さえると、あとの設定が読みやすくなります。

エンドポイント一覧（公式の全24件）

Spring Boot 4.1.1 の公式リファレンスに載っているIDをすべて並べました。「既定の公開」はHTTPでの初期状態、「外部公開の目安」は外部ネットワークから届く場所に置いてよいかの目安です（目安の列は本記事の整理で、公式の記載ではありません）。

どの種類のアプリでも使える21件

Webアプリ（Spring MVC・WebFlux・Jersey）で追加される3件

prometheus を使うときは、依存に micrometer-registry-prometheus を足します。公式リファレンスには「既定では利用できず、公開が必要」と書かれています。

Prometheus側の収集設定は、公式リファレンスの例では次の形です（HOST:PORT は自分の環境の値に置き換えます）。

scrape_configs:
- job_name: "spring"
  metrics_path: "/actuator/prometheus"
  static_configs:
  - targets: ["HOST:PORT"]

公開（exposure）とaccessの2段階を理解する

Actuatorのエンドポイントは、「access（どこまで操作を許すか）」と「exposure（HTTPやJMXに出すか）」の2つがそろって初めて外から使えます。 片方だけ設定しても届かないのは、この2段階のためです。

flowchart LR
  A[リクエスト] --> B{exposureに<br>含まれるか}
  B -- いいえ --> X[届かない]
  B -- はい --> C{accessは<br>noneか}
  C -- none --> X
  C -- read-only --> D[読み取りだけ可]
  C -- unrestricted --> E[読み書きとも可]

accessの3つの値

exposureとaccessの組み合わせ

設定キーの役割

include: "*" を本番向けに直す

開発中に便利な include: "*" は、すべてのIDをHTTPに出す設定です。本番向けには、出すIDを名前で列挙し、accessを「必要なものだけ許可」に切り替えると、意図しないIDが増えたときにも設定が守ってくれます。

直す前：

management:
  endpoints:
    web:
      exposure:
        include: "*"

直した後：

management:
  endpoints:
    web:
      exposure:
        include: "health,info,prometheus"
    access:
      default: none
      max-permitted: read-only
  endpoint:
    health:
      access: read-only
    info:
      access: read-only
    prometheus:
      access: read-only

access.default: none で全体をいったん閉じ、使うIDだけ read-only で開けています。max-permitted: read-only を置くと、あとから誰かが個別に unrestricted を書いても読み取りまでに抑えられます。

なお、* はYAMLで特別な意味を持つ文字なので、"*" と引用符で囲みます（公式リファレンスの例も引用符つきです）。

環境別のapplication.yml全文3種

開発用：すべて公開して中身を見る

手元での調査用です。全IDを公開し、healthの詳細と env の値も表示します。

# application-dev.yml（開発用）
management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: always
      show-components: always
    env:
      show-values: always
    configprops:
      show-values: always
  info:
    env:
      enabled: true
    java:
      enabled: true
    os:
      enabled: true

info:
  app:
    name: "task-api"
    description: "タスク管理API（開発環境）"

本番用：health・info・prometheusだけを別ポートで

アプリ本体は8080、Actuatorは8081に分けます。8081を外部に公開しないネットワーク構成にすれば、利用者からは届かず、監視サーバーからだけ読める形になります。

# application-prod.yml（本番用）
server:
  port: 8080

management:
  server:
    port: 8081
  endpoints:
    web:
      exposure:
        include: "health,info,prometheus"
    access:
      default: none
      max-permitted: read-only
  endpoint:
    health:
      access: read-only
      show-details: when-authorized
      show-components: when-authorized
      roles: "ENDPOINT_ADMIN"
    info:
      access: read-only
    prometheus:
      access: read-only
  info:
    env:
      enabled: true

info:
  app:
    name: "task-api"

同じホストの中からだけ読めれば足りる場合は、management.server.address を足します。公式リファレンスにあるとおり、アドレスを変えられるのは、ポートを本体と別にしたときだけです。

management:
  server:
    port: 8081
    address: "127.0.0.1"

Kubernetes用：livenessとreadiness

Spring Boot 4.0 から、livenessとreadinessのプローブは既定で有効です。/actuator/health/liveness と /actuator/health/readiness が使えます。Actuatorを別ポートにしている場合は、プローブだけ本体のポートにも出しておくと、「管理用ポートは応答するが本体が応答しない」状態を見分けやすくなります。

# application-k8s.yml（Kubernetes用）
server:
  port: 8080

management:
  server:
    port: 8081
  endpoints:
    web:
      exposure:
        include: "health,info,prometheus"
  endpoint:
    health:
      probes:
        enabled: true
        add-additional-paths: true
      group:
        readiness:
          include: "readinessState,db"

add-additional-paths: true にすると、liveness は /livez、readiness は /readyz として本体のポートでも使えるようになります。group.readiness.include に db を足しているのは、データベースにつながらない間はトラフィックを受けないようにするためです（db は DataSource があるときに使えるヘルス指標です）。

Kubernetes側のマニフェストは次のように書きます。パスは上の設定に合わせて本体ポートの /livez と /readyz を指しています。

# Deployment の containers[].の一部
livenessProbe:
  httpGet:
    path: "/livez"
    port: 8080
  failureThreshold: 3
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: "/readyz"
    port: 8080
  failureThreshold: 3
  periodSeconds: 10

failureThreshold と periodSeconds の値は例です。公式リファレンスの例では、Actuatorのポートで /actuator/health/liveness と /actuator/health/readiness を指す形が示されています。起動に時間がかかるアプリでは、livenessのHTTPプローブを使った startupProbe の追加も案内されています。

Actuatorだけを認証で守るSecurityFilterChain全文

Spring Securityを使っているアプリでは、Actuator用の SecurityFilterChain を分けて書くと、アプリ本体のルールと混ざりません。EndpointRequest.toAnyEndpoint() で「Actuatorのエンドポイントすべて」を対象にできます。 Spring Boot 4 ではこのクラスのパッケージが org.springframework.boot.security.autoconfigure.actuate.web.servlet になっています。

package com.example.taskapi.config;

import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class ActuatorSecurityConfiguration {

    @Bean
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) {
        // このチェーンは Actuator のエンドポイントだけを担当する
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests
                // 稼働確認とプローブは認証なしで通す
                .requestMatchers("/actuator/health", "/actuator/health/**").permitAll()
                // それ以外は ENDPOINT_ADMIN ロールが必要
                .anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic(withDefaults());
        return http.build();
    }

}

このコードは公式リファレンスの例（securityMatcher(EndpointRequest.toAnyEndpoint())、hasRole("ENDPOINT_ADMIN")、httpBasic）を土台に、health を認証なしで通す1行を足したものです。使うときの注意点を表にまとめます。

healthの表示設定（show-detailsとshow-components）

health は、設定によって返す情報の量が変わります。既定は never で、全体の状態（UP など）だけを返します。

値ごとの違い

show-details と show-components は同じ3つの値を取ります。when-authorized の「認可されたユーザー」は、management.endpoint.health.roles に書いたロールのどれかを持つユーザーです。roles を設定していない場合は、認証済みのユーザー全員が対象になります。

management:
  endpoint:
    health:
      show-details: when-authorized
      show-components: when-authorized
      roles: "ENDPOINT_ADMIN"

状態とHTTPステータスの対応

自動で用意されるヘルス指標

依存やBeanがそろうと、次の指標が health に加わります。個別に止めるときは management.health.<キー>.enabled を false に、まとめて止めるときは management.health.defaults.enabled を使います。

ヘルスグループで用途別にまとめる

指標をグループにすると、用途ごとに別のURLで確かめられます。次の例は db だけを含むグループ custom を作り、/actuator/health/custom で見られるようにします。

management:
  endpoint:
    health:
      group:
        custom:
          include: "db"
          show-details: "when-authorized"
          roles: "admin"

存在しない指標をグループに書くと、既定では起動時にエラーになります。management.endpoint.health.validate-group-membership を false にすると、この検査を止められます。

infoに出す項目の設定一覧

info は、有効になっている情報の提供元（InfoContributor）の内容をまとめて返します。有効・無効は management.info.<id>.enabled で切り替えます。

設定例の全文です。env を有効にすると、info. 以下に書いた値がそのまま返ります。

management:
  info:
    env:
      enabled: true
    java:
      enabled: true
    os:
      enabled: true
    process:
      enabled: true
    git:
      mode: "full"

info:
  app:
    name: "task-api"
    encoding: "UTF-8"
    java:
      source: "21"
      target: "21"

management.info.git.mode を full にするとGitの情報をすべて出し、management.info.git.enabled を false にするとGitの情報を出さなくなります。info は外部に見せる用途にも使えるので、載せる項目はアプリ名や版など、見せてよいものに絞るのがおすすめです。

パス・ポート・CORS・キャッシュの設定

パスを変える

management:
  endpoints:
    web:
      base-path: "/manage"

これで /actuator/{id} が /manage/{id} に変わります。個別のIDだけ変えたいときは path-mapping を使います。次の例では /actuator/health が /healthcheck になります。

management:
  endpoints:
    web:
      base-path: "/"
      path-mapping:
        health: "healthcheck"

management.server.port を設定していない場合、base-path は server.servlet.context-path（サーブレット系）からの相対パスになります。

HTTPでの公開をやめる

management:
  server:
    port: -1

または、すべてを公開対象から外します。

management:
  endpoints:
    web:
      exposure:
        exclude: "*"

CORSとキャッシュ

CORSは既定で無効で、allowed-origins を設定したときだけ有効になります。

management:
  endpoints:
    web:
      cors:
        allowed-origins: "https://example.com"
        allowed-methods: "GET,POST"

引数を取らない読み取り操作は、応答をキャッシュできます。次の例は beans の応答を10秒間キャッシュします。

management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"

版ごとの違い（Boot 1から4まで）

以前の版向けの記事や既存の設定ファイルを読むときに役立つ、名前と既定値の移り変わりです。公式のマイグレーションガイドとリリースノート（確認日 2026年10月7日）で確認できたものだけを載せています。

以前の設定を書き換える対応表

つまずきやすい点と直し方

本番に出す前のチェックリスト

• [ ] exposure.include は "*" ではなく、IDを名前で列挙している
• [ ] access.default と max-permitted で、操作範囲の既定と上限を決めている
• [ ] shutdown と heapdump を公開対象に入れていない
• [ ] env・configprops の show-values は never か when-authorized になっている
• [ ] health の show-details は never か when-authorized になっている
• [ ] Actuatorのポートやパスは、外部ネットワークから届かない経路に置いている
• [ ] Spring Securityを使う場合、Actuator用のルールを SecurityFilterChain に書いている
• [ ] Kubernetesのプローブのパスとポートが、アプリの設定と一致している

よくある質問

Q. management.endpoints.web.exposure.include と management.endpoint.<id>.access はどう違いますか？ A. exposure は「HTTPやJMXに出すかどうか」、access は「どこまでの操作を許すか」です。外から使うには、公開対象に入っていて、かつ access が none でないことが必要です。

Q. health 以外も最初から見られるようにできますか？ A. management.endpoints.web.exposure.include にIDを足すと見られます。開発中は "*"、本番では "health,info,prometheus" のように名前で列挙する形が扱いやすいです。

Q. Actuatorを別ポートにする利点は何ですか？ A. アプリ本体と管理用の入口を分けられるので、管理用のポートだけを外部に公開しない構成にできます。プローブを本体側でも確かめたいときは、add-additional-paths で /livez と /readyz を本体ポートに出せます。

Q. enabled を使った以前の設定は書き換えが必要ですか？ A. management.endpoint.<id>.enabled と management.endpoints.enabled-by-default は Spring Boot 3.4 で非推奨になりました。新しく書く設定は access と access.default を使うと、今後の版でもそのまま読めます。

まとめ

• 追加直後にHTTPで公開されるのは health だけ。ほかは exposure.include で選ぶ
• 外から使えるのは、exposureに含まれ、かつaccessが none でないID。2段階で考える
• accessは unrestricted／read-only／none の3つ。access.default と max-permitted で全体を決める
• 本番は "health,info,prometheus" のように名前で列挙し、別ポートに分けると管理しやすい
• Spring Boot 4 ではlivenessとreadinessのプローブが既定で有効。/livez・/readyz も使える
• health の詳細と env の値は既定で伏せられている。見せる相手を when-authorized と roles で決める
• 以前の設定は enabled→access、httptrace→httpexchanges に読み替える

参考・出典

確認日はすべて 2026年10月7日 です。

• Spring Boot リファレンス Endpoints（4.1.1）：https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
• Spring Boot リファレンス Monitoring and Management Over HTTP（4.1.1）：https://docs.spring.io/spring-boot/reference/actuator/monitoring.html
• Spring Boot リファレンス Enabling Production-ready Features（4.1.1）：https://docs.spring.io/spring-boot/reference/actuator/enabling.html
• Spring Boot リファレンス Metrics（4.1.1）：https://docs.spring.io/spring-boot/reference/actuator/metrics.html
• Spring Boot 4.0 Migration Guide：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
• Spring Boot 3.4 Release Notes：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.4-Release-Notes
• Spring Boot 3.0 Migration Guide：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide
• Spring Boot 2.5 Release Notes：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.5-Release-Notes
• Spring Boot 2.0 Migration Guide：https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide
• Spring Boot プロジェクトページ（現行 4.1.1）：https://spring.io/projects/spring-boot

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。