Supporting material availability

This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:

• <support-root>/references/failure-patterns.md

Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.

Debug Buttercup

When to Use

• Pods in the crs namespace are in CrashLoopBackOff, OOMKilled, or restarting
• Multiple services restart simultaneously (cascade failure)
• Redis is unresponsive or showing AOF warnings
• Queues are growing but tasks are not progressing
• Nodes show DiskPressure, MemoryPressure, or PID pressure
• Build-bot cannot reach the Docker daemon (DinD failures)
• Scheduler is stuck and not advancing task state
• Health check probes are failing unexpectedly
• Deployed Helm values don't match actual pod configuration

When NOT to Use

• Deploying or upgrading Buttercup (use Helm and deployment guides)
• Debugging issues outside the crs Kubernetes namespace
• Performance tuning that doesn't involve a failure symptom

Namespace and Services

All pods run in namespace crs. Key services:

Confirm the cluster context and installed Buttercup version; crs, labels, queue names and health paths below are deployment assumptions. diagnosis.sh and deployment/collect-logs.sh are not bundled here; do not invent or run substitute helpers. Read-only diagnostics may still expose credentials/records or add load. Select the correct container and redact logs/CLIENT LIST/OTEL variables before sharing; avoid dumping all environment values. Namespace scoping does not constrain node-level commands. Use XPENDING for delivered-unacknowledged group messages and XINFO GROUPS for lag; XLEN counts retained entries. Do not restart or change Redis durability settings as part of diagnosis without a separate scoped recovery plan.

Triage Workflow

Always start with triage. Run these three commands first:

# 1. Pod status - look for restarts, CrashLoopBackOff, OOMKilled
kubectl get pods -n crs -o wide

# 2. Events - the timeline of what went wrong
kubectl get events -n crs --sort-by='.lastTimestamp'

# 3. Warnings only - filter the noise
kubectl get events -n crs --field-selector type=Warning --sort-by='.lastTimestamp'

Then narrow down:

# Why did a specific pod restart? Check Last State Reason (OOMKilled, Error, Completed)
kubectl describe pod -n crs <pod-name> | grep -A8 'Last State:'

# Check actual resource limits vs intended
kubectl get pod -n crs <pod-name> -o jsonpath='{.spec.containers[0].resources}'

# Crashed container's logs (--previous = the container that died)
kubectl logs -n crs <pod-name> --previous --tail=200

# Current logs
kubectl logs -n crs <pod-name> --tail=200

Historical vs Ongoing Issues

High restart counts don't necessarily mean an issue is ongoing -- restarts accumulate over a pod's lifetime. Always distinguish:

• --tail shows the end of the log buffer, which may contain old messages. Use --since=300s to confirm issues are actively happening now.
• --timestamps on log output helps correlate events across services.
• Check Last State timestamps in describe pod to see when the most recent crash actually occurred.

Cascade Detection

When many pods restart around the same time, check for a shared-dependency failure before investigating individual pods. The most common cascade: Redis goes down -> every service gets ConnectionError/ConnectionRefusedError -> mass restarts. Look for the same error across multiple --previous logs -- if they all say redis.exceptions.ConnectionError, debug Redis, not the individual services.

Log Analysis

# All replicas of a service at once
kubectl logs -n crs -l app=fuzzer-bot --tail=100 --prefix

# Stream live
kubectl logs -n crs -l app.kubernetes.io/name=redis -f

# Collect all logs to disk (existing script)
bash deployment/collect-logs.sh

Resource Pressure

# Per-pod CPU/memory
kubectl top pods -n crs

# Node-level
kubectl top nodes

# Node conditions (dis