[IBMCloud] "kubectl debug"を使ったWorker Nodeの操作方法（ROKS以外の環境向け）

目的

RedHat OpenShift on IBM Cloud（ROKS）では"oc debug node/"コマンドを使って簡単にワーカーノードへアクセスできますが、IBM Cloud Kubernetes Service (IKS)などのROKS以外の環境では同等の操作ができません。
そこで、本記事では"kubectl debug"を活用し、ワーカーノードのホスト環境に入る方法を紹介する。

手順

対象のワーカーノードのIPまたは名前を確認

まず対象のワーカーノードのIPまたは名前を確認

コマンド: kubectl get nodes -o wide

% kubectl get nodes -o wide
NAME            STATUS   ROLES    AGE   VERSION        INTERNAL-IP     EXTERNAL-IP     OS-IMAGE             KERNEL-VERSION     CONTAINER-RUNTIME
10.244.128.27   Ready    <none>   60d   v1.30.13+IKS   10.244.128.27   10.244.128.27   Ubuntu 24.04.2 LTS   6.8.0-60-generic   containerd://1.7.27
10.244.64.34    Ready    <none>   14d   v1.30.14+IKS   10.244.64.34    10.244.64.34    Ubuntu 24.04.2 LTS   6.8.0-64-generic   containerd://1.7.27

イメージの確認

ワーカーノードに"kubectl debug"で入る際に指定する"--image="には、IBM Cloud Container Registry (ICR) に保存したコンテナイメージを利用する
以下の手順でイメージの一覧を確認可能

コマンド: ibmcloud cr image-list

% ibmcloud cr image-list
イメージをリストしています...

リポジトリー                                            タグ     ダイジェスト   名前空間                作成日         サイズ   セキュリティー状況
jp.icr.io/khoshina-cr/busybox-cr                        latest   0052b9b95d91   khoshina-cr             1 year ago     9.3 MB   -
jp.icr.io/khoshina-cr/fluentd                           latest   155648f47130   khoshina-cr             8 months ago   14 MB    -
jp.icr.io/khoshina-cr/nginx                             latest   9a09179391eb   khoshina-cr             2 years ago    70 MB    -

OK

次の手順で、コンテナイメージの指定は"jp.icr.io/khoshina-cr/busybox-cr"とする

debug Pod を起動

以下のコマンドを実行して、ワーカーノードに一時的にPodを作成し、/hostをchrootする

コマンド: kubectl debug node/ -it --image= -- chroot /host bash

% kubectl debug node/10.244.128.27 -it --image=jp.icr.io/khoshina-cr/busybox-cr -- chroot /host bash

--profile=legacy is deprecated and will be removed in the future. It is recommended to explicitly specify a profile, for example "--profile=general".
Creating debugging pod node-debugger-10.244.128.27-9wkd6 with container debugger on node 10.244.128.27.
Warning: metadata.name: this is used in the Pod's hostname, which can result in surprising behavior; a DNS label is recommended: [must not contain dots]
If you don't see a command prompt, try pressing enter.
root@kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698:/#

オプション

-it
bashやshをそのまま使えるように対話モードでPodに入る

--image=<image>
Debug Podとして利用するコンテナイメージを指定
例: --image=jp.icr.io/khoshina-cr/busybox-cr
BusyBoxやUbuntuなど軽量イメージを指定するのが良い

-- chroot /host bash
chroot /host : ノードのファイルシステムに切り替え
bash : その環境でシェルを起動

ワーカーノードに入ると、Pod内からノードのファイルシステムに直接アクセスできるため、通常のPodからはできない「ノード自体の調査・操作」が可能

OS確認

root@kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698:/# cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04.2 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.2 LTS (Noble Numbat)"
VERSION_CODENAME=noble
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=noble
LOGO=ubuntu-logo

ログ調査

root@kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698:/# ls /var/log/
README            apt           auth.log             btmp.1.gz              cloud-init.log  dist-upgrade  dmesg.1.gz  firstboot.flag  haproxy.log    kern.log        kubernetes  pods      syslog               wtmp
alternatives.log  at            bootstrap_base.flag  calico                 containerd.log  dmesg         dpkg.log    firstboot.log   ibmc-s3fs.log  kube-proxy.log  landscape   private   sysstat
apport.log        at-no-rotate  btmp                 cloud-init-output.log  containers      dmesg.0       dpkg.log.1  fluent-bit      journal        kubelet.log     lastlog     sudo.log  unattended-upgrades

root@kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698:/# journalctl -u kubelet | tail -n 10
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.093292    7368 kubelet_node_status.go:73] "Attempting to register node" node="10.244.128.27"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: E0619 02:29:45.094144    7368 kubelet_node_status.go:96] "Unable to register node with API server" err="Post \"https://172.20.0.1:2040/api/v1/nodes\": dial tcp 172.20.0.1:2040: connect: connection refused" node="10.244.128.27"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.220517    7368 util.go:30] "No sandbox for pod can be found. Need to start a new one" pod="kube-system/ibm-master-proxy-static-10.244.128.27"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: E0619 02:29:45.389636    7368 controller.go:145] "Failed to ensure lease exists, will retry" err="Get \"https://172.20.0.1:2040/apis/coordination.k8s.io/v1/namespaces/kube-node-lease/leases/10.244.128.27?timeout=10s\": dial tcp 172.20.0.1:2040: connect: connection refused" interval="800ms"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.494870    7368 kubelet_node_status.go:356] "Setting node annotation to enable volume controller attach/detach"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.497057    7368 kubelet_node_status.go:679] "Recording event message for node" node="10.244.128.27" event="NodeHasSufficientMemory"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.497120    7368 kubelet_node_status.go:679] "Recording event message for node" node="10.244.128.27" event="NodeHasNoDiskPressure"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.497132    7368 kubelet_node_status.go:679] "Recording event message for node" node="10.244.128.27" event="NodeHasSufficientPID"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: I0619 02:29:45.497196    7368 kubelet_node_status.go:73] "Attempting to register node" node="10.244.128.27"
Jun 19 02:29:45 kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698 kubelet.service[7368]: E0619 02:29:45.500871    7368 kubelet_node_status.go:96] "Unable to register node with API server" err="Post \"https://172.20.0.1:2040/api/v1/nodes\": dial tcp 172.20.0.1:2040: connect: connection refused" node="10.244.128.27"

終了する場合はexit

root@kube-co9j451t0t7uths6kb10-acspaasclus-lowspec-00002698:/# exit
exit

注意点

"kubectl debug"には"--rm"オプションがなく、終了後も"Debug Pod"が残る
不要な場合は"kubectl delete pod"で削除すること
作成されるPodの名前はランダムに付与される（例: node-debugger-xxxxx）。

ノード上のファイル編集は 即クラスタに影響する可能性があるため、確認目的での利用を推奨

pod名の確認し、削除する
コマンド: kubectl get pod

% ku get pod
NAME                                READY   STATUS      RESTARTS         AGE
node-debugger-10.244.128.27-gsq5j   0/1     Completed   0                5m57s

PODを削除する
コマンド: kubectl delete pod

% kubectl delete pod node-debugger-10.244.128.27-gsq5j
pod "node-debugger-10.244.128.27-gsq5j" deleted