troubleshoot-ml-k8s

Diagnose failing Wikimedia KServe/Knative InferenceService deployments using kubectl evidence.

4|Updated May 12, 2021
One-click install
npx skills add https://github.com/wikimedia/machinelearning-liftwing-inference-services --skill troubleshoot-ml-k8s
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: troubleshoot-ml-k8s
Source: https://github.com/wikimedia/machinelearning-liftwing-inference-services/tree/main/.claude/skills/troubleshoot-ml-k8s
Command: npx skills add https://github.com/wikimedia/machinelearning-liftwing-inference-services --skill troubleshoot-ml-k8s

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps pinpoint why a Wikimedia KServe/Knative InferenceService deployment on ml-serve or ml-staging is failing, stuck, unreachable, not scaling, or returning bad responses.

Core Features & Use Cases

  • Evidence-driven Kubernetes triage: Guides you to gather the smallest set of facts (conditions, events, revisions, pods) to isolate the failing layer.
  • Symptom-to-layer branching: Uses targeted branches for missing/spec rejection, revision readiness issues, scheduling/persistence problems, crashes, readiness failures, ingress/routing failures, autoscaling/timeouts, and bad response payloads.
  • Cluster-safe workflow: Instructs you to run exact commands on deployment.eqiad.wmnet after entering the correct cluster context, without broad cluster sweeps.

Quick Start

Ask the Skill to diagnose an InferenceService failure by providing the cluster, namespace, and InferenceService name, then run the initial diagnostic bundle commands and paste the outputs back for analysis.

Frequently Asked Questions about troubleshoot-ml-k8s

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot a KServe InferenceService that is stuck in a pending or crashing state?

To troubleshoot a stuck or crashing KServe InferenceService, gather kubectl evidence including pod status, conditions, and events to isolate whether the failure is at the application or platform layer. This process narrows observed symptoms to the responsible layer for targeted resolution.

Why is my Knative revision not ready and how can I diagnose the deployment failure?

A Knative revision not ready indicates a deployment failure requiring checks of ksvc, revision, and route states alongside targeted logs. Diagnosing the failure involves mapping these specific conditions to underlying platform or application layer issues.

How do I fix KServe inference endpoint unreachable errors on Kubernetes?

Fixing KServe inference endpoint unreachable errors requires collecting evidence on route conditions and ingress states to identify routing failures. The workflow checks scaling and timeout issues to pinpoint the exact network layer responsible for the unavailability.

Can I use this to diagnose Kubernetes autoscaling and timeout issues for GPU inference workloads?

Yes, you can diagnose Kubernetes autoscaling and timeout issues for GPU inference workloads by analyzing revision states and pod events. The workflow applies evidence-driven branching to determine if scaling failures stem from resource constraints or application errors.

What is the best way to collect diagnostic evidence for a failing InferenceService deployment?

The best way to collect diagnostic evidence for a failing InferenceService deployment is running targeted kubectl commands to retrieve conditions, events, and logs after setting the correct cluster context. This cluster-safe approach avoids broad sweeps and grounds the analysis in specific facts.