HashiCorp設定
概要
このセクションでは、HashiCorp Vault KV Secrets Engine - Version 2 からシークレットを取得するための Zabbix の設定方法について説明します。
Vault は、公式の HashiCorp documentation に記載されているとおりにデプロイおよび設定されている必要があります。
Zabbix での TLS の設定については、Storage of secrets を参照してください。
データベース認証情報の取得
データベース認証情報を含むシークレットを正常に取得するには、次の両方を設定する必要があります。
- Zabbix サーバー/プロキシ
- Zabbix Webインターフェース
サーバー/プロキシ
Zabbix server または proxy を設定するには、
設定ファイルで次の設定パラメータを指定します。
Vault- 使用する vault プロバイダー;VaultToken- vault 認証トークン（詳細は Zabbix server/proxy の設定ファイルを参照）;VaultAppRoleIDと併用できません;VaultAppRoleIDおよびVaultAppSecretID- vault 認証のロール ID とシークレット ID（詳細は Zabbix server/proxy の設定ファイルを参照）;VaultTokenと併用できません;VaultURL- vault サーバーの HTTP[S] URL;VaultDBPath- データベース認証情報を含む vault シークレットへのパス（このオプションは DBUser と DBPassword が指定されていない場合にのみ使用できます）; Zabbix server または proxy は、キー "password" と "username" により認証情報を取得します;VaultPrefix- vault に応じた、vault パスまたはクエリのカスタムプレフィックス; 指定されていない場合は、最適なデフォルトが使用されます。
Vault、VaultToken（または VaultAppRoleID/VaultAppSecretID）、VaultURL、および VaultPrefix の設定パラメータは、Zabbix server がシークレット vault マクロを処理する際の vault 認証にも使用されます（また、設定済み の場合は Zabbix proxy でも使用されます）。Zabbix server および proxy は、VaultDBPath から DB 認証情報を含む vault シークレットマクロを開きません。
異なる proxy ごとに異なるトークンを使用することを強く推奨します。
Zabbix server と Zabbix proxy は、起動時に zabbix_server.conf および zabbix_proxy.conf から vault 関連の設定パラメータを読み込みます。
さらに、Zabbix server と Zabbix proxy は起動時に VAULT_TOKEN 環境変数を一度だけ読み取り、その後は fork されたスクリプトから利用できないように unset します。VaultToken と VAULT_TOKEN の両方に値が含まれている場合はエラーになります。
例
zabbix_server.confで、以下のパラメータを指定します。
VaultToken を使用する場合:
Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/または、VaultAppRoleID を使用する場合:
Vault=HashiCorp
VaultAppRoleID=6f1567f1-538d-7d70-e8e4-5d3e59471b2e
VaultAppSecretID=89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/- 以下の CLI コマンドを実行して、vault に必要な secret を作成します。
# まだ有効になっていない場合は "secret/" マウントポイントを有効化します。なお、"kv-v2" を使用する必要があります。
vault secrets enable -path=secret/ kv-v2
# マウントポイント "secret/" とパス "zabbix/database" の下に、username と password のキーを持つ新しい secret を追加します。
vault kv put -mount=secret zabbix/database username=zabbix password=<password>
# secret が正常に追加されたことを確認します。
vault kv get secret/zabbix/database
# 最後に Curl でテストします。なお、"data" はマウントポイントの後ろに手動で追加し、"/v1" はマウントポイントの前に追加する必要があります。--capath パラメータも参照してください。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database- その結果、Zabbix サーバーはデータベース認証用に以下の認証情報を取得します。
- ユーザー名: zabbix
- パスワード: <password>
Webインターフェース
Zabbix Webインターフェースは、Webインターフェースの インストール 時、または Webインターフェース設定ファイル (zabbix.conf.php) を更新することで、データベースの認証情報を vault から取得するように設定できます。
前回の Webインターフェースのインストール以降に vault の認証情報が変更された場合は、Webインターフェースのインストールを再実行するか、zabbix.conf.php を更新してください。あわせて 既存の設定の更新 も参照してください。
Webインターフェースのインストール 中は、Configure DB Connection ステップで接続パラメータを指定する必要があります。
トークン認証を使用した設定例:
AppRole 認証を使用した設定例:
| Parameter | Mandatory | Default value | Description |
|---|---|---|---|
| Store credentials in | no | HashiCorp Vault を選択します。 | |
| Vault API endpoint | yes | https://localhost:8200 | vault に接続するための URL を scheme://host:port 形式で指定します。 |
| Vault prefix | no | /v1/secret/data/ | vault パスまたはクエリ用のカスタムプレフィックスを指定します。指定しない場合はデフォルトが使用されます。 例: /v1/secret/data/zabbix/ |
| Vault secret path | yes | データベースの認証情報を "password" および "username" キーで取得するための secret へのパスです。 例: database |
|
| Vault authentication type | no | vault の認証タイプを選択します: Token - トークン認証を使用します; AppRole - AppRole 認証方式を使用します。 |
|
| Vault authentication token | yes | secret path への読み取り専用アクセス用の認証トークンを指定します。 トークンおよび vault ポリシーの作成方法については、HashiCorp documentation を参照してください。 このフィールドは、vault 認証タイプとして Token が選択されている場合にのみ使用できます。 |
|
| Vault authentication role ID | yes | AppRole の role ID を指定します。 AppRole については、HashiCorp documentation を参照してください。 このフィールドは、vault 認証タイプとして AppRole が選択されている場合にのみ使用できます。 |
|
| Vault authentication secret ID | yes | AppRole に対して発行された secret ID を指定します。 AppRole については、HashiCorp documentation を参照してください。 このフィールドは、vault 認証タイプとして AppRole が選択されている場合にのみ使用できます。 |
ユーザーマクロ値の取得
Vault secret ユーザーマクロ値を保存するために HashiCorp Vault を使用するには、次の条件を満たしていることを確認してください。
- Zabbix サーバー/プロキシが HashiCorp Vault と連携するように 設定 されている。
- Administration > General > Other の Vault provider パラメータが "HashiCorp Vault"（デフォルト）に設定されている。
Zabbix サーバー（および 設定 されている場合の Zabbix プロキシ）は、vault から Vault secret マクロ値へアクセスする必要があります。 Zabbix Webインターフェースにはそのようなアクセスは必要ありません。
マクロ値には参照パスを path:key の形式で含める必要があります。たとえば、macros:password です。
Zabbix サーバー/プロキシの設定時に指定した認証トークン（VaultToken パラメータ）は、このパスに対する読み取り専用アクセス権を提供している必要があります。
Zabbix によるマクロ値の処理の詳細については、Vault secret macros を参照してください。
パス構文
スラッシュ（"/"）とコロン（":"）の記号は予約されています。
スラッシュは、マウントポイントとパスを区切るためにのみ使用できます（例: secret/zabbix。この場合、マウントポイントは "secret"、パスは "zabbix" です）。Vaultマクロの場合、コロンはパス/クエリとキーを区切るためにのみ使用できます。
スラッシュとコロンの記号は、スラッシュで区切られる名前のマウントポイントを作成する必要がある場合（例: foo/bar/zabbix。この場合、マウントポイントは "foo/bar"、パスは "zabbix" であり、"foo%2Fbar/zabbix" としてエンコードできます）、またはマウントポイント名やパスにコロンを含める必要がある場合に、URLエンコードできます。
例
- Zabbix で、タイプが "Vault secret" で値が
macros:passwordのユーザーマクロ {$PASSWORD} を追加します。
- 次の CLI コマンドを実行して、vault に必要な secret を作成します。
# "secret/" マウントポイントがまだ有効でない場合は有効化します。なお、"kv-v2" を使用する必要があります。
vault secrets enable -path=secret/ kv-v2
# マウントポイント "secret/" とパス "zabbix/macros" の下に、キー "password" を持つ新しい secret を追加します。
vault kv put -mount=secret zabbix/macros password=<password>
# secret が正常に追加されたことを確認します。
vault kv get secret/zabbix/macros
# 最後に Curl でテストします。なお、"data" はマウントポイントの後ろに手動で追加し、"/v1" はマウントポイントの前に追加する必要があります。また、--capath パラメータも参照してください。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros- その結果、Zabbix はマクロ {$PASSWORD} を次の値に解決します: <password>
既存の設定の更新
HashiCorp Vault からシークレットを取得するための既存の設定を更新するには、次の手順を実行します。
-
Database credentials セクションで説明されているとおり、Zabbix サーバーまたはプロキシの設定ファイルのパラメータを更新します。
-
Frontend セクションで説明されているとおり、Zabbix Webインターフェースを再設定して必要なパラメータを指定し、DB 接続設定を更新します。
Zabbix Webインターフェースを再設定するには、ブラウザで Webインターフェースのセットアップ URL を開きます。
- Apache の場合: http://<server_ip_or_name>/zabbix/setup.php
- Nginx の場合: http://<server_ip_or_name>/setup.php
または、これらのパラメータは Webインターフェース設定ファイル (zabbix.conf.php) で設定できます。
Vault トークンを使用する場合:
$DB['VAULT'] = 'HashiCorp';
$DB['VAULT_URL'] = 'https://localhost:8200';
$DB['VAULT_DB_PATH'] = 'database';
$DB['VAULT_TOKEN'] = 'hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg';
$DB['VAULT_PREFIX'] = '/v1/secret/data/zabbix/';または、Vault AppRole メソッドを使用する場合:
$DB['VAULT'] = 'HashiCorp';
$DB['VAULT_URL'] = 'https://localhost:8200';
$DB['VAULT_DB_PATH'] = 'database';
$DB['VAULT_APP_ROLE_ID'] = '6f1567f1-538d-7d70-e8e4-5d3e59471b2e';
$DB['VAULT_APP_SECRET_ID'] = '89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1';
$DB['VAULT_PREFIX'] = '/v1/secret/data/zabbix/';- 必要に応じて、User macro values セクションで説明されているとおり、ユーザーマクロを設定します。
CyberArk Vault からシークレットを取得するための既存の設定を更新するには、CyberArk configuration を参照してください。
トラブルシューティング
- Zabbix サーバー/プロキシのログファイルで:
237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"考えられる原因: HashiCorp Vault が（再）起動されましたが、まだ unseal されていません（デフォルト設定では必要です。Auto Unseal が設定されている場合は不要です）。
- Zabbix サーバー/プロキシのログファイルで:
235545:20260729:125617.944 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"または
235545:20260729:125718.537 Vault token renew failed: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"考えられる原因: VaultAppSecretID が HashiCorp vault で期限切れになったか、使用回数の上限に達しています。