vixens-troubleshoot

Diagnose Kubernetes pod failures and ArgoCD sync issues with read-only kubectl commands.

1|Updated Aug 29, 2025
One-click install
npx skills add https://github.com/charchess/vixens --skill vixens-troubleshoot
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vixens-troubleshoot
Source: https://github.com/charchess/vixens/tree/main/.opencode/skills/vixens-troubleshoot
Command: npx skills add https://github.com/charchess/vixens --skill vixens-troubleshoot

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill provides expert guidance for diagnosing and resolving common issues within the Vixens multi-cluster Kubernetes homelab infrastructure, ensuring smooth operation and rapid recovery.

Core Features & Use Cases

  • Proactive Diagnostics: Offers read-only kubectl commands to quickly assess cluster health, identify pod failures, and check ArgoCD synchronization status.
  • GitOps-Centric Solutions: Emphasizes fixing issues by committing changes to Git and allowing ArgoCD to reconcile, aligning with the Vixens GitOps philosophy.
  • Common Issue Resolution: Provides step-by-step troubleshooting for scenarios like "OutOfSync" ArgoCD apps, "CrashLoopBackOff" pods, "Pending" pods, service accessibility problems, and ingress/certificate issues.
  • Recovery Procedures: Outlines safe methods for restarting applications, forcing ArgoCD refreshes, and handling stuck ArgoCD applications.
  • Incident Lessons: Includes detailed post-mortems of past production incidents to prevent recurrence.

Quick Start

Use the vixens-troubleshoot skill to debug why the 'authentik' application is not working.

Frequently Asked Questions about vixens-troubleshoot

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

FAQPage Schema
How do I troubleshoot CrashLoopBackOff and OOMKilled pods in a Kubernetes homelab?

To troubleshoot CrashLoopBackOff and OOMKilled pods in a Kubernetes homelab, run read-only kubectl commands to assess pod health and resource limits. You can then resolve the issue by committing configuration changes to Git and letting ArgoCD reconcile the deployment.

Why is my ArgoCD application stuck OutOfSync and how do I fix it with GitOps?

ArgoCD applications stuck OutOfSync can be fixed using GitOps by committing the desired state changes to your Git repository. You can then force an ArgoCD refresh to trigger reconciliation and bring the cluster state back into sync.

What is the best way to debug ingress controller errors and service accessibility problems in Kubernetes?

The best way to debug ingress controller errors and service accessibility problems in Kubernetes is to run read-only kubectl diagnostics to check service routing and ingress configurations. Fixes are then applied by updating Git and allowing ArgoCD to reconcile the manifests.

Can I use kubectl to directly modify resources when troubleshooting a Talos Linux cluster?

You should not use kubectl to directly modify resources when troubleshooting a Talos Linux cluster. Instead, run read-only kubectl commands for diagnostics and apply all fixes by committing changes to Git, maintaining strict GitOps principles for cluster reconciliation.

How do I safely restart applications and force ArgoCD refreshes for stuck applications?

To safely restart applications and force ArgoCD refreshes for stuck applications, follow established recovery procedures that trigger reconciliation through Git updates. This ensures applications restart without violating GitOps principles or destabilizing the cluster state.

What causes pending pods in Kubernetes and how can GitOps workflows resolve them?

Pending pods in Kubernetes are typically caused by resource constraints or unschedulable nodes, diagnosed via read-only kubectl commands. GitOps workflows resolve them by committing adjusted resource requests or node affinity rules to Git for ArgoCD to reconcile.