【ITニュース解説】kubectl Troubleshooting & Daily Commands Cheat Sheet

ITの世界でシステム開発や運用に携わる際、コンテナ技術はもはや欠かせない存在となった。特に「Kubernetes（クバネティス）」は、多数のコンテナ化されたアプリケーションを効率的に管理し、安定稼働させるための強力なプラットフォームとして広く利用されている。しかし、このKubernetesを使いこなすには、専用の操作ツールが必要だ。それが「kubectl（キューブコントロール）」というコマンドラインツールである。今回の記事では、このkubectlを使ってKubernetes環境で起こる様々な問題に対応し、日々の運用をスムーズに行うための基本的なコマンドと実践的なトラブルシューティング方法を解説する。システムエンジニアを目指す上で、これらの知識は非常に役立つはずだ。

まず、Kubernetes環境でアプリケーションを動かす際の最小単位となるのが「Pod（ポッド）」である。Podは一つまたは複数のコンテナをカプセル化したもので、アプリケーションの実体がここで動く。kubectlを使えば、このPodをはじめとするKubernetesのリソースの状態を調べたり、操作したりできる。 例えば、kubectl get pods -o wide -n <名前空間>というコマンドは、指定した名前空間（Kubernetes内でリソースをグループ分けする論理的な区切り）にあるPodの基本的な情報を一覧で表示する。-o wideオプションを付けると、Podのステータス（STATUS）、再起動回数（RESTARTS）、どのノード（サーバー）で動いているか（NODE）、IPアドレスといった詳細な情報も確認できる。この情報は、Podが正常に動いているか、どこで問題が起きているかを大まかに把握するための第一歩となる。

次に、特定のPodについてもっと詳しく調べたい場合は、kubectl describe pod <pod名>コマンドが非常に有効だ。このコマンドは、Podの現在の状態（State）、過去の状態（Last State）、そしてそのPodに発生したイベント（Events）など、詳細な設定や実行状況、さらには過去の出来事まで教えてくれる。アプリケーションが起動しない、あるいは予期せぬ挙動をする場合、このdescribeコマンドの結果を確認することで、エラーの原因が設定ミスにあるのか、リソース不足にあるのか、あるいは他の要因によるものなのかといった手がかりを得られることが多い。

Kubernetesクラスター内で何らかの警告やエラーが発生していないかを広範囲にチェックしたいときは、kubectl events -n <名前空間> --types=Warningを使うと便利だ。これにより、指定した名前空間で発生した警告イベントのみを抽出して表示できる。これは、問題が顕在化する前に予兆を捉えたり、トラブルの原因究明の範囲を絞り込んだりする際に役立つ。

アプリケーションの具体的なエラーメッセージや動作状況を確認するには、ログが不可欠だ。kubectl logs <pod名> -c <コンテナ名> --previousコマンドは、指定したPod内のコンテナが以前クラッシュした場合のログを表示する。もしコンテナが何度も再起動を繰り返している場合、直前の起動で何が起きたのかを知る上でこのコマンドは非常に重要だ。また、kubectl logs -l app=web --prefix --since=15m -fのように使えば、特定のラベルを持つ複数のPodのログをリアルタイムで追跡できる。これは、アプリケーション全体にわたる問題を監視する際に非常に強力な機能だ。

さらに進んだデバッグが必要な場合、kubectl exec -it <pod名> -c <コンテナ名> -- shコマンドを使って、稼働中のコンテナ内部にシェルで入り込むことができる。これにより、コンテナ内で直接コマンドを実行し、ファイルシステムの状況を確認したり、ネットワーク設定を調べたりと、まるで通常のサーバーにログインしているかのように詳細な調査が可能になる。また、kubectl debug -it <pod名> --image=busybox:1.36 --target=<コンテナ名>というコマンドを使えば、一時的なデバッグ用のコンテナ（エフェメラルコンテナ）を起動し、既存のアプリケーションコンテナに影響を与えることなく、デバッグツールを使って問題を調査できる。これは本番環境でのデバッグにおいて非常に安全な方法だ。

リソースの使用状況を把握することも、安定稼働のためには重要である。kubectl top pod -n <名前空間> --sort-by=memoryコマンドを使えば、指定した名前空間内のPodのCPUやメモリの使用量を一覧で確認できる。これにより、リソースを過剰に消費しているPodや、ボトルネックになっている可能性のあるPodを特定できる。

アプリケーションのデプロイ（配置）状況を追跡するには、kubectl rollout status deploy/<デプロイ名>が有効だ。デプロイの進行状況や成功・失敗を確認でき、問題があればkubectl rollout undo deploy/<デプロイ名>で以前の安定したバージョンにロールバック（元に戻す）することも可能だ。これは、新しいバージョンのアプリケーションで不具合が見つかった際に、迅速にサービスを復旧させるための非常に重要な機能である。

開発やテストの段階で、Kubernetesクラスター内のサービスにローカルPCからアクセスしたい場合は、kubectl port-forward svc/<サービス名> 8080:80を使う。これにより、ローカルPCのポート8080からKubernetesクラスター内のサービスのポート80に通信を転送でき、あたかもローカルでサービスが動いているかのように扱える。

Kubernetesでは、誰がどのような操作をできるかを厳密に管理する「RBAC（Role-Based Access Control）」という仕組みがある。kubectl auth can-i <動詞> <リソース> --as=<ユーザー名>コマンドを使えば、特定のユーザーが特定のリソースに対してどのような操作（例えばgetやdelete）を許可されているかを確認できる。これは、アクセス権限の問題をトラブルシューティングする際に非常に役立つ。

設定ファイルを変更する前にその影響を確認したい場合は、kubectl diff -f <ファイル名.yaml>コマンドを使うことで、実際に変更を適用した場合に何が変わるかをプレビューできる。これにより、意図しない変更を防ぎ、安全に設定を進めることができる。また、特定のPodが準備完了状態（Ready）になるまで待機したい場合は、kubectl wait --for=condition=Ready pod -l app=web --timeout=120sのように使うことで、スクリプトなどで自動処理を行う際に役立つ。

ここからは、より実践的なトラブルシューティングのパターンを見ていこう。まず、Podが失敗している時の基本的な調査手順は「粗い情報から細かい情報へ」という流れが重要だ。 具体的には、

1. kubectl get pod $POD -n $NS -o wideでPodの基本的な状態（ステータス、再起動回数、ノード、IP）を確認する。
2. kubectl describe pod $POD -n $NSでPodの詳細な状態、コンディション、イベントを確認する。多くのクラッシュ原因は、ログを見る前にこのdescribeコマンドの結果から推測できることが多い。
3. kubectl events -n $NS --for pod/$PODで、そのPodに特化したイベントをチェックする。
4. kubectl logs $POD -n $NS --all-containers --previous --tail=200で、クラッシュしたコンテナの直前のログを確認する。--all-containersでPod内の全コンテナのログ、--previousで以前の実行時のログ、--tail=200で末尾から200行のみを表示する。
5. 最後にkubectl get pod $POD -n $NS -o yamlでPodの完全な設定と現在のステータスをYAML形式で確認する。これにより、期待通りの設定が反映されているか、あるいは意図しない設定がないかを確認できる。

次に、コンテナがなぜ停止したのかを詳しく調べる方法だ。コンテナが予期せず終了した場合、その理由と終了コードはlastState.terminatedという情報に格納されている。kubectl get pod $POD -n $NS -o jsonpath='{range .status.containerStatuses[*]}{.name}{"\t"}{.restartCount}{"\t"}{.lastState.terminated.reason}{"\t"}{.lastState.terminated.exitCode}{"\n"}{end}'のようなjsonpathクエリを使うと、各コンテナの終了理由と終了コードを効率的に抽出できる。 終了コードにはそれぞれ意味がある。例えば、終了コード「137」は、通常「SIGKILL」というシグナルによって強制終了されたことを意味し、これはメモリ不足（OOMKilled）が原因でOSによって強制的に停止させられた可能性が高い。終了コード「143」は「SIGTERM」というシグナルによるもので、これはアプリケーションが正常に終了処理を行ったことを示すことが多い。そして、終了コード「1」は、一般的にアプリケーション内部でエラーが発生したことを意味する。 また、コンテナが起動できずに「Waiting」状態になっている場合、その理由として「CrashLoopBackOff」（繰り返しクラッシュして再起動している）、「ImagePullBackOff」（コンテナイメージのダウンロードに失敗している）、「CreateContainerConfigError」（コンテナの設定に問題がある）などが考えられる。これらもkubectl get pod $POD -n $NS -o jsonpath='{.status.containerStatuses[*].state.waiting}'で確認できる。 さらに、クラスター全体で最も再起動回数の多いPodを探すには、kubectl get pods -A --sort-by='.status.containerStatuses[0].restartCount' | tail -15といったコマンドが有効だ。これにより、不安定なPodを特定し、優先的に調査できる。

このように、kubectlはKubernetes環境を管理し、アプリケーションの健全性を維持し、問題が発生した際に迅速に解決するための非常に多機能で強力なツールである。システムエンジニアとして、これらのコマンドを理解し、適切に使いこなす能力は、日々の業務における生産性と安定性を大きく向上させる。今回解説したコマンドやトラブルシューティングのパターンを参考に、ぜひkubectlのスキルを習得し、実際の運用で活用してほしい。