はじめに
この記事はClaude Codeによって生成されています。
目的
閉域網のOpenShiftを、クラスタの外にあるZabbixサーバーから監視します。
- 公式のZabbix Helm chartで、ノードとクラスタの状態を監視する
- OpenShift標準のPrometheusをHTTP APIで参照し、OpenShift Virtualization(OCP-V)上のVMをVM 1台=Zabbixホスト1台で監視する
- OpenShiftとZabbixの間で決める設定値を、1つの構成としてまとめる
構築はAnsible Playbookで行いました。本記事は構成・設定値と、実際にハマった点のまとめです。
環境
| 項目 | 内容 |
|---|---|
| 監視対象 | Single Node OpenShift 4.19.34(閉域網) |
| 仮想化 | OpenShift Virtualization 4.19.37 |
| Zabbix | 7.0.32 LTS(Podmanで構築) |
| Helm chart |
zabbix-helm-chart 1.3.4(Zabbix公式) |
| Zabbixサーバーの置き場所 | ミラーレジストリのVM(RHEL 9.8)に同居 |
構成
監視の経路は2本です。
- ノード・クラスタの状態: クラスタ内のzabbix-proxyが値を集めて、Zabbixサーバーへ送る。サーバーからクラスタ内への接続は不要
- VMの状態: ZabbixサーバーがThanos Querier(Prometheusの問い合わせ口)にPromQLを投げる
1. Zabbixサーバー: Podman Quadletで構築
ミラーレジストリのVMにはdnfリポジトリがなかったので、Zabbix公式のコンテナをQuadlet(Podmanのコンテナをsystemdで管理する仕組み)で動かしました。PostgreSQL・server・web・agent2を1つのPodにまとめ、メモリは約330MBでした。
# /etc/containers/systemd/zabbix-server.container(抜粋)
[Container]
Image=docker.io/zabbix/zabbix-server-pgsql:alpine-7.0.32
Pod=zabbix.pod
Environment=DB_SERVER_HOST=127.0.0.1
Environment=ZBX_STARTHTTPPOLLERS=5
ハマり: Environment=の値に空白があると分割される
Environment=ZBX_HOSTNAME=Zabbix server # NG: "Zabbix" と "server" に分かれる
Environment="ZBX_HOSTNAME=Zabbix server" # OK
2. 閉域網へのミラー: oc-mirror v2
OCP-VのOperatorと、Helm chartが使うイメージをミラーしました(67イメージ、約36分)。
apiVersion: mirror.openshift.io/v2alpha1
kind: ImageSetConfiguration
mirror:
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.19
targetCatalog: redhat/redhat-operator-index-ocpv # 既存のカタログを上書きしない
packages:
- name: kubevirt-hyperconverged
channels: [{name: stable}]
additionalImages:
- name: docker.io/zabbix/zabbix-agent2:alpine-7.0.32
- name: docker.io/zabbix/zabbix-proxy-sqlite3:alpine-7.0.32
- name: registry.k8s.io/kube-state-metrics/kube-state-metrics:v2.9.2
- name: quay.io/containerdisks/fedora:44
Helm chartのイメージ名は書き換えず、oc-mirrorが作るITMS(イメージの読み替え設定)でミラーレジストリへ向けています。
ハマり: IDMS/ITMSの名前が毎回同じ
oc-mirror v2はIDMSをidms-operator-0のような固定名で作ります。同じ名前のリソースが既にあると、oc applyで上書きされて既存のミラー設定が消えます。適用前にmetadata.nameを変えてください。
3. Zabbix Helm chartをOpenShiftに入れる
helm repo add zabbix-chart-7.0 https://cdn.zabbix.com/zabbix/integrations/kubernetes-helm/7.0
helm upgrade -i zabbix zabbix-chart-7.0/zabbix-helm-chart --version 1.3.4 -n zabbix -f values.yaml
素のKubernetes向けのchartなので、OpenShiftでは3か所の調整が必要でした。
3.1 agent2: privileged SCCが必要
agent2はホストのネットワーク・プロセス・ファイルシステムを使うので、既定のSCC(restricted-v2)では起動しません。chartが作るServiceAccountにprivileged SCCを付与します。
oc adm policy add-scc-to-user privileged -z zabbix-agent -n zabbix
3.2 kube-state-metrics: UID固定がSCCに拒否される
.containers[0].runAsUser: Invalid value: 65534: must be in the ranges: [1000760000, 1000769999]
サブchartがUIDを65534に固定しているためです。親chartからrunAsUser: nullを指定してもサブchartの既定値は消えませんでした。securityContextごと出力しないようにすると、OpenShiftがUIDを割り当てます。
kube-state-metrics:
securityContext:
enabled: false
3.3 proxy: クラスタ内APIの証明書を検証できない
SSL certificate OpenSSL verify result: self-signed certificate in certificate chain
ZabbixのCAディレクトリにクラスタのCAを置いても直りませんでした。Kubernetes用テンプレートはJavaScript型のアイテムでAPIを叩いており、このディレクトリを見ないためです。
CAをシステムのCAバンドルとしてマウントすると解決しました。proxyがTLSで話す相手はクラスタ内のAPIだけなので、置き換えても困りません。
zabbixProxy:
extraVolumes:
- name: kube-root-ca
configMap: {name: kube-root-ca.crt}
extraVolumeMounts:
- name: kube-root-ca
mountPath: /etc/ssl/certs/ca-certificates.crt
subPath: ca.crt
readOnly: true
4. Zabbix側: Kubernetesの監視設定
proxyと、Kubernetes用テンプレートを使うホスト2台を登録します(設定値は7章にまとめています)。
ハマり: ノードのホストが作られない
「Kubernetes nodes by HTTP」のホストプロトタイプ(ノードごとのホストを自動で作る設定)は、既定で無効でした。エラーも出ないので気づきにくいです。有効にすると、すぐにノードのホストが作られました。
ハマり: openshift-state-metricsで証明書のホスト名が合わない
PodのIPで接続するため、証明書のホスト名と一致せず失敗します。このホストだけ{$HTTP.TLS.VERIFY}=peer(CAは検証、ホスト名は検証しない)にしました。
結果、SNO 1台で監視アイテムは約25,000件になりました。
5. OCP-Vの導入
ミラーしたカタログからOperatorを入れ、HyperConvergedを作ります。閉域網ではOSイメージを自動取得できないので、自動インポートは止めます。
apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
name: kubevirt-hyperconverged
namespace: openshift-cnv
spec:
enableCommonBootImageImport: false
テストVMはcontainerDisk(quay.io/containerdisks/fedora:44)で起動しました。
6. ZabbixからPrometheusでVMを監視する
6.1 接続先と認証
接続先はThanos QuerierのRouteです。読み取り専用のServiceAccountを作り、期限なしのトークンを発行しました(oc create tokenのトークンは期限切れで監視が止まるため)。
apiVersion: v1
kind: ServiceAccount
metadata: {name: zabbix-prometheus-reader, namespace: zabbix}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata: {name: zabbix-prometheus-reader}
roleRef: {apiGroup: rbac.authorization.k8s.io, kind: ClusterRole, name: cluster-monitoring-view}
subjects: [{kind: ServiceAccount, name: zabbix-prometheus-reader, namespace: zabbix}]
---
apiVersion: v1
kind: Secret
metadata:
name: zabbix-prometheus-reader-token
namespace: zabbix
annotations: {kubernetes.io/service-account.name: zabbix-prometheus-reader}
type: kubernetes.io/service-account-token
RouteのCAはopenshift-config-managed/default-ingress-certのca-bundle.crtから取り出し、ZabbixサーバーのCAディレクトリに置きます。こちらはHTTPエージェント型のアイテムなので、CAディレクトリが効きます。
CAディレクトリは**<subject hash>.0というファイル名**で証明書を探すので、openssl x509 -noout -subject_hashで求めた名前で置きます。公式コンテナは起動時にこのディレクトリを内部へコピーするため、配置後にzabbix-serverの再起動が必要です。
6.2 使えるURI
TQはhttps://thanos-querier-openshift-monitoring.apps.<cluster>.<domain>です。
| URI | 結果 | 内容 |
|---|---|---|
TQ/api/v1/query?query=<PromQL> |
200 | 現在の値。今回はこれを使う |
TQ/api/v1/query_range |
200 | 期間の値 |
TQ/api/v1/series |
200 | 系列のラベル一覧 |
TQ/api/v1/label/__name__/values |
200 | メトリクス名の一覧(約2,600件) |
TQ/api/v1/metadata |
200 | 説明。?metric=で絞ると空になる |
TQ/api/v1/rules、/alerts
|
200 | ルール・発火中のアラート |
/federate |
200 | テキスト形式。ただしPromQLの計算はできない |
Alertmanagerの/api/v2/alerts
|
403 |
cluster-monitoring-viewでは読めない |
CPU使用率のようにrate()で計算した値が欲しいので、/api/v1/queryを使いました。
6.3 VM 1台=Zabbixホスト1台にする
1つのホストに全VMのアイテムを並べても値は取れますが、障害表示・メンテナンス期間・権限をVM単位で扱えません。そこでVMごとにZabbixホストを自動で作ります。
ホスト「sno-airgap-ocpv-vms」(クラスタ全体 + VMの検出)
アイテム(クラスタ全体、1分ごと):
健全性 kubevirt_hco_system_health_status
VM数 sum(kubevirt_number_of_vms) or vector(0)
稼働中のVMI数 count(kubevirt_vmi_info{phase="running"}) or vector(0)
アイテム: kubevirt_vm_info を取得
└─ VMの検出ルール {#VM.NAME}=$.metric.name / {#VM.NS}=$.metric.namespace
└─ ホストプロトタイプ
ホスト名 sno-airgap_{#VM.NS}_{#VM.NAME}
表示名 VM {#VM.NS}/{#VM.NAME} (sno-airgap)
テンプレート「OCP-V VM by Prometheus」
テンプレート「OCP-V VM by Prometheus」
アイテム(1分ごと): そのVMのメトリクスを1回の問い合わせで取得
依存アイテム9件: 状態 / 状態グループ / CPU / メモリ使用量 / メモリ割り当て / ネットワーク受信・送信 / ディスク読み・書き
トリガー: 稼働していない(status<>"running")、データが5分来ない
VMの検出にはkubevirt_vm_infoを使います。VMを停止しても系列が消えずstatus="stopped"になるので、停止中のVMも検出から外れません。VMを削除すると、LLDの保持期間(今回は1日)が過ぎてからホストごと消えます。
kubevirt_vmi_*(稼働中のVMのメトリクス)を検出に使うと、停止したVMが検出から外れ、しばらくするとホストごと消えます。
Zabbixのホスト名には/が使えないので、<cluster>_<namespace>_<name>にしています。Namespaceを含めているので、別のNamespaceにある同じ名前のVMもぶつかりません。
6.4 問い合わせを「VM数×1回/分」にする
クラスタ用ホストの4本(検出1+クラスタ全体3)はVM台数によらず固定で、VMごとの分がVM数×1回/分です。
メトリクスごとに問い合わせると「VM数×メトリクス数」回になります。そこでlabel_replaceで各式にmラベルを付け、orで1本にまとめました。
label_replace(kubevirt_vm_info{namespace="{$VM.NS}",name="{$VM.NAME}"}, "m", "status", "", "")
or label_replace(sum by (namespace, name) (rate(kubevirt_vmi_cpu_usage_seconds_total{namespace="{$VM.NS}",name="{$VM.NAME}"}[5m])), "m", "cpu_cores", "", "")
or label_replace(kubevirt_vmi_memory_used_bytes{namespace="{$VM.NS}",name="{$VM.NAME}"}, "m", "memory_used", "", "")
or ...(ネットワーク・ディスクも同様)
1回の問い合わせで、そのVMの値が全部返ります。
m=status status=running 1
m=cpu_cores 0.0376
m=memory_used 270581760
...
依存アイテムは、JSONPathでmを指定して自分の行を取り出します。
$[?(@.metric.m == 'cpu_cores')].value[1].first()
$[?(@.metric.m == 'status')].metric.status.first()
kubevirt_vmi_*はVMを停止すると系列ごと消えます。値が取れずエラーになるので、前処理のエラー時の動作を「値を設定: 0」にしておきます。
6.5 Zabbixへの登録手順(GUI)
テンプレート「OCP-V VM by Prometheus」は、Data collection → Templates → ImportでYAMLを取り込みます。
自動登録(推奨)
- クラスタ用のホストを作る(インターフェースなし)。マクロに
{$PROM.URL}と{$PROM.TOKEN}(Secret text) - アイテムを作る
| 項目 | 値 |
|---|---|
| Type | HTTP agent |
| URL | {$PROM.URL}/api/v1/query |
| Query fields |
query = kubevirt_vm_info
|
| Headers |
Authorization = Bearer {$PROM.TOKEN}
|
| SSL verify peer / SSL verify host | オン(6.1で置いたCAで検証する) |
| 前処理 | JSONPath $.data.result
|
- 検出ルールを作る: Type=Dependent item、LLDマクロ
{#VM.NAME}=$.metric.name、{#VM.NS}=$.metric.namespace - ホストプロトタイプを作る: テンプレート「OCP-V VM by Prometheus」、マクロ
{$VM.NS}={#VM.NS}、{$VM.NAME}={#VM.NAME}、{$PROM.URL}・{$PROM.TOKEN}も
手順4でURLとトークンをもう一度設定するのは、検出で作られたホストに親ホストのマクロが引き継がれないためです。
個別登録
監視するVMを絞りたい場合は、VMごとにホストを手で作り(テンプレート「OCP-V VM by Prometheus」、インターフェースなし)、マクロ{$VM.NS}・{$VM.NAME}・{$PROM.URL}・{$PROM.TOKEN}を設定します。テンプレートにこの4つを空の値+説明つきで入れておくと、GUIで何を設定すればよいかがそのまま分かります。
6.6 動作確認: VM 2台で確認する
別のNamespace(vm-test2)に、1台目と同じ名前のfedora-testを追加しました。StorageClassがない環境なので、containerDiskで起動しています。
apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
name: fedora-test
namespace: vm-test2
spec:
runStrategy: Always
template:
spec:
domain:
cpu: {cores: 1}
memory: {guest: 512Mi} # 1台目は1Gi。理由は下のハマりを参照
devices:
disks:
- {name: rootdisk, disk: {bus: virtio}}
volumes:
- name: rootdisk
containerDisk: {image: quay.io/containerdisks/fedora:44}
2台目だけを止めて、検知を確認します。
oc -n vm-test2 patch vm fedora-test --type merge -p '{"spec":{"runStrategy":"Halted"}}'
| 時刻 | 事象 |
|---|---|
| 14:31 | 2台目(vm-test2/fedora-test)を作成 |
| 14:33 | 2台目のホストVM vm-test2/fedora-test (sno-airgap)が自動で作られ、値が入る |
| 14:33:37 | 2台目だけ停止 |
| 14:34:15 |
2台目のホストだけに障害「VM vm-test2/fedora-test が稼働していません」。1台目はrunningのまま |
2台にして分かったことは次のとおりです。
-
同じ名前のVMも別のホストになる。ホスト名にNamespaceを含めているため、
sno-airgap_vm-test_fedora-testとsno-airgap_vm-test2_fedora-testに分かれる - 値もVMごとに別々に取れる。メモリ割り当ては1台目1GiB、2台目512MiBと、それぞれ正しく入った
-
URIは1つのまま。検出用の
kubevirt_vm_infoの応答が2行になるだけ。問い合わせは「検出1本+クラスタ全体の値3本+VM台数分」で、2台なら6回/分(4+2) - クラスタ用ホストの「稼働中のVMI数」は、停止で2→1になった
ハマり: 2台目がInsufficient memoryで起動しない
2台目を1台目と同じ1GiBで作ると、スケジュールできませんでした。
0/1 nodes are available: 1 Insufficient memory
ノードのメモリ使用量は72%でしたが、**要求(requests)**が95%に達していました。VMはvirt-launcherのPodとして動き、ゲストメモリに加えてオーバーヘッド(約260MB)をrequestsで確保します。VMの台数は、使用量ではなくrequestsで見積もる必要があります。今回は2台目を512MiBにして起動しました。
CPUやネットワークのrate()の値は、停止後もしばらく小さな値が残ります(5分間のサンプルから計算するため)。停止の判定にはstatusを使うのが確実です。
7. 設定値まとめ(OpenShift⇔Zabbix)
ここまでの設定のうち、OpenShiftとZabbixの間で値を合わせる必要があるものをまとめます。
7.1 通信
| # | 送信元 | 宛先 | ポート | 用途 |
|---|---|---|---|---|
| ① | OpenShiftのノード(zabbix-proxy) | Zabbixサーバー | 10051/TCP | 監視データの送信(Active proxy) |
| ② | Zabbixサーバー | Thanos QuerierのRoute | 443/TCP | PromQLの問い合わせ |
| - | OpenShiftのノード | ミラーレジストリ | 8443/TCP | Zabbix関連イメージのpull(閉域網の場合) |
7.2 OpenShift側の設定値
| 項目 | 値 |
|---|---|
| Namespace | zabbix |
| Helm chart |
zabbix-helm-chart 1.3.4 |
proxyの接続先(ZBX_SERVER_HOST) |
ZabbixサーバーのIP(ポートは既定の10051) |
proxyの名前(ZBX_HOSTNAME) |
zabbix-proxy-sno-airgap |
| agent2のSCC | ServiceAccount zabbix-agentにprivileged |
| kube-state-metrics | securityContext.enabled: false |
| proxyのCA | ConfigMap kube-root-ca.crtをシステムCAバンドルとしてマウント |
| Kubernetes API用トークン | chartが作るSecret zabbix(ServiceAccount zabbix)の.data.token
|
| Prometheus用ServiceAccount |
zabbix-prometheus-reader(ClusterRole cluster-monitoring-view) |
| Prometheus用トークン | Secret zabbix-prometheus-reader-token(kubernetes.io/service-account-token型、期限なし) |
| RouteのCA |
openshift-config-managed/default-ingress-certのca-bundle.crt
|
7.3 Zabbix側の登録値
proxy
| 項目 | 値 |
|---|---|
| 名前 |
zabbix-proxy-sno-airgap(OpenShift側のZBX_HOSTNAMEと完全一致) |
| モード | Active |
ホスト
| ホスト | テンプレート | 監視経由 | 主なマクロ |
|---|---|---|---|
sno-airgap-k8s-nodes |
Kubernetes nodes by HTTP | proxy |
{$KUBE.API.URL}、{$KUBE.API.TOKEN}、{$KUBE.NODES.ENDPOINT.NAME}=zabbix-agent、{$HTTP.TLS.VERIFY}=full(既定値) |
sno-airgap-k8s-cluster |
Kubernetes cluster state by HTTP | proxy |
{$KUBE.API.URL}、{$KUBE.API.TOKEN}、{$KUBE.STATE.ENDPOINT.NAME}=zabbix-kube-state-metrics、{$HTTP.TLS.VERIFY}=peer
|
sno-airgap-ocpv-vms |
(VM検出用。6.5の手順で作成) | サーバー直接 |
{$PROM.URL}、{$PROM.TOKEN}
|
| VMごとのホスト(自動作成) | OCP-V VM by Prometheus | サーバー直接 |
{$VM.NS}、{$VM.NAME}、{$PROM.URL}、{$PROM.TOKEN}
|
マクロの値
| マクロ | 値 |
|---|---|
{$KUBE.API.URL} |
https://kubernetes.default.svc.cluster.local:443 |
{$KUBE.API.TOKEN} |
Kubernetes API用トークン(Secret text) |
{$PROM.URL} |
https://thanos-querier-openshift-monitoring.apps.<cluster>.<domain> |
{$PROM.TOKEN} |
Prometheus用トークン(Secret text) |
サーバーの設定
| 項目 | 値 |
|---|---|
| バージョン | 7.0系(proxyとメジャーバージョンを揃える) |
CAディレクトリ(SSLCALocation) |
RouteのCAを<subject hash>.0というファイル名で配置し、zabbix-serverを再起動 |
ZBX_STARTHTTPPOLLERS |
5(HTTPエージェント型アイテム用) |
7.4 運用で決めておくこと
- トークン: 期限なしだが自動更新もされない。再発行の手順は「Secretを作り直す → Zabbixのマクロを差し替える → 古いSecretを削除」
- CA: Routeの証明書を差し替えたら、ZabbixサーバーのCAも入れ替える
- バージョンアップ: OCP・OCP-V・chart・Zabbixを更新するときは、proxyとサーバーのバージョン差に注意
- アイテム数: SNO 1台で約25,000件。サーバーの性能見積もりや、LLDのフィルターでの絞り込みを検討する
- 計画停止: VMごとのホストなので、メンテナンス期間をVM単位で設定できる
- VMの台数: ノードのメモリはrequests(ゲストメモリ+約260MB/台)で見積もる。問い合わせはVM 1台あたり1回/分増える
8. 取れるメトリクス(抜粋)
テストVM 1台で、kubevirt_*は131件ありました。
| 分類 | 主なメトリクス |
|---|---|
| VMの状態 |
kubevirt_vm_info、kubevirt_vm_resource_requests
|
| VMIの情報 |
kubevirt_vmi_info(ゲストOS・ノード)、kubevirt_vmi_status_addresses(IP) |
| CPU |
kubevirt_vmi_cpu_*_seconds_total、kubevirt_vmi_vcpu_*
|
| メモリ | kubevirt_vmi_memory_*_bytes |
| ネットワーク | kubevirt_vmi_network_{receive,transmit}_*_total |
| ディスク | kubevirt_vmi_storage_* |
| ゲスト内FS | kubevirt_vmi_filesystem_{capacity,used}_bytes |
| 基盤の健全性 |
kubevirt_hco_system_health_status(0=健全、1=警告、2=重大)、kubevirt_virt_*_up
|
ゲストOSの情報とゲスト内FSは、VM内でqemu-guest-agentが動いている場合だけ取れます。
OCP-V関連のアラートルールも51件定義済みでした。Zabbixで閾値を作る代わりに、ALERTS{alertstate="firing", kubernetes_operator_part_of="kubevirt"}を取り込む手もあります。
ハマりポイントまとめ
| # | 事象 | 対応 |
|---|---|---|
| 1 | QuadletのEnvironment=の値が空白で分割される |
"..."で囲む |
| 2 | oc-mirrorのIDMS/ITMSが既存の同名リソースを上書きする | 適用前に名前を変える |
| 3 | agent2が起動しない | privileged SCCを付与 |
| 4 | kube-state-metricsのUID固定がSCCに拒否される | securityContext.enabled: false |
| 5 | proxyがクラスタのCAを使わない | システムCAバンドルとしてマウント |
| 6 | ノードのホストが作られない | ホストプロトタイプを有効化 |
| 7 | openshift-state-metricsの証明書のホスト名不一致 | {$HTTP.TLS.VERIFY}=peer |
| 8 | 検出で作られたホストに親のマクロが引き継がれない | ホストプロトタイプにも{$PROM.URL}・{$PROM.TOKEN}を設定 |
| 9 | VM停止中にVMI系のアイテムがエラーになる | エラー時に「値を設定: 0」 |
| 10 | 2台目のVMがInsufficient memoryで起動しない(使用量72%、requests 95%) |
VMのメモリをrequests基準で見積もる(今回は512MiBに縮小) |
まとめ
- 閉域網でも、イメージをミラーすれば公式Zabbix Helm chartで監視できる。OpenShiftではSCC・securityContext・CAの調整が必要
- VMは
kubevirt_vm_infoを元にした検出ルールで、VM 1台=Zabbixホスト1台を自動で作れる。停止中のVMも検出から外れない - メトリクスを
label_replace+orで1本のPromQLにまとめると、問い合わせはVM数×1回/分で済む - OpenShiftとZabbixの間で合わせる値は、proxy名・トークン・CA・URL。7章の表を設計書のたたき台にできる