gke-workload-troubleshooting

GKE Workload Troubleshooting Skill

Use this skill to systematically diagnose and resolve failures in application workloads deployed in GKE clusters. This skill enforces a read-only diagnostics boundary before proposing manifest or config corrections.

🔍 Diagnostic Workflow

Step 0: Context Acquisition & Time Window Definition

To begin troubleshooting, acquire the following context from the user or active SETTINGS.md config:

• Project ID (e.g., my-gcp-project)
  • Cluster Name (e.g., my-gke-cluster)
  • Cluster Location (e.g., us-central1)
  • Workload Name (e.g., payment-api)
  • Workload Namespace (e.g., checkout)
  • Issue Time (Optional, e.g., 2026-06-01T15:30:00Z)

Before running any diagnostics or kubectl commands, you must fetch GKE credentials and context for the target GKE cluster:

gcloud container clusters get-credentials <cluster_name> --region <cluster_location>

Time Handling & Fallbacks:

1. Determine Issue Timestamp ($T$):

   • Specific Time Provided: If the user provides a specific timestamp, use it as $T$.
   • Relative Time Provided (e.g., "5 minutes ago"): Dynamically calculate the corresponding UTC timestamp based on the current system time, and use it as $T$.
   • No Time Provided (Default):
     1. Retrieve the GKE pod status (kubectl get pods -n <namespace> -o yaml).
     2. If there are crashing or pending containers, check their state transition timestamps (e.g. status.containerStatuses[*].lastState.terminated.finishedAt or status.startTime) and use that transition time as $T$.
     3. If no active transitions are found, default to the current system time as $T$.

2. Window Calculation: Center a 1-hour query window around the issue timestamp $T$:

   • Start_Time = T - 30m
   • End_Time = T + 30m

---

Step 1: Analyze Pod Status and Conditions

Inspect the workload's active pod states and controller status.

Diagnostic Commands: