okteto-debugging

Okteto 環境デバッガー

このスキルは、壊れた Okteto 環境のトリアージを行います。サービスの動作に問題がある場合は、以下のトリアージアルゴリズムに従って確認し、該当するプレイブックを適用して、構造化された診断結果を出力してください。推測はせず、必ずコマンドの出力に基づいて結論を出してください。

診断は読み取り専用です。ここでは kubectl get、kubectl describe、kubectl logs、kubectl get events を使用できます。kubectl／helm を直接使ってクラスターを変更しないでください。修正には okteto build と okteto deploy を使用します（ライフサイクル操作、ワークツリーの分離、ティアダウンのルールについては okteto スキルを参照してください）。

トリアージアルゴリズム

以下の手順を順番に実行します。障害を特定した時点で終了してください。

手順 1：接続を確認し、名前空間を特定する

okteto context show

失敗した場合、ユーザーはクラスターから切断されています。そこで確認を終了し、次に進む前に再接続（okteto context use <url>）を案内してください。

JSON 出力にはアクティブな namespace が含まれています。これを取得してください。以下のすべてのコマンドでは、明示的に $ns を対象にします。

ns=$(okteto context show | jq -r .namespace)

分離されたワークツリーの名前空間で作業している場合（okteto スキルを参照）、代わりにその名前空間を使用してください。デバッグが必要な環境は、コンテキストのデフォルトではなく、その名前空間にあります。

kubectl の対象クラスターと名前空間は、Okteto と同じでなければなりません。 kubectl は独自の kubeconfig を読み込むため、特に同じマシンで複数のエージェントやワークツリーがアクティブな場合、Okteto コンテキストとは異なる名前空間、またはまったく別のクラスターを参照することがあります。okteto context で選択したクラスターの認証情報をダウンロードするには、okteto kubeconfig を実行し、すべての kubectl コマンドに -n "$ns" を指定してください。kubectl get pods -n "$ns" がエラーになる場合や、okteto.yaml のサービスと一致しないポッドが表示される場合は、診断結果を信頼する前に kubeconfig を修正してください。

手順 2：サービスを検出する

cat okteto.yaml

deploy セクションと dev セクションを解析し、正式なサービス名を特定してください。サービス名をハードコードせず、必ず okteto.yaml から取得してください。

手順 3：ポッドの状態をスナップショットする

kubectl get pods -n "$ns"

これがトリアージの主要な判断材料です。各ポッドを以下のいずれかの状態に分類し、該当するプレイブックを適用してください。

ポッドの状態	プレイブック
CrashLoopBackOff	クラッシュループ
OOMKilled	OOM キル
ImagePullBackOff / ErrImagePull	イメージのプル失敗
Pending（60 秒超）	スケジュール不可
Running だが応答しない／ヘルスチェックに失敗	ランタイムエラー
ポッドが存在しない／デプロイが完了していない	デプロイ失敗
すべてのポッドが Running かつ Ready	同期／開発モードの問題

ユーザーが特定のサービスを指定した場合は、そのサービスのポッドだけに絞り込んでください。サービスが指定されていない場合は、すべてのポッドを確認してください。

---

プレイブック

クラッシュループ（CrashLoopBackOff）

コンテナが起動してクラッシュし、Kubernetes が再起動を繰り返しています。

# Get logs from the previous (crashed) container instance
kubectl logs <pod-name> --previous -n "$ns"

# If that fails (first crash, no previous), get current logs
kubectl logs <pod-name> -n "$ns"

# Check exit code and liveness/readiness probe config
kubectl describe pod <pod-name> -n "$ns"

確認事項：

• kubectl describe pod の終了コード。Exit Code: 1 はアプリケーションエラー、Exit Code: 137 は OOM（OOM プレイブックを参照）、Exit Code: 126/127 はエントリーポイントのコマンドが見つからなかったことを示します
• --previous のログの末尾。クラッシュ直前の最後のエラーが、通常は根本原因です
• kubectl describe pod のイベントセクションにある Liveness Probe の失敗。ヘルスチェックのパスやタイムアウトの設定ミスが考えられます

一般的な根本原因：

• 環境変数が未設定、または値が誤っている（fatal: required env var FOO not set）
• まだ準備できていない依存サービス（データベース、メッセージキュー）に接続できない
• アプリケーションとプローブの設定でポートが一致していない
• コマンド／エントリーポイントが見つからない（ベースイメージが誤っている、または okteto.yaml の command に誤字がある）

---

OOM による強制終了（OOMKilled）

コンテナがメモリ制限を超過し、Kubernetes によって強制終了されました。

kubectl describe pod <pod-name> -n "$ns"

確認する項目：

• Last State セクションの OOMKilled
• Containers → Limits の limits.memory の値
• 制限値とサービスが実際に必要とするメモリ量を比較します

修正パターン： サービスの Helm values または okteto.yaml でメモリ制限を引き上げます。現在の制限値を正確にユーザーに示し、妥当な増加量（通常は 2 倍）を提案します。制限を完全に削除する提案はしないでください。

---

イメージのプル失敗

Kubernetes がコンテナイメージをプルできません。

kubectl describe pod <pod-name> -n "$ns"

確認する項目：

• Events セクションの Failed to pull image
• Kubernetes がプルしようとした正確なイメージ参照（レジストリ、リポジトリ、タグ）
• ImagePullBackOff と ErrImagePull の違い。どちらも意味は同じで、再試行の状態が異なります

一般的な根本原因：

• イメージが存在しない（タグの入力ミス、またはこのサービスで okteto build が実行されていない）
• イメージは存在するが、プル認証情報がないプライベートレジストリにある
• 不適切なプッシュの後にタグが削除または上書きされた

修正パターン： イメージが Okteto によってビルドされるはずの場合は、okteto build <service> を実行します。外部イメージの場合は、タグが存在することを確認します。認証情報が原因の場合は、ユーザーがイメージプルシークレットを作成できるよう支援します。

---

Pending / スケジュール不可

ポッドは Kubernetes に受け入れられましたが、ノードにスケジュールされていません。

kubectl describe pod <pod-name> -n "$ns"

# Also check recent namespace events for quota / resource pressure
kubectl get events -n "$ns" --sort-by=.lastTimestamp | tail -20

kubectl describe pod → Events で確認する項目：

• Insufficient cpu または Insufficient memory — ノードに空きがありません。リソースリクエストを確認します
• 0/N nodes are available — スケジュール条件に一致するノードがありません
• node(s) had untolerated taint — ノードのテイントに対する許容設定がポッドに必要です
• node(s) didn't match node affinity/selector — nodeSelector またはアフィニティルールが厳しすぎます
• リソースクォータ超過 — kubectl describe resourcequota -n "$ns" を確認します

修正パターン： エラーに応じた制約を確認します。リソースリクエストの場合は、リクエストを引き下げるか、ユーザーにノードプールのスケールを依頼します。テイントやセレクターの場合は、現在の制約を示し、削除または修正を提案します。

---

ランタイムエラー（Running だが正常でない）

ポッドは Running ですが、サービスが応答しない、ヘルスチェックが失敗する、またはリクエストでエラーが発生します。

# Get recent application logs
okteto logs <service> --since 10m -n "$ns"

# If that's not enough context
okteto logs <service> --tail 200 -n "$ns"

確認する項目：

• スタックトレースまたは panic: 行。ソースファイルと行番号を確認します
• 依存先への接続拒否やタイムアウトのエラー。サービスは稼働していますが、下流のサービスが稼働していません
• ミドルウェアまたはプロキシによって記録された HTTP 5xx エラー
• 「address already in use」— コンテナ内のポート競合です

修正パターン： スタックトレースまたはエラーのうち、最も関連性の高い 5～10 行を引用します。ソースファイルが記載されている場合は特定します。コードの変更、不足している環境変数、または起動が必要な依存サービスなど、具体的な修正方法を提案します。

---

デプロイ失敗

ポッドが作成される前に okteto deploy が失敗し、ポッドが現れませんでした。

# Check if the manifest is valid first
okteto validate

# Check deploy logs if validate passes
okteto logs --deploy -n "$ns"

確認する項目：

• okteto validate のエラー — YAML 構文、スキーマ違反、必須フィールドの不足
• デプロイログにある Helm テンプレートのレンダリングエラー
• イメージのビルド失敗（Dockerfile のエラー、ビルドコンテキストが大きすぎる）

修正パターン： okteto validate で検出された場合は、エラーと行を正確に示します。Helm エラーの場合は、テンプレートのパスを示します。ビルドエラーの場合は、失敗した Dockerfile のステージを示します。

---

同期／開発モードの問題

すべてのポッドが Running かつ Ready ですが、開発者のコード変更が開発用コンテナに反映されません。

okteto status は、アクティブな開発用コンテナのファイル同期状態を報告します。これは okteto up <service> セッションの実行中にのみ機能します。セッションが実行されていない場合、同期は行われていません。その場合は、ユーザーにセッションを開始するよう伝えてください。

okteto status -n "$ns"

# If the summary isn't enough, get syncthing troubleshooting links
okteto status --info -n "$ns"

確認する項目：

• Sync status: error または Sync status: paused
• ファイル数が増減していない
• 同期出力に表示されるパスが実際のソースディレクトリと一致しない

最も詳しい情報を確認できるのは okteto up のターミナル自体です。同期エラーや競合の警告はまずそこに表示されますが、そのセッションは確認できません。ユーザーに出力を貼り付けてもらってください。

修正手順： okteto.yaml の sync パスが実際のディレクトリ構造と一致していることを確認してください。パスが正しい場合は、okteto down を実行してから okteto up <service> を試してください（ユーザーは okteto up を対話形式で実行する必要があります。自分では決して実行しないでください）。同期が停止している場合は、okteto doctor で診断バンドルを生成できます。

---

出力形式

問題のあるサービスごとに、必ず1つのブロックを出力してください。

## Diagnosis: <service-name>
**Root cause:** <one sentence>
**Evidence:**
<relevant excerpt from logs or describe output — 5 to 20 lines, no more>
**Fix:**
<exact command to run or code change to make>
**Confidence:** High / Medium / Low

次の場合は、信頼度を Low にしてください。

• コンテナがクラッシュしたのが一度だけである（--previous のログを取得できない）
• エラーメッセージが曖昧、または存在しない
• 証拠に当てはまる根本原因が複数ある

すべてのポッドが正常な場合は、次のように報告してください。

All services are Running and Ready. No obvious failures detected.

If you're still seeing issues, run `okteto doctor` to generate a full diagnostic bundle.

---

よくある落とし穴

• kubectl と okteto の結果が異なる場合がある — kubectl は独自の kubeconfig コンテキストを使用します。そのコンテキストが、Okteto のコンテキストとは異なる名前空間やクラスターを参照している場合があります。kubectl の出力が okteto コマンドの報告と一致しない場合は、okteto kubeconfig を実行し、結論を出す前に -n "$ns" を指定して再確認してください。
• 初回のクラッシュでは kubectl logs --previous が失敗する — コンテナは少なくとも一度は再起動している必要があります。代わりに kubectl logs（現在のインスタンス）を使うか、イベントを確認してください。
• 終了コード137はOOMであり、アプリケーションエラーではない — CrashLoopBackOff で exit code: 137 が表示された場合は、クラッシュループではなくOOM による強制終了として扱ってください。
• Pending 状態のポッドにはログがない — kubectl logs は実行せず、kubectl describe pod と kubectl get events に進んでください。
• okteto logs と kubectl logs — アプリケーションの出力には okteto logs を優先してください。--previous が必要な場合や、describe にポッド名が必要な場合は kubectl logs を使ってください。
• デバッグの一環として okteto destroy を実行しないでください — まず診断してください。環境を復旧できず、ユーザーが明示的に求めた場合にのみ、環境の削除を提案してください。
• okteto up を実行しないでください — 対話形式のコマンドです。修正のために開発モードへの再入が必要な場合は、ユーザーにターミナルで okteto up <service> を実行するよう伝えてください。