Spring Boot Actuator入門｜health・infoの公開範囲と本番運用

2026年10月15日

Spring Boot Actuatorを追加すると、アプリケーションの状態や運用情報をHTTP経由で確認できるようになります。一方で、設定値や環境情報を返すエンドポイントまで不用意に公開すると、運用情報を外部へ見せてしまうおそれがあります。

この記事では、health と info を入口に、エンドポイントの利用可否・公開・認証の違い、本番での公開範囲、KubernetesのLiveness・Readinessを整理します。設定例はSpring Boot 4.1を対象としています。採用するSpring Bootのバージョンと環境に合わせて設定を確認してください。

Actuatorで分かること・分からないこと

Actuatorは、アプリケーションの監視や管理に使うエンドポイントを提供するSpring Bootの機能です。たとえば health はアプリケーションの状態を返し、info はアプリケーションが公開する情報を返します。ほかにも、設定プロパティ、ログレベル、メトリクス、マッピングなど、目的別のエンドポイントがあります。

ただし、Actuatorを入れれば運用監視がすべて完結するわけではありません。healthは設定されたHealthIndicatorの状態を集約した情報であり、利用者から見たすべての機能の正常性を確認するには、別途監視が必要です。ログの調査、メトリクスの継続収集、分散トレース、アラートの設計などは、それぞれ別に検討が必要です。

エンドポイントは「追加したら全部公開」ではない

Actuatorのエンドポイントが利用可能になるには、アクセスが許可され、かつHTTPやJMXなど対象の手段へ公開されている必要があります。Spring Boot 4.1では、HTTPで公開されるエンドポイントは既定で health のみです。エンドポイントの利用可否と公開範囲は別の設定なので、片方だけを確認して「安全」または「使える」と判断しないようにしましょう。

Actuatorの依存関係を追加する

Mavenを使う場合は spring-boot-starter-actuator を依存関係に追加します。Spring Bootの依存関係管理を使っているプロジェクトでは、他のSpring Boot依存関係と同様に、個々のstarterへバージョンを直接書かずに管理する構成が一般的です。Gradleでも同じartifactを依存に追加できます。

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

依存関係を追加して起動しただけでは、HTTP上で使えるエンドポイントがすべて見えるわけではありません。標準のベースパスは /actuator で、healthなら /actuator/health です。実際のパスは、コンテキストパスやActuator側のベースパス、管理用ポートの設定によって変わることがあります。

health と info を公開する最小設定

health はHTTPで既定公開されます。info を追加する場合は、公開するエンドポイントを明示します。さらに、info.* のプロパティを info 応答に載せるには、env情報提供者を有効にする設定も必要です。エンドポイントの公開設定と、応答へ載せる情報の設定は別々です。

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  info:
    env:
      enabled: true

info:
  app:
    name: sample-app
    description: Sample application

この例では info.app.name など、公開しても差し支えない固定情報だけを登録します。パスワード、トークン、接続文字列、内部ホスト名、顧客情報などを info.* に書かないでください。設定に含まれた値は、公開範囲を広げた際に意図せず応答へ含まれる可能性があります。

healthの応答に詳細を出す前に確認する

healthのURLが応答しても、コンポーネントごとの詳細が常に表示されるわけではありません。Spring Boot 4.1では、show-details の既定値は never です。show-components を個別に設定していない場合は show-details の設定が使われるため、どちらも未設定なら詳細・コンポーネントは表示されません。show-details を変更するとコンポーネント表示も連動する点に注意し、必要なら両設定を明示的に分けます。認証済み利用者に限って詳細を見せたい場合は when-authorized と役割設定を検討できます。always は詳細をすべての利用者に表示する設定なので、公開環境で安易に有効化しないでください。

詳細の中身は、導入しているHealthIndicatorやアプリケーション側の実装に左右されます。データベース製品名、内部サービスの状態、例外メッセージなどが運用情報として現れる可能性があります。設定を変えたら、認証あり・なしの両方で実際の応答を確認し、想定外の情報が出ていないか点検します。

エンドポイントの利用可否・公開・認証を区別する

本番設定では、次の3つを分けて確認します。

利用可否：そのエンドポイントをアプリケーションコンテキストに含めるか。全体の既定値や個別endpointのaccess設定で制御します。
公開：HTTPまたはJMXのどちらへ公開するか。HTTPの場合はexposureのinclude/excludeで制御します。
認証・認可：公開された経路へ誰がアクセスできるか。Spring Securityやネットワーク境界などで制御します。

一例として、HTTPのincludeへ health,info を設定しても、すべてのActuator機能が有効になるわけではありません。また、includeに項目を追加しただけで認証が設定されるわけでもありません。excludeはincludeより優先されます。特に * を指定すると公開範囲が大きくなるため、必要なendpoint IDだけを指定する方針が基本です。

Spring Securityを使う場合の注意点

Spring Securityがクラスパスにあり、アプリケーション独自の SecurityFilterChain がない場合、Spring Bootは既定のセキュリティ設定でhealth以外のActuator endpointを保護します。一方、アプリケーションで独自の SecurityFilterChain を定義すると、Spring BootのActuator向け自動セキュリティ設定は後退し、アクセスルールをアプリケーション側で構成する必要があります。

たとえば、Actuator経路を運用担当者向けロールで保護する構成は次のように書けます。Spring Boot 4.1系のServlet/MVC向けの例です。既存のセキュリティ設定へ組み込む際は、一般画面やAPIを含む残りの経路にも適切なルールを別途設定し、チェーンの優先順位と一致条件を確認してください。

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.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
class ActuatorSecurityConfiguration {

    @Bean
    SecurityFilterChain actuatorSecurity(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(requests -> requests
                .anyRequest().hasRole("ACTUATOR_ADMIN"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

このコードはHTTP Basic認証とロール判定の例です。実際の認証方式、CSRF、管理画面へのアクセス、複数のセキュリティチェーンの構成はアプリケーションの要件に合わせてください。Actuatorの設定を追加しただけで、認証やネットワーク制御が自動的に完成するわけではありません。

Healthの詳細情報を安全に扱う

health は死活監視だけでなく、HealthIndicatorが報告するコンポーネント状態を集約します。外部からの確認に必要な最小限の状態と、運用担当者が調査に使う詳細情報を同じ公開範囲にしないよう設計するのがポイントです。

外部監視用の応答は、アプリケーションが応答可能か判断するための最小限にする。
コンポーネント名や詳細状態は、認証された運用担当者だけに見せる設定を検討する。
接続先の名前、内部IP、例外メッセージ、秘密情報が含まれないか実レスポンスで確認する。
HealthIndicatorを独自実装する場合は、エラー時に返す詳細もログと同様に情報漏えいの観点から見直す。

別ポートへ管理エンドポイントを移すことは、アクセス経路を分ける手段のひとつです。しかし、ポートを分けただけでは認証・認可やファイアウォール設定の代わりになりません。外部から到達できるアドレス、クラウド側のセキュリティグループ、コンテナやサービスメッシュの経路など、実際のネットワーク構成も合わせて確認してください。

KubernetesのLiveness・Readinessを使い分ける

Kubernetesでアプリケーションを動かす場合、ActuatorはLivenessとReadinessのprobeをhealth groupとして提供できます。Spring Bootはアプリケーションのavailability状態から、それぞれ /actuator/health/liveness と /actuator/health/readiness を公開します。どのポートへ到達するかは、Actuatorの管理ポートを分けているかどうかによって変わります。

Liveness：プロセスが内部的に回復不能な状態かを判断し、失敗時にはコンテナ再起動につながるprobe。
Readiness：そのインスタンスへ新しいリクエストを流してよいかを判断し、失敗時にはトラフィックから外すprobe。

特に注意したいのは、Livenessにデータベースや外部APIなどの依存先チェックを安易に含めないことです。共有データベースが一時的に停止したときに全インスタンスのLivenessが失敗すると、Kubernetesがアプリケーションを次々に再起動し、復旧を難しくする可能性があります。外部依存の確認をReadinessへ含めるかどうかも、サービスから外す影響や代替処理の有無を踏まえて個別に判断します。

また、Actuatorを別の管理ポートで動かしていると、そのポートだけが応答できてアプリケーション本体のHTTPサーバーは応答できない、という状態をprobeが見逃す場合があります。公式資料ではprobe groupをメインサーバーポートにも追加する設定が案内されています。どのポートを監視するかは、実際のデプロイ構成と合わせて決めましょう。

management:
  endpoint:
    health:
      probes:
        add-additional-paths: true

この設定を使うと、Spring Boot 4.1ではメインサーバーポートに /livez と /readyz の追加パスが用意されます。インフラ側のprobeが実際にどのパス・ポートを見ているか、認証やIngressの制限によりprobeが拒否されないかも確認してください。probeの閾値や間隔は、アプリケーションの起動時間・停止処理を考慮して設定します。

本番公開前の確認項目

依存関係に対応するSpring Bootのバージョンを確認した。
HTTP/JMXのexposureに、運用上必要なendpointだけを指定した。
endpointの利用可否とexposureを別々に確認した。
info に秘密情報、内部ホスト名、個人情報を含めていない。
health のdetails/componentsが公開範囲に合っている。
独自の SecurityFilterChain がある場合、Actuatorとアプリケーション本体の両方にルールを設定した。
管理ポートを分ける場合、ネットワークからの到達可否・認証・ファイアウォールを確認した。
KubernetesではLivenessとReadinessの役割を分け、Livenessへ外部依存を混ぜていない。
設定変更後、認証あり・なしのHTTP応答と運用監視側のprobe結果を確認した。

確認時には、ブラウザーで一度アクセスするだけでなく、アプリケーション設定、プロキシ、認証設定、ネットワーク制御を含めて経路全体を追います。監視システムが成功していても、実ユーザーのリクエスト経路とは異なるポートやホストを見ている場合があるためです。

よくある404・401・403の確認ポイント

ActuatorのURLでエラーが返った場合は、まずパスと設定の組み合わせを確認します。ステータスコードだけから原因を断定するのではなく、実際のルーティングとSpring Securityのルールを照合してください。

404 Not Found：依存関係が入っているか、endpointが利用可能か、HTTPへexposeされているか、base-path・context-path・管理ポートが一致しているかを確認します。アクセス不可にしたendpointは、アプリケーションコンテキストから取り除かれる場合があります。
401 Unauthorized：認証が必要な経路へ未認証でアクセスしていないか、認証方式・資格情報・プロキシによるAuthorizationヘッダーの扱いを確認します。
403 Forbidden：認証済みでも要求されたロールがない可能性があります。CSRF保護が有効な状態で、POSTなど更新系endpointへアクセスした場合にも拒否されることがあります。

読み取りのGET endpointと、ログレベル変更やshutdownなどの更新系endpointでは必要な権限・リスクが異なります。運用目的がhealth確認だけなら、他の管理endpointを追加公開する必要があるかを先に見直しましょう。原因の切り分け中も、調査のために全endpointを公開したままにするのは避けてください。

まとめ

Spring Boot Actuatorは、healthやinfoを通じてアプリケーションの運用状態を確認するための機能です。本番利用では、endpointの利用可否、HTTP/JMXへの公開、認証・認可を別々に設計し、必要最小限だけを公開します。healthの詳細やinfoの内容には運用情報が含まれ得るため、実際の応答を確認してください。

Kubernetesでは、再起動を判断するLivenessと、トラフィックを受けられるか判断するReadinessを混同しないことが大切です。外部依存の障害をLivenessへ直結させると、再起動の連鎖を招く可能性があります。採用しているSpring Bootのバージョン、Spring Security構成、ネットワーク・デプロイ環境に合わせて設定を検証しましょう。