本記事は OpenShift Advent Calendar 2025 の 12/15 の記事です。
OpenShift のトラブルシューティングにおいて、ログや各種設定を一括で取得する must-gather というツールがよく使われます。障害発生時にまず must-gather を取得しておくと、あとから原因調査ができます。しかし、must-gather はYAMLファイルを中心とする大量のテキストの集合体であり、目的の情報をgrep等で探すのは簡単ではありません。
そんなときに役立つのが omc (OpenShift Must-Gather Client) です。omc を使うと、ローカルにある must-gather ディレクトリに対し、あたかも稼働中のクラスターに oc コマンドを実行するかのような感覚で調査を行えます (例: omc get pod, omc get node)。
omc の基本的な使い方は以下の記事が参考になります。
OpenShiftのmust-gather - 赤帽エンジニアブログ
本記事では、ocコマンドの模倣にとどまらない、omc独自の便利なコマンドを紹介します。
検証環境
以下のバージョンで動作確認を行いました。
- omcのバージョン: 3.12.2
- ターゲットクラスターのバージョン: 4.20.6
事前にmust-gatherディレクトリに対しomc useを実行しておく必要があります。
$ omc version
omc version: v3.12.2
hash: b7eee6a
https://github.com/gmeghnag/omc
$ omc get clusterversion
NAME VERSION AVAILABLE PROGRESSING SINCE STATUS
version 4.20.6 True False 7h10m Cluster version is 4.20.6
$ omc use ./must-gather.local.8374101325171721878
etcdの健全性を確認する: omc etcd
コントロールプレーンの重要なコンポーネントであるetcdの状態を把握できます。statusコマンドでは、各ノードのエンドポイント一覧、DBのサイズや使用中のサイズ、リーダー選出状況などを確認できます。
$ omc etcd status
+--------------------------+------------------+---------+----------------+----------+-----------+------------+-----------+------------+--------------------+--------+
| ENDPOINT | ID | VERSION | DB SIZE/IN USE | NOT USED | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS |
+--------------------------+------------------+---------+----------------+----------+-----------+------------+-----------+------------+--------------------+--------+
| https://10.0.26.8:2379 | 6f55a06fe0b7183c | 3.5.24 | 80 MB/41 MB | 49% | false | false | 11 | 309080 | 309080 | |
| https://10.0.44.168:2379 | 7ab75f2f10b8713b | 3.5.24 | 79 MB/41 MB | 48% | false | false | 11 | 309080 | 309080 | |
| https://10.0.40.177:2379 | 8b3d866d32438e1a | 3.5.24 | 80 MB/41 MB | 49% | true | false | 11 | 309080 | 309080 | |
+--------------------------+------------------+---------+----------------+----------+-----------+------------+-----------+------------+--------------------+--------+
healthコマンドでは、各エンドポイントの応答速度を確認でき、パフォーマンス問題の切り分けに役立ちます。
$ omc etcd health
+--------------------------+--------+------------+-------+
| ENDPOINT | HEALTH | TOOK | ERROR |
+--------------------------+--------+------------+-------+
| https://10.0.26.8:2379 | true | 7.995356ms | |
| https://10.0.40.177:2379 | true | 8.65011ms | |
| https://10.0.44.168:2379 | true | 8.425166ms | |
+--------------------------+--------+------------+-------+
アラート状況を確認する: omc prom rule
must-gather取得時点で発報中(firing)、あるいは待機中(pending)だった Prometheus のアラートを表示できます。Webコンソールからアラートを確認することなく、クラスターが当時どのような異常を検知していたかを確認できます。
$ omc prom rule -s firing,pending -o wide
GROUP RULE SEVERITY STATE AGE ALERTS ACTIVE SINCE
general.rules Watchdog none firing 24s 1 15 Dec 25 04:55 UTC
openshift-kubernetes.rules AlertmanagerReceiversNotConfigured warning firing 20s 1 15 Dec 25 00:13 UTC
OVNネットワーク情報を確認する: omc ovn
Open Virtual Network (OVN) 関連の情報は複雑で把握が難しいですが、omc ovnコマンドは物理ネットワーク(アンダーレイ)や論理ネットワーク(オーバーレイ)の情報を整理して表示してくれます。
物理ネットワーク情報: hostnetinfo
各ノードの物理ネットワーク(アンダーレイ)設定を表示できます。ホストのIPアドレスや、OVNが利用するプライマリインターフェースのアドレス、ゲートウェイのアドレスが確認できます。
$ omc ovn hostnetinfo
HOST/NODE ROLE HOST IP-ADDRESSES PRIMARY IF-ADDRESS HOST GATEWAY-IP
ip-10-0-26-8.ap-southeast-1.compute.internal control-plane,master 10.0.26.8/18 10.0.26.8/18 10.0.0.1
ip-10-0-26-95.ap-southeast-1.compute.internal worker 10.0.26.95/18 10.0.26.95/18 10.0.0.1
ip-10-0-33-25.ap-southeast-1.compute.internal worker 10.0.33.25/18 10.0.33.25/18 10.0.0.1
ip-10-0-40-177.ap-southeast-1.compute.internal control-plane,master 10.0.40.177/18 10.0.40.177/18 10.0.0.1
ip-10-0-44-168.ap-southeast-1.compute.internal control-plane,master 10.0.44.168/18 10.0.44.168/18 10.0.0.1
論理ネットワーク情報: subnets
OVN の論理ネットワーク(オーバーレイネットワーク)の情報を表示できます。各ノードに割り当てられた Pod 用のサブネット(NODE SUBNET)や、ノード間通信でのルーティングに使われるTransit SwitchのIPアドレス(NODE TRANSIT-SWITCH-IP)がわかります。
$ omc ovn subnets
HOST/NODE ROLE NODE SUBNET NODE TRANSIT-SWITCH-IP
ip-10-0-26-8.ap-southeast-1.compute.internal control-plane,master 10.128.0.0/23 100.88.0.2/16
ip-10-0-26-95.ap-southeast-1.compute.internal worker 10.128.2.0/23 100.88.0.6/16
ip-10-0-33-25.ap-southeast-1.compute.internal worker 10.131.0.0/23 100.88.0.5/16
ip-10-0-40-177.ap-southeast-1.compute.internal control-plane,master 10.129.0.0/23 100.88.0.3/16
ip-10-0-44-168.ap-southeast-1.compute.internal control-plane,master 10.130.0.0/23 100.88.0.4/16
証明書の有効期限を確認する: omc certs inspect
クラスター内の ConfigMap、Secret、CSR に含まれる証明書の詳細を一覧表示します。証明書の有効期限切れ(NOTAFTER)は、障害の一般的な原因の一つです。証明書の有効期限を一括で確認でき、原因調査に役立ちます。
$ omc certs inspect
NAME KIND AGE CERTTYPE SUBJECT NOTBEFORE NOTAFTER
kube-root-ca.crt ConfigMap 24h ca-bundle CN=kube-apiserver-lb-signer,OU=openshift 2025-12-14 06:22:38 +0000 UTC 2035-12-12 06:22:38 +0000 UTC
kube-root-ca.crt ConfigMap 24h ca-bundle CN=kube-apiserver-localhost-signer,OU=openshift 2025-12-14 06:22:37 +0000 UTC 2035-12-12 06:22:37 +0000 UTC
kube-root-ca.crt ConfigMap 24h ca-bundle CN=kube-apiserver-service-network-signer,OU=openshift 2025-12-14 06:22:37 +0000 UTC 2035-12-12 06:22:37 +0000 UTC
kube-root-ca.crt ConfigMap 24h ca-bundle CN=openshift-kube-apiserver-operator_localhost-recovery-serving-signer@1765694719 2025-12-14 06:45:18 +0000 UTC 2035-12-12 06:45:19 +0000 UTC
kube-root-ca.crt ConfigMap 24h ca-bundle CN=*.apps.cluster-qvx6z.qvx6z.sandbox3510.opentlc.com 2025-12-14 06:46:35 +0000 UTC 2027-12-14 06:46:36 +0000 UTC
kube-root-ca.crt ConfigMap 24h ca-bundle CN=ingress-operator@1765694792 2025-12-14 06:46:33 +0000 UTC 2027-12-14 06:46:34 +0000 UTC
openshift-service-ca.crt ConfigMap 24h ca-bundle CN=openshift-service-serving-signer@1765694718 2025-12-14 06:45:17 +0000 UTC 2028-02-12 06:45:18 +0000 UTC
コンテナイメージのビルド情報やソースコードを確認する: omc source
特定のPod/コンテナに関して、ビルド情報の詳細を知りたいときにomc source manifestコマンドが使えます。対象のコンテナイメージのベースOSや、リポジトリとコミットID、インストール済みパッケージなどがわかります。skopeo inspect --config コマンドで確認できる情報に相当します。
注意: コンテナレジストリから情報を取得するため、事前に~/.omc/pull-secret.jsonとしてプルシークレットを配置しておく必要があります。
※出力が非常に長いため、一部を省略しています。
$ omc source manifest ovnkube-control-plane-5f899dffd9-2c4cg -n openshift-ovn-kubernetes -c ovnkube-cluster-manager | jq
{
"architecture": "amd64",
"config": {
"Entrypoint": [
"/bin/sh",
"-c",
"/root/ovnkube.sh"
],
"Env": [
[...]
"BUILD_RELEASE=202511252120.p2.gecb7aac.assembly.stream.el9",
"BUILD_VERSION=v4.20.0",
[...]
"SOURCE_GIT_COMMIT=ecb7aac7dfd79120937d8a51806c6a8ea633b07a",
"SOURCE_GIT_TAG=v0.3.11-9949-gecb7aac7d",
"SOURCE_GIT_URL=https://github.com/openshift/ovn-kubernetes",
[...]
],
[...]
{
"created": "2025-11-25T21:47:16.329635302Z",
"created_by": "|4 ovnver=25.03 ovnver_okd=25.03 ovsver=3.5 ovsver_okd=3.5 /bin/sh -c . /cachi2/cachi2.env && INSTALL_PKGS=\"iptables nftables\" && source /etc/os-release && [ \"${ID}\" == \"centos\" ] && ovsver=$ovsver_okd && ovnver=$ovnver_okd; \tdnf --setopt=retr
ies=2 --setopt=timeout=2 install -y --nodocs $INSTALL_PKGS && \tdnf --setopt=retries=2 --setopt=timeout=2 install -y --nodocs \"openvswitch$ovsver\" \"python3-openvswitch$ovsver\" && \tdnf --setopt=retries=2 --setopt=timeout=2 install -y --nodocs \"ovn$ovnver\" \"ovn$ovnver-central\
" \"ovn$ovnver-host\" && \tdnf clean all && rm -rf /var/cache/* && \tsed 's/%/\"/g' <<<\"%openvswitch$ovsver-devel% %openvswitch$ovsver-ipsec% %ovn$ovnver-vtep%\" > /more-pkgs",
"empty_layer": true
},
[...]
{
"created": "2025-11-25T22:04:59.883895942Z",
"created_by": "/bin/sh -c . /cachi2/cachi2.env && INSTALL_PKGS=\" \topenssl firewalld-filesystem \tlibpcap iproute iproute-tc strace \ttcpdump iputils \tlibreswan \tethtool conntrack-tools \topenshift-clients \t\" && \tdnf --setopt=retries=2 --setopt=timeout=2 install -y --nodocs $INSTALL_PKGS && \teval \"dnf --setopt=retries=2 --setopt=timeout=2 install -y --nodocs $(cat /more-pkgs)\" && \tdnf clean all && rm -rf /var/cache/*",
"empty_layer": true
},
さらに強力なのが、omc source code コマンドです。ログに出力されているファイル名および行番号を-fオプションで指定すると、該当バージョンのGitHub URLを生成します。
例えば以下のログがあったとします。
$ omc logs ovnkube-control-plane-5f899dffd9-2c4cg -n openshift-ovn-kubernetes -c ovnkube-cluster-manager
[...]
2025-12-15T00:12:33.516671249Z I1215 00:12:33.515074 1 leaderelection.go:266] failed to acquire lease openshift-ovn-kubernetes/ovn-kubernetes-master
[...]
このログ中のファイル名と行番号(leaderelection.go:266)を指定して実行すると、ピンポイントでコードの場所を特定できます。
$ omc source code ovnkube-control-plane-5f899dffd9-2c4cg -n openshift-ovn-kubernetes -c ovnkube-cluster-manager -f leaderelection.go:266
{
"matches": [
"https://github.com/openshift/ovn-kubernetes/blob/ecb7aac7dfd79120937d8a51806c6a8ea633b07a/go-controller/vendor/k8s.io/client-go/tools/leaderelection/leaderelection.go#L266"
]
}
これにより、ログ出力箇所周辺のロジックをすぐに確認でき、原因調査に役立ちます。