kdescribe

Terminal highlighter for kubectl describe output.

kdescribe runs kubectl describe, finds common Kubernetes failure signals, and prints the most important findings first. It can also read describe output from stdin for scripting.

Usage

kubectl kdescribe pod <pod-name>
kubectl kdescribe pod <pod-name> -n <namespace>
kubectl kdescribe pod -A

Pipe mode is still supported:

kubectl describe pod <pod-name> | kdescribe

For local development:

go run . pod <pod-name>

Output formats

kubectl kdescribe pod <pod-name> --output human
kubectl kdescribe pod <pod-name> --output json
kubectl kdescribe pod <pod-name> --output markdown

Useful flags:

• --no-color disables ANSI colors
• --min-score 80 only shows high-signal findings
• --exit-code exits with status 1 when findings are present
• --show-all prints every finding instead of the top results

Current MVP

• regex-based detection for common workload issues
• severity and score for every finding
• line number and original describe line for context
• simple cluster health risk: LOW, MEDIUM, or HIGH
• lightweight parsing for Containers, Conditions, and Events

Example signals:

• OOMKilled
• CrashLoopBackOff
• ImagePullBackOff
• ErrImagePull
• FailedScheduling
• FailedMount
• readiness/liveness probe failures

Releasing

The release binary is named kubectl-kdescribe so krew can expose it as:

kubectl kdescribe

Build release artifacts with GoReleaser:

goreleaser release --snapshot --clean

On main, GitHub Actions builds archives with GoReleaser first, then semantic-release creates the GitHub Release and uploads those archives as release assets. Each archive contains the kubectl-kdescribe binary.

The draft krew manifest lives in krew/kdescribe.yaml. Replace sha256: TODO values with checksums from the release before submitting to the krew index.

Changelog

Releases and CHANGELOG.md are generated by semantic-release on every push to main. Use Conventional Commits so semantic-release can decide the next version:

feat: add workload grouping
fix: detect failed volume attachments
docs: document krew installation

Only commits that affect release notes, such as feat and fix, create a new release by default.