Skip to content

feat: add qovery-cluster-ops skill (node churn, Karpenter, upgrades) - #18

Open
Guimove wants to merge 1 commit into
mainfrom
feat/qovery-cluster-ops
Open

feat: add qovery-cluster-ops skill (node churn, Karpenter, upgrades)#18
Guimove wants to merge 1 commit into
mainfrom
feat/qovery-cluster-ops

Conversation

@Guimove

@Guimove Guimove commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Why

Three recurring cluster support cases have no skill today: nodes replaced so often that pods restart without crashing, clusters that never scale down after load drops, and pods stuck in Pending because a node pool hit its limits. The existing skills stop at the application layer. qovery-optimize's own reference says "Verify Karpenter is consolidating properly" without saying how, and qovery-troubleshoot's layer 8 only checks that Karpenter can provision nodes. No skill encodes the actual diagnosis or the fix, so every case is re-investigated by hand.

What

  • Five diagnosis playbooks: node churn, blocked consolidation, pending pods, node memory pressure, spot interruptions
  • Karpenter tuning through the KARPENTER cluster feature (consolidate_after, stable pool consolidation window, instance requirements, node pool limits, spot, node disks), applied via PUT cluster + cluster deploy. Editing CRDs directly is called out as wrong: the next cluster update overwrites them
  • Resilience review: PDBs (both failure modes), do-not-disrupt, stable pool placement, multi-AZ spread
  • Kubernetes upgrade guidance (managed vs self-managed) with a preparation checklist
  • A report template that doubles as a support escalation dossier

Every API field comes from qovery-openapi-spec (ClusterFeatureKarpenterParameters, KarpenterNodePool* schemas) and every CLI command from the qovery-cli source.

Why a separate skill, not an extension of qovery-troubleshoot

  • Different entry point. Troubleshoot starts from a broken service. In most cluster-ops cases nothing is broken: deployments pass, apps run, but nodes churn or the bill creeps up. Half of this skill is proactive work (node pool configuration, resilience review, upgrade prep) with no incident to troubleshoot.
  • Different fix surface. Troubleshoot edits service config: ports, probes, env vars, memory. Cluster-ops edits the cluster object and requires a cluster redeploy, with rolling node replacement as a side effect the user must be warned about.
  • Trigger precision. Descriptions are how agents route requests. Folding node churn, Karpenter tuning and upgrades into troubleshoot's description would dilute both problem spaces and degrade routing. This keeps the existing split: troubleshoot (broken) / speedup (slow) / optimize (costly) / cluster-ops (unstable infra).
  • Explicit handoffs both ways: troubleshoot's layer 8 stays a shallow check that routes here; cluster-ops routes app crashes to troubleshoot and over-requested resources to optimize.

Structure

Follows the CLAUDE.md conventions: SKILL.md at 120 lines (triage, checklist, navigation table, quick reference), 7 self-contained reference files loaded on demand, slash command (reference only, not installed), 4 eval scenarios. No templates/scripts, so the User-Agent rule is covered by the _shared/auth.md runtime directive.

Test plan

  • Every SKILL.md under 500 lines
  • All internal reference links resolve
  • No anti-patterns (2nd-person openers, time-sensitive content, AI trailers)
  • scripts/sync-shared.sh run after adding the skill to the sync map (auth.md, console-url-detection.md shipped into the skill)
  • local-install.sh smoke-tested in a throwaway HOME, installs the skill to all 3 locations
  • evals/qovery-cluster-ops.json valid and follows the authoring guidelines (golden path, variants, edge case)

Reviewer notes

  • Replaces feat: add qovery-cluster-ops skill (node churn, Karpenter, upgrades) #17, which was based on the stale refactor branch; this one is built on main's current layout (9 skills including qovery and qovery-terraform, README count updated to nine).
  • Karpenter tuning is scoped to AWS EKS with the KARPENTER feature; on other providers the skill degrades explicitly to phases 1, 2, 5, 6.
  • Registered everywhere CLAUDE.md requires: install.sh and local-install.sh SKILLS arrays, README (table row, trigger prompts, slash command table, manual cp lines), sync map.

…rades)

Ninth skill covering the cluster infrastructure layer:
- Diagnosis playbooks: node churn, blocked consolidation, pending pods,
  node memory pressure, spot interruptions
- Karpenter node pool tuning via the KARPENTER cluster feature
  (consolidate_after, stable pool consolidation window, requirements,
  limits, spot, node disks), applied through PUT cluster + deploy
- Disruption resilience review (PDBs, do-not-disrupt, stable pool,
  multi-AZ spread) and Kubernetes upgrade preparation
- Registered in install.sh/local-install.sh, README, sync-shared map;
  4 eval scenarios
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant