kubernetes-operations

Kubernetes 運用

トークン効率の高いスクリプトを使用して、デバッグ、リソース管理、クラスター運用を包括的に支援する kubectl ガイドです。

開始する前に

このスキルは、よくある5つのエラーを防ぎ、トークンを約70％節約します。

指標	スキルなし	スキルあり
Pod のデバッグ	約1200トークン	約400トークン
リソース一覧の取得	約800トークン	約200トークン
クラスターのヘルスチェック	約1500トークン	約300トークン

このスキルで防止できる既知の問題

1. 誤った namespace/context で kubectl コマンドを実行する
2. 冗長な出力によって、不要なデータがコンテキストを埋め尽くす
3. 重要なデバッグ手順（イベント、以前のログ）を見落とす
4. 平文の出力にシークレットを露出する
5. dry-run による確認なしに破壊的な操作を行う

クイックスタート

ステップ1：コンテキストを確認する

kubectl config current-context
kubectl config get-contexts

重要な理由： 誤ったクラスターでコマンドを実行すると、本番環境のインシデントにつながる可能性があります。

ステップ2：Pod をデバッグする

uv run scripts/debug_pod.py <pod-name> [-n namespace]

重要な理由： このスクリプトは describe、ログ、イベントを簡潔な概要にまとめ、約800トークンを節約します。

ステップ3：クラスターのヘルスを確認する

uv run scripts/cluster_health.py

重要な理由： 冗長な出力を使わずに、ノードの状態と異常な Pod をすばやく概観できます。

重要なルール

必ず行うこと

• 操作の前に、必ず kubectl config current-context を確認します
• 対象を明確にするため、必ず -n namespace を指定します
• 変更を適用する前に、必ず --dry-run=client -o yaml を使用します
• デバッグ時は必ずイベントを確認します：kubectl get events --sort-by='.lastTimestamp'
• Pod が CrashLoopBackOff の場合は、必ず --previous フラグを使用します

絶対に行わないこと

• 本番環境で、最初に --dry-run を指定せず kubectl delete を実行しないでください
• フィルタリングせずにシークレットを出力しないでください：kubectl get secret -o yaml は避けてください
• default namespace を前提にしないでください。必ず -n を指定します
• OOMKilled の Pod をデバッグする際に、リソース制限を無視しないでください
• ログにエラーが表示されなくても、describe を省略しないでください

よくある間違い

誤り：

kubectl logs my-pod

正しい方法：

kubectl logs my-pod -n my-namespace --tail=100 --timestamps

理由： default namespace が適切とは限りません。無制限のログはコンテキストを埋め尽くし、タイムスタンプはイベントとの関連付けに役立ちます。

既知の問題の予防

問題	根本原因	解決策
CrashLoopBackOff	起動時のアプリケーションのクラッシュ	kubectl logs --previous を確認し、終了コードを調べるために describe を実行します
ImagePullBackOff	レジストリ認証またはイメージタグ	イメージが存在することを確認し、プルシークレットを確認します
Pending 状態の Pod	スケジュール可能なノードがない	ノードのリソースと Pod のアフィニティ／許容設定を確認します
OOMKilled	メモリ制限の超過	kubectl top を使って、コンテナーの制限と実際の使用量を確認します
接続拒否	Service セレクターの不一致	Pod のラベルが Service セレクターと一致することを確認します

デバッグのワークフロー

Pod が起動しない

# 1. Get pod status and events
kubectl describe pod <name> -n <namespace>

# 2. Check logs (current or previous)
kubectl logs <name> -n <namespace> --tail=100
kubectl logs <name> -n <namespace> --previous  # If restarting

# 3. Check events for scheduling issues
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | grep <name>

# 4. Interactive debugging
kubectl exec -it <name> -n <namespace> -- /bin/sh

Service の接続性

# 1. Verify service exists and has endpoints
kubectl get svc <name> -n <namespace>
kubectl get endpoints <name> -n <namespace>

# 2. Check pod labels match service selector
kubectl get pods -n <namespace> --show-labels

# 3. Test from within cluster
kubectl run debug --rm -it --image=busybox -- wget -qO- http://<service>:<port>

# 4. Port-forward for local testing
kubectl port-forward svc/<name> 8080:80 -n <namespace>

リソース管理

Deployment

# List deployments
kubectl get deployments -n <namespace>

# Scale
kubectl scale deployment <name> --replicas=3 -n <namespace>

# Rollout status
kubectl rollout status deployment/<name> -n <namespace>

# Rollback
kubectl rollout undo deployment/<name> -n <namespace>

# History
kubectl rollout history deployment/<name> -n <namespace>

ConfigMap と Secret

# List
kubectl get configmaps -n <namespace>
kubectl get secrets -n <namespace>

# View ConfigMap data
kubectl get configmap <name> -n <namespace> -o jsonpath='{.data}'

# View Secret keys (NOT values)
kubectl get secret <name> -n <namespace> -o jsonpath='{.data}' | jq 'keys'

# Create from file
kubectl create configmap <name> --from-file=<path> -n <namespace> --dry-run=client -o yaml

クラスター運用

ノード管理

# List nodes with status
kubectl get nodes -o wide

# Node details
kubectl describe node <name>

# Cordon (prevent scheduling)
kubectl cordon <node>

# Drain (evict pods)
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

# Uncordon
kubectl uncordon <node>

リソース使用状況

# Node resources
kubectl top nodes

# Pod resources
kubectl top pods -n <namespace>

# Sort by memory
kubectl top pods -n <namespace> --sort-by=memory

同梱リソース

スクリプト

scripts/ にあります：

• debug_pod.py - 簡潔な出力で Pod を包括的にデバッグします
• get_resources.py - jsonpath を使って最小限のトークンでリソースの概要を取得します
• cluster_health.py - クラスターの状態をすばやく概観します

リファレンス

references/ にあります：

• kubectl-cheatsheet.md - 簡潔なコマンドリファレンス
• jsonpath-patterns.md - よく使われる JSONPath 式
• debugging-flowchart.md - Pod の問題に関する判断ツリー

注： 特定のトピックを詳しく調べるには、上記のリファレンスファイルを参照してください。

依存関係

必須

パッケージ	バージョン	用途
kubectl	1.25+	Kubernetes CLI
jq	1.6+	スクリプトでの JSON 解析

任意

パッケージ	バージョン	用途
k9s	0.27+	Kubernetes 用ターミナル UI
stern	1.25+	複数 Pod のログ追跡

公式ドキュメント

• kubectl クイックリファレンス
• JSONPath のサポート
• kubectl チートシート
• 実行中の Pod のデバッグ

トラブルシューティング

kubectl コマンドが見つからない

症状： command not found: kubectl

解決方法：

# macOS
brew install kubectl

# Verify
kubectl version --client

コンテキストが設定されていない

症状： error: no context is currently set

解決方法：

# List available contexts
kubectl config get-contexts

# Set context
kubectl config use-context <context-name>

権限が拒否される

症状： Error from server (Forbidden)

解決方法：

# Check current user
kubectl auth whoami

# Check permissions
kubectl auth can-i get pods -n <namespace>
kubectl auth can-i --list -n <namespace>

クラスターへの接続がタイムアウトする

症状： Unable to connect to the server: dial tcp: i/o timeout

解決方法：

# Check cluster endpoint
kubectl cluster-info

# Verify network connectivity
curl -k https://<cluster-api-endpoint>/healthz

# Check kubeconfig
cat ~/.kube/config

セットアップチェックリスト

このスキルを使用する前に、以下を確認してください。

• kubectl がインストールされている（kubectl version --client）
• Kubeconfig が設定されている（~/.kube/config が存在する）
• 正しいクラスターにコンテキストが設定されている（kubectl config current-context）
• 権限が確認されている（kubectl auth can-i get pods）
• JSON の解析用に jq がインストールされている（jq --version）