Kubernetesの「あのコマンド、なんだっけ？」を卒業！初心者でもわかるkubectl逆引きリファレンス
やあ、みんな！クラウドインフラの最前線で奮闘している諸君、調子はどうかな？
君たちが今、Kubernetes (k8s) という強力なツールに触れ始めたばかりだとしたら、きっと「kubectl」というコマンドラインツールも毎日触っていることだろう。でも、正直、コマンドって覚えるのが大変だよね。「あれ、Podの状態を確認するコマンドって何だっけ？」「コンテナの中に入ってデバッグしたいんだけど、どうやるんだっけ？」なんて、毎日のように頭を抱えているんじゃないかな。
大丈夫、それは君だけじゃない。僕も同じ道を歩んできたし、今でも時々コマンドを検索することがあるさ。
でもね、kubectlの基本をしっかり押さえておけば、日々のKubernetes操作が劇的に楽になるんだ。まるで、暗闇の中に光が差し込むように、見通しが良くなる。そして、トラブルシューティングのスピードも格段に上がる。そうなれば、もっとクリエイティブな仕事に時間を割けるようになるはずだ。
この記事では、そんな君たちのために、実務で本当によく使うkubectlコマンドを「逆引き」形式で、しかも「なぜそうなるのか」という背景も踏まえながら、優しく丁寧に解説していく。まるで、隣で君のコードレビューをしている先輩エンジニアになったつもりで、じっくりと付き合っていくよ。
これをマスターすれば、君たちのKubernetesライフは、きっともっと楽しく、そして生産的になるはずさ。さあ、一緒にkubectlの深淵を覗いてみよう！
—
1. まずは基本！リソースの状態を「見る」コマンドたち
Kubernetesは、たくさんの「リソース」（Pod、Service、Deploymentなど）の集合体だ。まずは、これらのリソースが今どんな状態にあるのかを把握することが、全ての始まりだ。
1.1. 「今、何があるの？」を知りたいときは `kubectl get`
`kubectl get` は、指定したリソースのリストや、その概要を知りたいときに使う、まさに基本中の基本コマンドだ。
基本構文:
kubectl get <リソースの種類> [リソース名] -n
- `<リソースの種類>`: `pods`, `services`, `deployments`, `nodes`, `namespaces` など、確認したいリソースの種類を指定します。複数指定することも可能です (例: `pods,services`)。
- `[リソース名]`: 特定のリソースだけを確認したい場合に指定します。省略した場合は、その種類の全てのリソースが表示されます。
- `-n
`: 確認したいリソースが存在するNamespaceを指定します。省略すると、デフォルトのNamespace（通常は`default`）が対象になります。
よく使う例:
- 全てのPodを表示する:
kubectl get pods
出力例:
NAME READY STATUS RESTARTS AGE
my-app-pod-abcdef 1/1 Running 0 5m
another-pod-ghijkl 0/1 Pending 0 1m
`READY`列は「コンテナ数/準備完了したコンテナ数」を示します。`STATUS`列は、Podの状態（`Running`, `Pending`, `Error`など）を表します。
- 特定のDeploymentを表示する:
kubectl get deployment my-app-deployment
- 特定のNamespaceにある全てのServiceを表示する:
kubectl get services -n production
- 全てのNamespaceにある全てのNodeを表示する:
kubectl get nodes -A # -A は –all-namespaces の略
さらに詳しく知りたいときは `-o wide` オプション:
`kubectl get` は、オプションを付けることで、より詳細な情報を表示できる。特に `-o wide` は、IPアドレスやPodがどのNodeで動いているかなど、ネットワークやスケジューリングに関わる情報も表示してくれるので、重宝するぞ。
kubectl get pods -o wide
出力例（`IP`と`NODE`列が追加されている）:
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
my-app-pod-abcdef 1/1 Running 0 5m 10.244.1.5 worker-node1
1.2. 「具体的にどうなっているの？」を深掘りする `kubectl describe`
`kubectl get` で概要は掴めた。でも、「なぜかPodが起動しないんだ…」とか、「Serviceにアクセスできない…」といった、もう少し踏み込んだ原因を調査したいときは、`kubectl describe` の出番だ。
`kubectl describe` は、指定したリソースの詳細な情報、イベントログ、状態遷移の履歴などを表示してくれる。これを見れば、大抵の原因究明の糸口が見つかるはずだ。
基本構文:
kubectl describe <リソースの種類> <リソース名> -n
よく使う例:
- 特定のPodの詳細情報を表示する:
kubectl describe pod my-app-pod-abcdef
出力例（一部抜粋）:
Name: my-app-pod-abcdef
Namespace: default
Priority: 0
Node: worker-node1/192.168.1.100
Start Time: Tue, 26 Oct 2023 10:00:00 +0900
Labels: app=my-app
pod-template-hash=abcdef
Annotations:
Status: Running
IP: 10.244.1.5
IPs:
IP: 10.244.1.5
Containers:
my-app-container:
Container ID: containerd://…
Image: nginx:latest
Image ID: docker.io/library/nginx@sha256:…
Port: 80/TCP
Host Port: 0/TCP
State: Running
Started: Tue, 26 Oct 2023 10:00:05 +0900
Ready: True
Restart Count: 0
Liveness: http-get http://localhost:80/ delay=30s timeout=1s period=10s #success=1 #failure=3
Readiness: http-get http://localhost:80/ delay=10s timeout=1s period=10s #success=1 #failure=3
Environment:
Mounts:
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-xxxxx (ro)
… (省略) …
Events:
Type Reason Age From Message
—- —— —- —- ——-
Normal Scheduled 5m default-scheduler Successfully assigned default/my-app-pod-abcdef to worker-node1
Normal Pulling 5m kubelet Pulling image “nginx:latest”
Normal Pulled 5m kubelet Successfully pulled image “nginx:latest” in 2s
Normal Created 5m kubelet Created container my-app-container
Normal Started 5m kubelet Started container my-app-container
特に注目してほしいのは、出力の一番下にある `Events` セクションだ。ここに、Podの生成、スケジューリング、コンテナの作成・起動といった一連のイベントが時系列で記録されている。Podが `Pending` のまま進まない場合は、`Events` にスケジューリングの失敗理由などが書かれていることが多い。「`FailedScheduling`」といった理由が出てきたら、リソース不足やNodeの制約などが原因だと推測できる。
- Serviceの詳細を確認する:
kubectl describe service my-app-service
Serviceの場合、`Endpoints` の項目に、どのPodにトラフィックが転送されているかが表示される。ここにIPアドレスが表示されていない場合は、ServiceとPodが正しく紐づいていない可能性がある。
—
2. コンテナの中に入って、生の声を聞くコマンドたち
Podの状態が「Running」なのに、アプリケーションが期待通りに動いていない。そんな時は、コンテナの中に入って直接調査する必要がある。
2.1. 「元気にしてる？」ログを覗く `kubectl logs`
アプリケーションの動作状況やエラーメッセージは、ログに集約されている。`kubectl logs` は、コンテナの標準出力・標準エラー出力をリアルタイムで取得したり、過去のログを確認したりできるコマンドだ。
基本構文:
kubectl logs
- `
`: ログを取得したいPodの名前を指定します。 - `[-c <コンテナ名>]`: Pod内に複数のコンテナがある場合に、対象のコンテナを指定します。省略すると、Pod内の最初のコンテナが対象になります。
- `[-n
]`: 対象のNamespaceを指定します。
よく使うオプション:
- `-f` または `–follow`: リアルタイムでログを追跡（ストリーミング）します。`tail -f` のように使えるので、アプリケーションの起動時やエラー発生時の確認に非常に便利だ。
- `–previous`: 直前に終了したコンテナのログを表示します。Podがクラッシュして再起動した場合などに、その原因となったログを確認するのに役立つ。
- `–tail=<行数>`: 最新の指定した行数だけログを表示します。
よく使う例:
- Podの最新ログを表示する:
kubectl logs my-app-pod-abcdef
- Podのログをリアルタイムで追跡する:
kubectl logs -f my-app-pod-abcdef
「Ctrl+C」で追跡を終了できる。
- クラッシュしたPodの直前のログを表示する:
kubectl logs –previous my-app-pod-abcdef
- 複数のコンテナを持つPodで、特定のコンテナのログを表示する:
kubectl logs my-multi-container-pod -c sidecar-container
2.2. 「ちょっと失礼して…」コンテナにログインする `kubectl exec`
ログだけでは分からない、あるいは、ファイルシステムの中身を確認したり、コマンドを実行してデバッグしたりしたい場合は、`kubectl exec` を使ってコンテナ内に直接入り込もう。
基本構文:
kubectl exec -it
- `-i` (`–stdin`): 標準入力を開いたままにします。
- `-t` (`–tty`): 疑似TTY（ターミナル）を割り当てます。この2つを組み合わせることで、対話型のシェル（例: `bash`, `sh`）を実行できるようになる。
- `–`: これ以降を、コンテナ内で実行したいコマンドとして解釈させます。
よく使う例:
- Pod内のコンテナにログインし、対話型シェルを起動する (bashがある場合):
kubectl exec -it my-app-pod-abcdef — bash
これで、コンテナ内のシェルプロンプトが表示される。`exit` コマンドでシェルを閉じられる。
- Pod内のコンテナにログインし、対話型シェルを起動する (shしかない場合):
kubectl exec -it my-app-pod-abcdef — sh
- コンテナ内で特定のコマンドを実行し、その結果を表示する (例: ファイル一覧):
kubectl exec my-app-pod-abcdef — ls /app
この場合、`-it` は不要だ。
- 複数のコンテナを持つPodで、特定のコンテナにログインする:
kubectl exec -it my-multi-container-pod -c app-container — bash
—
3. アプリケーションを「更新」し、「元に戻す」コマンドたち
デプロイしたアプリケーションは、バグ修正や新機能追加のために更新する必要がある。Kubernetesでは、この更新プロセスを安全かつ柔軟に行うことができる。
3.1. 「新しいバージョンに更新！」 `kubectl apply` と `kubectl set image`
アプリケーションの更新は、主にYAMLマニフェストファイルを変更して適用する方法と、コンテナイメージを直接指定して更新する方法がある。
1. YAMLマニフェストファイルを更新して適用する (`kubectl apply`)
Deploymentなどのリソース定義を記述したYAMLファイルを変更し、`kubectl apply` コマンドで適用するのが最も一般的で推奨される方法だ。`apply` は、宣言的な設定を実現するためのコマンドで、現在のリソースの状態と、指定したYAMLファイルの状態を比較し、差分のみを適用してくれる。
基本構文:
kubectl apply -f <ファイル名.yaml> [-n
例:
`deployment.yaml` というファイルに、最新のコンテナイメージを指定したDeployment定義があるとしよう。
deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app-deployment
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app-container
image: my-registry/my-app:v1.1.0 # <-- ここを v1.0.0 から v1.1.0 に変更した ports:
- containerPort: 80
このファイルを適用するには:
kubectl apply -f deployment.yaml
Kubernetesは、`my-app-deployment` というDeploymentが存在していることを認識し、`template.spec.containers[0].image` が `my-registry/my-app:v1.0.0` から `my-registry/my-app:v1.1.0` に変更されたことを検知する。そして、Deploymentのローリングアップデート戦略に従って、Podを段階的に新しいイメージのPodに置き換えていく。
2. コンテナイメージを直接更新する (`kubectl set image`)
DeploymentやStatefulSetなどのPodテンプレートを持つリソースに対して、コンテナイメージだけを直接更新したい場合に便利なのが `kubectl set image` だ。
基本構文:
kubectl set image <リソースの種類>/<リソース名> <コンテナ名>=<新しいイメージ名> [-n
例:
`my-app-deployment` というDeploymentの、`my-app-container` というコンテナイメージを `my-registry/my-app:v1.1.0` に更新する。
kubectl set image deployment/my-app-deployment my-app-container=my-registry/my-app:v1.1.0
これも `kubectl apply` と同様に、ローリングアップデートを実行してくれる。
3.2. 「やっぱり前のバージョンに戻りたい！」ロールバック操作 (`kubectl rollout undo`)
更新を適用した結果、問題が発生したり、ユーザーからのフィードバックが悪かったりした場合、すぐに前のバージョンに戻せるのは非常に重要だ。`kubectl rollout undo` は、Deploymentなどのローリングアップデートの履歴を辿って、以前の状態にロールバックするためのコマンドだ。
基本構文:
kubectl rollout undo <リソースの種類>/<リソース名> [-n
よく使う例:
- 最新の1つ前のバージョンにロールバックする:
kubectl rollout undo deployment/my-app-deployment
このコマンドを実行すると、DeploymentのPodテンプレートが、一つ前のリビジョン（バージョン）の状態に戻される。Kubernetesは、再びローリングアップデートを実行し、Podを新しい（古い）イメージのPodに置き換えていく。
- 特定の履歴リビジョン番号にロールバックする:
まず、ロールバックできる履歴を確認する。
kubectl rollout history deployment/my-app-deployment
出力例:
REVISION SOURCE REVISION_ID TIME_STAMP
3
2
1
例えば、リビジョン `2` に戻したい場合は、以下のように指定する。
kubectl rollout undo deployment/my-app-deployment –to-revision=2
—
4. トラブル発生！「まず最初に」確認すべき診断コマンド一覧
本番環境でインシデントが発生した時、パニックにならず、迅速かつ冷静に原因を特定するためには、いくつかの「お決まり」の診断コマンドを知っておくことが不可欠だ。ここでは、「まず最初に」確認すべき、実戦的なコマンドをいくつか紹介しよう。
4.1. Podの「状態」と「イベント」を総ざらい `kubectl get pods` & `kubectl describe pod`
これは基本中の基本だが、トラブル発生時はまずここからだ。
- Podの状態確認:
# 問題が発生しているNamespaceのPodを全て確認
kubectl get pods -n <問題のNamespace>
`CrashLoopBackOff` や `Error` になっているPodはないか？ `Pending` のまま進んでいないPodはないか？ `READY` 列は期待通りか？
- Podの詳細とイベント確認:
# 問題のPodの詳細を掘り下げる
kubectl describe pod <問題のPod名> -n <問題のNamespace>
特に `Events` セクションに注目！スケジューリングの失敗、イメージのpullエラー、Liveness/Readiness Probeの失敗などが記録されていることが多い。
4.2. コンテナの「生の声」を聞く `kubectl logs`
Podが `Running` になっていても、アプリケーションがエラーを起こしている可能性は十分にある。
- 最新ログの確認:
kubectl logs <問題のPod名> -n <問題のNamespace>
エラーメッセージが出ていないか？
- リアルタイムログでの確認:
kubectl logs -f <問題のPod名> -n <問題のNamespace>
アプリケーションの動作をリアルタイムで追いながら、どこで問題が発生しているのかを特定する。
- クラッシュ原因の究明 (`–previous`):
kubectl logs –previous <問題のPod名> -n <問題のNamespace>
`CrashLoopBackOff` になっているPodの原因究明には必須。
4.3. Pod間の通信やServiceの疎通確認 `kubectl exec` & `kubectl port-forward`
Podは動いている、ログも異常なし。でも、他のPodからアクセスできない、あるいは外部からアクセスできない。そんな時は、ネットワーク周りの問題が疑われる。
- コンテナ内から疎通確認:
まずは、問題のPod、あるいは通信元となるPodのコンテナに入り、`ping` や `curl` コマンドで疎通確認を行う。
# 問題のPodのコンテナにログイン
kubectl exec -it <問題のPod名> -n <問題のNamespace> — bash
# コンテナ内でcurlを実行
curl http://<別のPodのIPアドレス>:<ポート番号>
curl http://
コンテナ内に `curl` や `ping` がない場合は、`busybox` などの軽量イメージでPodを一時的に作成して試す、という手もある。
- ローカルからPodにアクセスして確認 (`kubectl port-forward`):
ローカル開発環境から、Kubernetesクラスタ内のPodに一時的にアクセスしたい場合や、Podに直接デバッグ用のポートフォワーディングをしたい場合に便利だ。
# ローカルの8080ポートを、Podの80ポートに転送
kubectl port-forward pod/<問題のPod名> 8080:80 -n <問題のNamespace>
このコマンドを実行したターミナルを開いたままにしておけば、ローカルの `localhost:8080` 経由でPodの80ポートにアクセスできる。
curl http://localhost:8080
Serviceに対しても同様にポートフォワーディングできる。
kubectl port-forward service/
4.4. Nodeの状態確認 `kubectl get nodes` & `kubectl describe node`
Podが `Pending` のままだったり、Podが `Unknown` 状態になっていたりする場合、Node自体の問題が考えられる。
- Nodeの状態確認:
kubectl get nodes
kubectl get nodes -o wide # IPアドレスなども表示
`NotReady` になっているNodeはないか？
- Nodeの詳細とイベント確認:
kubectl describe node <問題のNode名>
`Conditions` や `Events` セクションに、Nodeの異常を示す情報（ディスク容量不足、メモリ不足、Kubeletの停止など）が記録されていることがある。
4.5. デプロイメントの履歴と状態確認 `kubectl rollout status` & `kubectl rollout history`
ローリングアップデートがうまくいっていない、あるいは、いつから問題が発生したのかを調べる際に役立つ。
- デプロイメントの現在の進行状況を確認:
kubectl rollout status deployment/
ローリングアップデートが完了したか、あるいはどこかで詰まっているかを確認できる。
- デプロイメントの履歴を確認:
kubectl rollout history deployment/
いつ、どのような変更が行われたかの履歴を確認できる。ロールバックの判断材料になる。
—
まとめ：kubectlマスターへの道は、実践の中にあり！
どうだったかな？ 今回は、Kubernetesを日々使う上で「これだけは押さえておきたい！」というkubectlの基本コマンドと、トラブルシューティングに役立つコマンドを、実例を交えながら解説してみた。
- `kubectl get`: リソースの「全体像」を把握する。
- `kubectl describe`: リソースの「詳細」と「イベント」を深掘りする。
- `kubectl logs`: コンテナの「生の声」を聞く。
- `kubectl exec`: コンテナの中に入り込んで「直接調査」する。
- `kubectl apply`, `kubectl set image`, `kubectl rollout undo`: アプリケーションの「更新」と「復旧」を安全に行う。
- `kubectl port-forward`, `kubectl rollout status`, `kubectl rollout history`: トラブルシューティングの「強力な武器」となる。
これらのコマンドは、単に覚えるだけでなく、実際に手を動かして、様々な状況で使ってみることが何よりも大切だ。まずは、手元の開発環境で、色々なリソースを作ったり消したり、Podを意図的に壊してみたりして、これらのコマンドがどう反応するかを試してみてほしい。
君たちがこれらのコマンドを使いこなせるようになれば、Kubernetesの運用が格段に楽になるだけでなく、日々の開発プロセスにおいても、より自信を持って、そして迅速に対応できるようになるはずだ。
さあ、君たちのKubernetesマスターへの道は、ここから始まる！ 応援しているよ！