Apache BalancerPersist徹底解説：ロードバランサー設定の永続化と管理

2025-05-27

Apache HTTP Serverのmod_proxy_balancerモジュールは、複数のバックエンドサーバー（ワーカー）間でリクエストを負荷分散する機能を提供します。この負荷分散の設定は、通常、Apacheの設定ファイル（httpd.confなど）に記述されます。

しかし、Apacheには、Webブラウザからロードバランサーのメンバーの状態（例えば、特定のバックエンドサーバーをオフラインにする、ロードファクターを変更するなど）を動的に変更できるbalancer-managerという機能があります。

BalancerPersist ディレクティブの役割

BalancerPersist On
このディレクティブをOnに設定すると、balancer-managerで行われたロードバランサーの動的な変更が、Apacheの再起動後も維持されるようになります。Apacheは、これらの変更を内部的に保存し、再起動時にその状態を復元します。これにより、手動で設定ファイルを編集しなくても、動的な変更を永続化できます。
BalancerPersist Off (デフォルト)
これがデフォルトの動作です。balancer-managerを使ってロードバランサーの設定を動的に変更した場合、その変更はApacheが稼働している間は有効ですが、Apacheが再起動されると、設定ファイルに記述された元の状態に戻ってしまいます。つまり、動的に行った変更は永続化されません。

使用例

<Proxy balancer://mycluster>
    BalancerMember http://backend1.example.com:8080
    BalancerMember http://backend2.example.com:8080
    ProxySet lbmethod=byrequests
</Proxy>

ProxyPass /app balancer://mycluster/app
ProxyPassReverse /app balancer://mycluster/app

# 動的な変更を再起動後も維持する場合
BalancerPersist On

注意点

このディレクティブは、Apache HTTP Server 2.4.4以降で利用可能です。
通常、本番環境では、設定の変更はバージョン管理された設定ファイルを介して行うことが推奨されます。BalancerPersist Onは、開発環境や一時的な調整に便利ですが、永続的な設定変更は設定ファイルで行うべきです。
BalancerPersist Onを使用すると、balancer-managerからの変更が設定ファイルよりも優先されるため、設定の管理が複雑になる可能性があります。

BalancerPersist は、balancer-manager を介して行われたロードバランサーの動的な変更を、Apache の再起動後も永続化させるためのディレクティブです。そのため、この機能に関連する問題は、主に設定の意図と実際の動作の不一致、あるいは設定の競合から発生します。

BalancerPersist On に設定しても変更が永続化されない

考えられる原因

mod_proxy_balancer が有効になっていない
BalancerPersist は mod_proxy_balancer の機能であるため、このモジュールが有効になっていないと機能しません。
権限の問題
Apache が動的な状態を保存するファイルやディレクトリへの書き込み権限がない場合、永続化が失敗します。通常、Apache は内部的にこれらの情報を管理するため、直接ファイルシステム上のパスを指定することは少ないですが、内部的な保存メカニズムに問題がある可能性も考慮します。
設定ファイルの読み込み順序の問題
複数の設定ファイルに分散して設定している場合、BalancerPersist On が正しく読み込まれていない可能性があります。特に、Include ディレクティブを使って設定ファイルを読み込んでいる場合、意図しない順序で処理されることがあります。
Apache のバージョンが古い
BalancerPersist ディレクティブは、Apache HTTP Server 2.4.4 以降で導入されました。それ以前のバージョンではこのディレクティブは機能しません。

トラブルシューティング

SELinux/AppArmor の設定
Linux 環境の場合、SELinux や AppArmor などのセキュリティモジュールが Apache の書き込み操作をブロックしている可能性があります。ログに AVC (Access Vector Cache) 拒否のエントリがないか確認し、必要に応じてポリシーを調整します。
Apache のエラーログを確認する
error_log に BalancerPersist に関連するエラーメッセージが出力されていないかを確認します。権限の問題など、具体的なエラーの原因が示唆されている場合があります。
設定ファイルの整合性を確認する
- httpd -t -D DUMP_VHOSTS や httpd -t -D DUMP_RUN_SETTINGS コマンドを使用して、Apache が実際に読み込んでいる設定を確認します。
- BalancerPersist On が意図した場所で、かつ正しく記述されているかを確認します。例えば、<Proxy balancer://mycluster> ブロック内ではなく、グローバルな設定か、関連する <VirtualHost> 内に記述されているかを確認します。
mod_proxy_balancer が有効か確認する
httpd -M | grep proxy_balancer コマンドで proxy_balancer_module (shared) のように表示されるか確認します。表示されない場合は、Apache の設定で LoadModule proxy_balancer_module modules/mod_proxy_balancer.so がコメントアウトされていないか確認し、有効にします。
Apache のバージョンを確認する
httpd -v コマンドで Apache のバージョンを確認し、2.4.4 以降であることを確認します。

BalancerPersist On 使用時に、設定ファイルと動的な変更が競合する

考えられる原因

balancer-manager での意図しない変更
複数の管理者が balancer-manager を使用している場合、互いの変更が上書きし合ったり、意図しない状態になったりすることがあります。
設定ファイルでの変更
BalancerPersist On を有効にした状態で、設定ファイル (httpd.conf など) でロードバランサーのメンバー（ワーカー）の属性（例: loadfactor、status など）を変更し、その後 balancer-manager からも変更を行った場合、どちらの変更が優先されるかという問題が発生することがあります。通常は balancer-manager での動的な変更が永続化されて優先されますが、混乱を招く可能性があります。

トラブルシューティング

Apache の再起動時の挙動を理解する
BalancerPersist On の場合、Apache の再起動時に動的に変更された状態が復元されます。もし設定ファイルで変更を行いたい場合は、一度 BalancerPersist Off にして Apache を再起動し、設定ファイルの内容で初期化してから、再度 BalancerPersist On にするという手順も考えられます。しかし、これはダウンタイムを伴うため、慎重な計画が必要です。
balancer-manager のアクセス制限
balancer-manager へのアクセスを厳しく制限し、信頼できる管理者のみが操作できるようにします。
設定の管理ポリシーを明確にする
BalancerPersist On を使用する場合は、設定ファイルでの変更は極力避け、動的な変更は balancer-manager のみで行うという運用ポリシーを確立することが重要です。

ロードバランサーのメンバーの状態が予期せず変更される、またはリセットされる

考えられる原因

ファイルシステムの破損
永続化情報が保存されているファイルシステムに問題が発生した場合、データが失われる可能性があります。
Apache のクラッシュまたは強制終了
Apache が正常にシャットダウンされなかった場合、永続化された情報が破損したり、保存されなかったりする可能性があります。

トラブルシューティング

システムログの確認
システムレベルのログ（例: dmesg、journalctl）で、ファイルシステムエラーやディスク関連のエラーがないか確認します。
Apache の起動/停止は適切に行う
apachectl graceful または systemctl reload httpd (再読み込み) / systemctl restart httpd (再起動) を使用し、正常にサービスを管理します。

ログレベルの調整
トラブルシューティングの際には、LogLevel を info や debug に一時的に引き上げると、より詳細な情報がエラーログに出力され、問題の原因特定に役立つことがあります。
BalancerPersist On は慎重に使用する
このディレクティブは開発環境や一時的な調整には便利ですが、本番環境では設定の変更履歴を管理し、ロールバックを容易にするために、設定ファイルで明示的に管理することが推奨される場合が多いです。動的な変更が多すぎると、現在の設定が何であるかを把握しにくくなる可能性があります。

しかし、「関連するプログラミング」として考えられるのは、以下の2つの側面です。

Apache の設定ファイルでの BalancerPersist の記述例 (最も直接的な例)
balancer-manager を利用して動的にロードバランサーの状態を変更する例 (これによって BalancerPersist の効果を確認できる)
シェルスクリプトなどを用いた Apache サービスの制御と状態確認の例 (永続化の確認方法)

Apache の設定ファイルでの BalancerPersist の記述例

これは最も基本的で直接的な「プログラミング」例です。Apache の設定ファイル（例: httpd.conf や extra/httpd-proxy.conf など）に記述します。

# 必要なモジュールの読み込み（通常はデフォルトで有効）
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule slotmem_shm_module modules/mod_slotmem_shm.so # BalancerPersist に必要

# ロードバランサーの定義
<Proxy balancer://mycluster>
    # ロードバランサーのメンバー（ワーカー）
    BalancerMember http://192.168.1.100:8080 route=worker1 loadfactor=10
    BalancerMember http://192.168.1.101:8080 route=worker2 loadfactor=10 status=On

    # ロードバランシングメソッド（例: リクエスト数）
    ProxySet lbmethod=byrequests

    # ★ここが重要: BalancerPersist の設定
    # On にすると、balancer-manager での変更が Apache 再起動後も維持されます。
    # Off（デフォルト）にすると、再起動時に設定ファイルの状態に戻ります。
    BalancerPersist On
</Proxy>

# ロードバランサーへのリクエスト転送ルール
ProxyPass /app balancer://mycluster/app
ProxyPassReverse /app balancer://mycluster/app

# balancer-manager へのアクセス設定 (テストや管理用)
<Location /balancer-manager>
    SetHandler balancer-manager
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1 # ローカルホストからのみアクセス許可
    # Allow from 192.168.1.0/24 # 特定のネットワークからのアクセス許可
</Location>

解説

BalancerPersist On: この行が肝心です。これを On に設定することで、balancer-manager (後述) を使ってワーカーの status を Drain にしたり、loadfactor を変更したりした場合、Apache を再起動してもその変更が保持されます。
BalancerMember: ロードバランシングの対象となるバックエンドサーバー（ワーカー）を指定します。route や loadfactor、status などの属性を設定できます。
<Proxy balancer://mycluster>: ロードバランサーを mycluster という名前で定義しています。
LoadModule slotmem_shm_module: BalancerPersist が機能するために必要な共有メモリ管理モジュールです。Apache 2.4.4 以降で導入されました。

balancer-manager を利用して動的にロードバランサーの状態を変更する例

BalancerPersist の効果を実際に確認するためには、balancer-manager を使用してロードバランサーのワーカーの状態を変更してみるのが最もわかりやすい方法です。

手順

上記の設定を Apache に適用し、Apache を再起動します。
Web ブラウザで http://your-apache-server-ip/balancer-manager にアクセスします。（上記の設定例では 127.0.0.1 からのみアクセス可能です）
ロードバランサーの一覧が表示されますので、mycluster をクリックします。
ワーカーの一覧が表示されます。例えば、http://192.168.1.100:8080 の行で、Status を On から Drain や Off に変更し、「Update」ボタンをクリックします。
ステータスが変更されたことを確認します。
ここが BalancerPersist の検証ポイントです。 Apache を再起動します。
```
sudo systemctl restart httpd # または apachectl restart
```
再度ブラウザで http://your-apache-server-ip/balancer-manager にアクセスし、mycluster を確認します。

期待される動作

BalancerPersist Off の場合 (または設定なしの場合)
Apache 再起動後、ワーカーのステータスは設定ファイルに記述されたデフォルトの On に戻っているはずです。
BalancerPersist On の場合
先ほど balancer-manager で変更したワーカーのステータス（例: Drain）が、Apache 再起動後も維持されているはずです。

BalancerPersist 自体をシェルスクリプトで「プログラミング」するわけではありませんが、その効果を自動的に確認したり、管理したりするための補助的なスクリプトは考えられます。

例1: ワーカーの状態を `curl` と `grep` で確認するスクリプト

これは、balancer-manager のHTML出力を解析してワーカーの状態を簡易的に確認する例です。本番運用で自動化する際は、より堅牢な方法（例: ApacheのJMX/MBeansなど）を検討すべきですが、簡単な確認には使えます。

#!/bin/bash

APACHE_MANAGER_URL="http://127.0.0.1/balancer-manager"
BALANCER_NAME="mycluster"
TARGET_WORKER="http://192.168.1.100:8080" # 確認したいワーカーのURL

echo "--- ロードバランサーの状態確認 ---"

# balancer-manager のページを取得し、対象ワーカーの状態を抽出
STATUS=$(curl -s "$APACHE_MANAGER_URL" | grep "$TARGET_WORKER" | sed -n 's/.*<td[^>]*>\s*\(On\|Off\|Drain\)\s*<\/td>.*/\1/p' | head -n 1)

if [ -z "$STATUS" ]; then
    echo "エラー: ワーカーの状態を取得できませんでした。URLやワーカー名を確認してください。"
else
    echo "現在のワーカー $TARGET_WORKER の状態: $STATUS"
fi

echo "--- Apache サービスを再起動 ---"
sudo systemctl restart httpd
sleep 5 # Apache が完全に起動するまで待つ

echo "--- 再起動後の状態確認 ---"
STATUS_AFTER_RESTART=$(curl -s "$APACHE_MANAGER_URL" | grep "$TARGET_WORKER" | sed -n 's/.*<td[^>]*>\s*\(On\|Off\|Drain\)\s*<\/td>.*/\1/p' | head -n 1)

if [ -z "$STATUS_AFTER_RESTART" ]; then
    echo "エラー: 再起動後のワーカーの状態を取得できませんでした。"
else
    echo "再起動後のワーカー $TARGET_WORKER の状態: $STATUS_AFTER_RESTART"
fi

echo "--- BalancerPersist の効果検証 ---"
if [ "$STATUS" = "$STATUS_AFTER_RESTART" ]; then
    echo " ワーカーの状態が再起動後も維持されました。BalancerPersist が機能しています。"
else
    echo " ワーカーの状態が再起動後にリセットされました。BalancerPersist が機能していないか、Off になっています。"
fi

解説

Apache を再起動する前と後でワーカーの状態を比較し、BalancerPersist が意図通りに機能しているかを確認します。
このスクリプトは、Apache の balancer-manager ページから HTML を取得し、grep と sed を組み合わせて特定のワーカーの状態 (On, Off, Drain) を抽出します。

例2: 自動化されたロードバランサーメンバーの管理（より高度な概念）

実運用では、balancer-manager を手動で操作する代わりに、スクリプトやツールから HTTP リクエストを送信してロードバランサーのメンバーの状態をプログラムで変更する場合があります。例えば、デプロイツールが新しいバージョンをデプロイする際に、古いサーバーを Drain 状態にし、トラフィックがなくなった後に Off にするといったシナリオです。

これは balancer-manager が受け付ける POST リクエストをシミュレートすることになります。具体的なリクエスト形式は Apache のバージョンや balancer-manager の実装によって多少異なる場合がありますが、基本的な考え方は以下の通りです。

# 例: 特定のワーカーを Drain 状態にする curl コマンド（概念的な例であり、実際のフォームパラメータは確認が必要）
# balancer-manager のフォームを分析し、正しいPOSTパラメータを取得する必要があります。
# 通常は balancer-manager のページソースを見て、formのactionとinputの名前を確認します。

# POSTリクエストの例 (概念的なもの、実際のフォームフィールド名に合わせて調整が必要)
# cluster_name=mycluster
# worker_url=http://192.168.1.100:8080
# status=drain
# action=UpdateWorker

curl -X POST \
  -d "b=$BALANCER_NAME&w=$TARGET_WORKER_ROUTE&lf=10&rr=0&wd=0&wr=0&sc=0&st=2&o=UpdateWorker" \
  "http://127.0.0.1/balancer-manager"
# ↑ 上記の -d オプションの値は、実際のbalancer-managerのHTMLフォームのinputタグのname属性とvalue属性から組み立てる必要があります。
# status=2 は Drain に相当する内部値であることが多いです。
# w=TARGET_WORKER_ROUTE の部分は、BalancerMember の route=worker1 のような値になることが多いです。

このようなスクリプトを使って状態を変更した場合、BalancerPersist On であれば、その変更が永続化されることを確認できます。
-d "...": フォームのデータを指定します。この文字列は、balancer-manager の HTML フォームを解析して、ワーカーの状態を変更するための正しいフィールド名と値を特定する必要があります。通常は balancer-manager のページソースを確認するか、ブラウザの開発者ツールでフォーム送信時のリクエストペイロードを確認します。
curl -X POST: POST リクエストを送信します。

直接 BalancerPersist の機能を置き換える API はありませんが、ロードバランサーの管理において同様の目的（動的な状態変更）を達成するための代替手段として、以下のような方法が考えられます。

設定ファイルを直接編集し、Apache をリロード/再起動する

これは最も基本的で、多くの本番環境で推奨される方法です。

デメリット
- 変更のたびに Apache のリロード/再起動が必要。
- リロード/再起動時のごくわずかなダウンタイムやセッションロストのリスク（グレースフルリスタートである程度緩和）。
- 頻繁な変更には向かない。
メリット
- 設定変更の履歴が明確（バージョン管理システムとの連携が容易）。
- 確実な状態同期（設定ファイルが真の状態源となる）。
- シンプルで分かりやすい。
プログラミングとの関連
- CI/CD パイプライン
  デプロイメントツールやCI/CDパイプライン（Jenkins, GitLab CI/CD, GitHub Actions など）から、設定ファイルを自動生成・更新し、その後 Apache サービスを再起動するスクリプトを呼び出す形で実装されます。
- 構成管理ツール
  Ansible, Chef, Puppet などの構成管理ツールを使って、Apache の設定ファイルをバージョン管理し、変更を自動的に適用するのに適しています。
- シェルスクリプト
  特定のワーカーをメンテナンスモードにする場合など、単純な操作であればシェルスクリプトで設定ファイルを sed や awk などで編集し、Apache を再起動する処理を記述できます。
説明
ロードバランサーのメンバーの状態（例: status=On を status=Drain に変更）や、負荷分散の重み (loadfactor) などを Apache の設定ファイル（httpd.conf や conf.d/proxy.conf など）で直接編集します。変更後、Apache をグレースフルリスタート (apachectl graceful または systemctl reload httpd) するか、フルリスタート (apachectl restart または systemctl restart httpd) します。

外部のロードバランサーソリューションを利用する

Apache HTTP Server の mod_proxy_balancer はシンプルなロードバランサー機能を提供しますが、より高度な機能や大規模な運用には、専用のロードバランサー製品やソフトウェアが用いられます。

デメリット
- 導入コストや運用コストが増大する。
- 構成が複雑になる。
- 別途、ロードバランサーの学習と管理が必要。
メリット
- 高度な負荷分散アルゴリズム、ヘルスチェック、SSL オフロード、WAF (Web Application Firewall) など、より豊富な機能。
- Apache の負荷分散設定とは完全に分離されるため、Apache 自体の再起動を伴わない動的なバックエンド管理が可能。
- 大規模なシステムやマイクロサービスアーキテクチャに適している。
プログラミングとの関連
- これらのロードバランサーは、多くの場合 REST API を提供しており、プログラミング言語（Python, Java, Go など）から API を呼び出して、バックエンドサーバーの追加/削除、有効/無効の切り替え、重みの変更などを動的に行えます。
- CI/CD ツールや運用スクリプトからこれらの API を呼び出すことで、デプロイメントプロセスにロードバランサーの状態変更を組み込むことが可能です。
例
- ハードウェアロードバランサー
  F5 BIG-IP, Citrix ADC (NetScaler) など。
- ソフトウェアロードバランサー
  Nginx Plus (有償版), HAProxy, Envoy Proxy など。
- クラウドロードバランサー
  AWS ELB/ALB, Google Cloud Load Balancing, Azure Load Balancer など。

サービスディスカバリと連携させる

マイクロサービスアーキテクチャやクラウドネイティブ環境では、サービスディスカバリツールと連携してバックエンドを管理することが一般的です。

デメリット
- システム全体の複雑性が増す。
- サービスディスカバリツール自体の導入と運用が必要。
メリット
- 自動化されたサービス登録/解除による運用負荷の軽減。
- 高可用性とスケーラビリティの向上。
- 複雑な環境でのバックエンド管理を簡素化。
プログラミングとの関連
- アプリケーションが起動時にサービスディスカバリに自身を登録し、終了時や異常時に登録を解除（またはヘルスチェックが失敗）します。
- ロードバランサーやAPI Gateway（例: Envoy）は、これらのサービスディスカバリから動的にバックエンドのリストを取得し、変更を自動的に反映します。
- プログラミング言語からサービスディスカバリの API を呼び出して、サービスの登録/登録解除、状態変更などを行うことができます。
例
- Consul (HashiCorp)
  サービスレジストリとヘルスチェック機能を提供。
- ZooKeeper, etcd
  分散KVSとしてサービス情報や設定を管理。
- Kubernetes Service/Ingress
  Kubernetes 上のサービスは自動的にロードバランシングとサービスディスカバリを提供。

BalancerPersist は Apache 内で完結する手軽な永続化方法ですが、より堅牢で自動化されたシステムを構築する場合、設定ファイルの直接編集＋構成管理ツール や 外部のロードバランサーの API 利用、あるいは サービスディスカバリとの連携 が代替手段として挙げられます。

Apache HTTP Serverでリバースプロキシを構築：mod_proxyとの設定例

mod_proxy は Apache HTTP Server のモジュールで、HTTP リクエストを別のサーバー（バックエンドサーバー）に転送する、つまり「プロキシ」として機能するための機能を提供します。このプロキシ機能の設定において、<Proxy> ディレクティブはプロキシの対象となる URL パスを定義し、そのパスに対するプロキシの挙動を制御するために使用されます。

Apacheの「Expect: 100-continue」問題を解決！Proxy100Continue設定とトラブルシューティング

Proxy100Continueは、Apache HTTP Serverのmod_proxyモジュールで使用されるディレクティブです。これは、クライアントが送信する「Expect: 100-continue」HTTPヘッダーの扱いを制御します。

Apache mod_proxy: ProxyAddHeaders徹底解説 - リバースプロキシでのヘッダ転送

ProxyAddHeaders は Apache HTTP Server の mod_proxy モジュールが提供するディレクティブの一つです。このディレクティブは、リバースプロキシとして動作している Apache がバックエンドのサーバ（オリジンサーバ）にリクエストを転送する際に、特定のリクエストヘッダを自動的に追加するかどうかを制御します。

もう悩まない！ProxyBadHeaderエラー回避のためのバックエンドプログラミング

具体的には、以下のような状況でこのエラーが発生することがあります。バックエンドサーバーの応答の問題: バックエンドサーバー自体が、予期せぬ、または破損したHTTPレスポンスを返している場合。これは、バックエンドアプリケーションのバグ、あるいはネットワークの問題によるデータの破損が原因であることもあります。

Apache ProxyBlockとProxyAllow：効果的なアクセス制限の設定

「mod_proxy: ProxyBlock」は、Apache HTTP Serverのmod_proxyモジュールが提供するディレクティブの一つです。このディレクティブは、Apacheがプロキシとして動作する際に、特定のホストやドメインへのアクセスを拒否（ブロック）するために使用されます。

mod_proxy: ProxyDomain

ProxyDomainは、Apache HTTP Serverのmod_proxyモジュールでかつて使用されていたディレクティブです。現在では非推奨 (deprecated) となっており、ほとんどの場合、使用すべきではありません。このディレクティブの目的は、プロキシされたリクエストのHTTPヘッダーにあるHostヘッダーを、指定されたドメイン名に書き換えることでした。具体的には、Apacheがリバースプロキシとして機能し、バックエンドのアプリケーションサーバーにリクエストを転送する際に、リクエストが本来意図していたドメイン名をバックエンドサーバーに伝えるために使われました。

Apache BalancerPersist徹底解説：ロードバランサー設定の永続化と管理

BalancerPersist On に設定しても変更が永続化されない

BalancerPersist On 使用時に、設定ファイルと動的な変更が競合する

ロードバランサーのメンバーの状態が予期せず変更される、またはリセットされる

Apache の設定ファイルでの BalancerPersist の記述例

balancer-manager を利用して動的にロードバランサーの状態を変更する例

例1: ワーカーの状態を curl と grep で確認するスクリプト

例2: 自動化されたロードバランサーメンバーの管理（より高度な概念）

設定ファイルを直接編集し、Apache をリロード/再起動する

外部のロードバランサーソリューションを利用する

サービスディスカバリと連携させる

例1: ワーカーの状態を `curl` と `grep` で確認するスクリプト