Kubernetes 操作マニュアル

クラスタと namespace を固定し、Pod → EndpointSlice → Service → Ingress の関係から問題を絞る。状態、probe、疎通、業務の正しさは別々の根拠である。

やりたいこと	参照先
操作対象を確認	コンテキストとリソース
Pod が未準備・再起動	イベントとログ
稼働中なのに接続不可	通信と設定の対応
展開・復元・デバッグ	変更後の検証

context と namespace を固定

# context と集群・ユーザー・namespace を列挙する
kubectl config get-contexts

星印が現在の選択で、current-context はその名前だけを表示する。以降の your-context と default を確認済みの値に置き換える。各コマンドで明示し、前の変数に依存させない。

# namespace のワークロード・入口・ストレージ要求を確認する
kubectl --context your-context -n default get deploy,svc,ingress,pvc

各層の設定が存在するかを確認する。Pod の配置は次で調べる。NotFound は名前と範囲、Forbidden は権限を確認する。

# Pod 名・Ready・再起動数・IP・ノードを確認する
kubectl --context your-context -n default get pods -o wide

-o wide は IP・ノードなどを追加する。your-pod はこの一覧、コンテナ名 app は describe の Containers で確認する。

# namespace に属さないノードの状態を確認する
kubectl --context your-context get nodes -o wide

Ready でもすべてが配置可能とは限らない。requests・taint・affinity も確認する。

# この認証主体と範囲で Pod の読取権限を確認する
kubectl --context your-context -n default auth can-i get pods

yes / no は指定 verb/resource の認可だけを示し、API の稼働や他の操作の許可は保証しない。

例の context・namespace・リソース名を確認済みの対象に置き換える。Secret 一覧を見るために中身を出力する必要はない。--as による代理実行にも権限が必要。

Pod 状態は停止段階を示し原因は別

イベントとコンテナごとの状態を先に読む

# 配置イベント・プローブ・マウント・コンテナ状態を確認する
kubectl --context your-context -n default describe pod your-pod

State と Last State を区別し、終了コード・理由・時刻・回数を記録する。イベントは期限で消えるため、出力なしでも異常がなかったとは限らない。

# 現在のコンテナのログを直近 100 行読む
kubectl --context your-context -n default logs your-pod -c app --tail=100

-c は Pod 内のコンテナを選ぶ。複数なら明示する。-f で追跡し Ctrl-C で表示を終了する。

# 一つ前に終了したインスタンスのログを読む
kubectl --context your-context -n default logs your-pod -c app --previous --tail=100

再起動ループではこちらを読む。前のインスタンスやログが残っていない場合のエラーは、再起動の指示ではない。

# namespace のイベントを作成時刻順に確認する
kubectl --context your-context -n default get events --sort-by=.metadata.creationTimestamp

繰り返し発生した全件の時系列ではない。describe の最終時刻と回数を照合し、下表で確認先を選ぶ。

現象	確認
Pending / FailedScheduling	Events の requests、quota、affinity、taint、PVC。CPU の空きだけではない
ImagePullBackOff	ノードからのイメージ名・tag・registry 接続・認証・制限
CrashLoopBackOff	終了コード、lastState、前回ログ、startup/liveness probe。再試行待機状態を表す
Running / 0/1 Ready	readiness probe/gate と各コンテナ。Running は配信可能と同義ではない

設定項目と通信経路を対応させる

図を準備しています

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - name: http
      port: 80
      targetPort: 8080

同じ namespace の app: web の Pod を選び、8080 に接続する。アプリ自身の待ち受けが必要。containerPort はポートを開く設定ではなく、整数 targetPort に必須ではない。名前付き targetPort には対応する名前付きポートが必要。

selector・endpoint・port を順に照合する

上の YAML は Service オブジェクトの例で、Pod は作らない。service.yaml に保存する場合も公開手順で検証・適用する。

# Service selector に一致する Pod を探す
kubectl --context your-context -n default get pods -l app=web --show-labels

出力がなければポート変更の前にラベルと namespace を確認する。

# web の実際の接続先・ポート・Ready 条件を見る
kubectl --context your-context -n default get endpointslice -l kubernetes.io/service-name=web -o yaml

複数 slice の endpoints.addresses・conditions.ready・ports.port を確認する。存在しても NetworkPolicy・CNI・待ち受け先の確認は必要。

# Service の selector・port・targetPort を確認する
kubectl --context your-context -n default describe service web

Service への接続は port、アプリの待ち受けは targetPort。名前指定は Pod の同名ポートへ解決できる必要がある。

port-forward が通る経路だけを検証する

# kubectl クライアントでローカル診断ポートを開く
kubectl --context your-context -n default port-forward service/web 8080:80

この端末を維持し、別端末で curl http://127.0.0.1:8080/ を実行する。Ctrl-C で停止。選択された Pod が終了した場合は再接続が必要になる。

# 実際のクライアント Pod から Service 経路を試す
kubectl --context your-context -n default exec client-pod -c app -- curl -v http://web.default.svc.cluster.local/

curl がある許可対象の client-pod/app、実際の namespace と集群ドメインに置き換える。その主体で DNS と Service 経路を検証し、Ingress は外部から別途調べる。

EndpointSlice に宛先がなければ selector と namespace、未準備なら readiness を確認。port-forward は API 経由で Pod に接続し、ClusterIP・クラスタ DNS・Ingress は検証しない。クラスタ内クライアントから Service を検証し、Ingress の host/path/backend、コントローラー、外部入口を別に調べる。

展開とデバッグの作用範囲を確認

定義確認・API 検証・適用を分ける

# 確認した manifest と現在の API オブジェクトを比較する
kubectl --context your-context -n default diff -f manifest.yaml

manifest.yaml は今回の変更ファイル。内部の namespace と集群単位の対象も確認する。0 は差分なし、1 は差分あり。それ以外は先に解決する。

# 保存せずサーバーで検証・既定値適用を行う
kubectl --context your-context -n default apply --dry-run=server -f manifest.yaml

API・admission に接続する。失敗を直す。成功してもイメージ取得や動作は保証されない。

# 確認・検証したリソース宣言を書き込む
kubectl --context your-context -n default apply -f manifest.yaml

created/configured/unchanged の対象が意図通りか確認してから rollout を観察する。

# Deployment の更新完了またはタイムアウトを待つ
kubectl --context your-context -n default rollout status deployment/web --timeout=120s

タイムアウト時は新 ReplicaSet・イベント・ログを調べる。成功後も実リクエストを確認する。待機タイムアウトは自動 rollback ではない。

revision を確認してから戻す

# Deployment テンプレートの履歴を列挙する
kubectl --context your-context -n default rollout history deployment/web

rollout history deployment/web --revision=2 で候補を読む。2 は確認した revision に置き換える。

# 確認した revision のテンプレートへ戻す
kubectl --context your-context -n default rollout undo deployment/web --to-revision=2

rollout status・Pod・実リクエストを再確認する。DB、外部システム、独立 ConfigMap の内容は戻らない。

diff の終了値1は通常差分あり。server dry-run は API/admission にアクセスする。展開後も実リクエストを確認する。rollout undo はテンプレート履歴を戻すだけで DB は戻さない。restart は新 Pod を作るがイメージタグ自体は変えない。

ツールがあるコンテナでは exec を使う

# 対象コンテナで対話 shell を起動する
kubectl --context your-context -n default exec -it your-pod -c app -- sh

-- 以降が内部のコマンド。-i は入力、-t は端末を割り当てる。主プロセスを置き換えず、終了しても Pod は削除されない。

最小イメージでは一時診断コンテナを選ぶ

# 既存 Pod に一時診断コンテナを追加する
kubectl --context your-context -n default debug -it your-pod --image=busybox:1.37 --target=app

exec の代替であり権限・ポリシーが必要。承認済みイメージを使う。終了後も記録は Pod に残り、一時コンテナの項目だけを削除できない。

ファイルコピーの方向とコンテナを明示する

# 診断ファイルをクライアントへコピーする
kubectl --context your-context -n default cp your-pod:/tmp/report.txt ./report.txt -c app

必要な既存ファイルを上書きせず、内容・サイズを確認する。方向を逆にするとコンテナへ書く。通常、内部の tar が必要なので失敗時はエラーを読む。

kubectl debug は既存 Pod に一時コンテナを追加し、ポリシーとランタイムの制約がある。kubectl run は別 Pod を作りネットワーク条件が異なり得る。cp は通常コンテナ内 tar が必要。管理対象 Pod を削除する前にログとイベントを保存する。

Debug Services · Debug Pods · EndpointSlices