GROOT: One archive for cluster diagnostics

If you have ever SSH’d into three terminals during an incident, copy-pasting kubectl get, kubectl logs, and kubectl describe while the clock ticks, you already know the problem: manual capture is slow, inconsistent, and easy to get wrong—especially on large clusters.

GROOT is a small open-source Go CLI ( Cobra + Viper ) that automates that workflow. You configure namespaces, workloads, and options once; GROOT runs the right kubectl invocations in parallel, writes a predictable directory layout, and produces a single .tar.gz you can attach to a ticket, upload to storage, or hand to a vendor.

This post walks through why it exists, how it behaves, and how to run it safely in production—including notifications, cron, and the guardrails around optional extra_kubectl commands.

Big picture (one glance)

The problem GROOT solves

During troubleshooting or post-incident review, you usually need a bundle of evidence:

• Cluster-wide signals: nodes, events, pod list
• Namespace-scoped resources and pod logs (sometimes including previous container logs)
• Optional node detail (describe, top) when the incident touches capacity or scheduling
• A sanitized snapshot of kube context (not the raw secret file—GROOT writes a summary under extras/)

Doing that by hand means dozens of commands, different filenames every time, and no guarantee the next engineer collects the same shape of data. GROOT’s goal is repeatable, fast capture with one entrypoint: groot collect.

What GROOT actually does

Under the hood, GROOT still uses kubectl as the execution engine (no in-cluster agent). That keeps RBAC and behavior aligned with what operators already understand, while worker concurrency (collection.worker_concurrency) speeds up I/O-bound phases.

High-level features (see the README for the full list):

Notifications send a one-line summary (totals, duration, output dir, archive path). Outbound HTTP uses a bounded client timeout so a stuck webhook does not hang the whole run.

Quick start

Prerequisites (all installs): kubectl on PATH, a valid kubeconfig, and RBAC sufficient for read/list/log operations.

Prerequisites (build from source only): Go 1.26+ and Git.

Install from GitHub Releases

Pre-built .deb, .rpm, .tar.gz (and .zip on Windows) are published on Releases. GoReleaser names files with the semver without v (e.g. groot_0.1.8_amd64.deb), while the GitHub download URL uses the tag with v (…/download/v0.1.8/…). Use TAG for the path and VER="${TAG#v}" for the filename, or copy exact names from the release page.

Replace v0.1.8 / 0.1.8 and amd64 below with the release and CPU you need (arm64 on many ARM machines).

Debian / Ubuntu (.deb)

Installs the groot binary under /usr/bin and ships a sample at /etc/groot/groot.yml.sample (from configs/groot.yml.sample in the repo). For a machine-wide active config, copy it: sudo cp /etc/groot/groot.yml.sample /etc/groot/groot.yml and edit groot.yml, or rely on default discovery (see Configuration model).

TAG=v0.1.8
VER="${TAG#v}"
DEB="groot_${VER}_amd64.deb"
TMP="/tmp/${DEB}"
if ! curl -fsSL "https://github.com/hrodrig/groot/releases/download/${TAG}/${DEB}" -o "$TMP"; then
  echo "Download failed — check tag and filename (basename has no v)." >&2; exit 1
fi
[ -f "$TMP" ] || { echo "Missing $TMP after curl" >&2; exit 1; }
sudo apt install "$TMP"
# or: sudo dpkg -i "$TMP"
groot --version

On Debian/Ubuntu, installing a .deb from $HOME can trigger _apt permission denied if your home is not traversable; /tmp avoids that.

Fedora / RHEL / AlmaLinux / Rocky (.rpm)

Same binary path and /etc/groot/groot.yml.sample layout as the .deb.

TAG=v0.1.8
VER="${TAG#v}"
curl -fsSLO "https://github.com/hrodrig/groot/releases/download/${TAG}/groot_${VER}_amd64.rpm"
sudo rpm -Uvh "groot_${VER}_amd64.rpm"
# or: sudo dnf install "./groot_${VER}_amd64.rpm"
groot --version

Tarball (Linux / macOS, no package manager)

Archive names look like groot_0.1.8_linux_amd64.tar.gz or groot_0.1.8_darwin_arm64.tar.gz (no v in the basename).

TAG=v0.1.8
VER="${TAG#v}"
OS=linux    # or: darwin
ARCH=amd64  # or: arm64
curl -fsSLO "https://github.com/hrodrig/groot/releases/download/${TAG}/groot_${VER}_${OS}_${ARCH}.tar.gz"
tar xzf "groot_${VER}_${OS}_${ARCH}.tar.gz"
# GoReleaser wraps files in a directory named like the archive without .tar.gz — adjust if your layout differs.
cd "groot_${VER}_${OS}_${ARCH}"
./groot --version

On Windows, download the matching .zip, unpack it, and run groot.exe from a terminal with kubectl available.

After any install, generate or reuse a config and run groot collect (see below). With no --config, GROOT picks the first existing file among ./groot.yml, ~/.groot/groot.yml, /etc/groot/groot.yml, then /etc/groot/groot.yml.sample. You can always pass --config /path/to/file.yaml.

Build from source

git clone https://github.com/hrodrig/groot.git
cd groot
make build

Generate a starter config (matches the repo’s sample and groot --print-sample-config):

./bin/groot --print-sample-config > groot.yml
# Edit namespaces, targets, output_dir, notify.*, etc.
./bin/groot collect

Handy flags:

• --test-connection — sanity-check cluster access without collecting
• --verbose — print each command as it runs
• --quiet — suppress normal console noise; notifications still fire unless disabled in config
• --no-notify — skip all notify channels for this run (same as GROOT_NO_NOTIFY=1)
• --message "meaningful-label" — sanitized suffix on archive / related names

Configuration model

If you pass --config /path/to/file.yaml, that file is the only YAML source for that run.

Otherwise the first existing file wins, in this order:

1. ./groot.yml
2. ~/.groot/groot.yml
3. /etc/groot/groot.yml
4. /etc/groot/groot.yml.sample

If none of those exist, built-in defaults apply, and GROOT_* environment variables override where documented.

Kubeconfig resolution is documented in the README: CLI flag → KUBECONFIG → YAML kubeconfig → kubectl defaults.

Targets and pod logs

If you define collection.targets for a namespace, pod log collection for that namespace is limited to pods belonging to those workloads. If a namespace has no targets, GROOT keeps broader pod log behavior for that namespace—useful for control-plane or shared namespaces.

Helm instances are matched via app.kubernetes.io/instance as documented in the project.

extra_kubectl: power with guardrails

You can append arbitrary read-only diagnostics as extra jobs, e.g.:

extra_kubectl:
  - "get componentstatuses"
  - "get csr"

GROOT splits each string on whitespace and passes arguments directly to kubectl (no shell). At config load time, only allowlisted, read-oriented first verbs are accepted (for example get, describe, logs, top, …, plus config view … and auth can-i …). Anything else fails fast so a bad paste cannot turn into delete or exec by accident.

Output layout

Each run creates a timestamped working directory under output_dir, then archives it:

• Archive name: <timestamp>-<cluster>[-<sanitized-message>].tar.gz
• Inside the tarball: paths are rooted under the capture folder name so extracting many runs into one parent directory (e.g. ~/tmp/groot-out) does not mix kube-system/ trees from different captures.

Typical top-level groups include nodes/, extras/, per-namespace folders, and pod log files named pod__node.log (and .previous.log when enabled).

Notifications in incident workflows

Enable channels in notify.* and provide webhooks or tokens. For PagerDuty Events v2, routing keys can also be ;-separated for multiple integrations. The README spells out payload shape, severity values, and HTTP 202 expectations for PagerDuty.

For cron where you only want the archive locally:

0 * * * * GROOT_NO_NOTIFY=1 /usr/local/bin/groot collect --config /home/you/.groot/prod.yml --quiet

Security and operations notes

• RBAC: GROOT runs as your kube identity. Tight RBAC on the ServiceAccount or user still applies.
• Secrets in archives: Logs and describes may contain sensitive material—treat bundles like production data.
• Notify credentials: Prefer environment variables or secret stores; the README lists GROOT_NOTIFY_* env names.
• Pre-built binaries: Check GitHub Releases for GoReleaser artifacts when you do not want to compile.

Why Go, Cobra, and Viper?

• Single static binary easy to ship to bastions and CI agents
• Familiar CLI patterns (subcommands, persistent flags)
• Portable configuration (YAML + env) without inventing a new DSL

The repository includes make release-check (lint, race-enabled tests, vulnerability and cyclomatic gates, GoReleaser config validation) for maintainers cutting releases.

Contributing and feedback

GROOT is MIT-licensed. Issues and PRs are welcome against develop (see CONTRIBUTING.md). If you try it on your next incident, open an issue with what worked, what felt missing, or what integrations you would like next.

Closing

GROOT does not replace observability platforms or centralized logging—it compresses the first hour of kubectl archaeology into one repeatable command and one archive. That is often exactly what you need before you dive into traces, metrics, or vendor support.

• Repository: github.com/hrodrig/groot
• Releases: GitHub Releases

If this post saved you a round of manual copy-paste, consider starring the repo so others find it faster.

Disclosure: human vs AI in this article

This post is meant to be technically accurate and useful on dev.to; here is how it was produced so you can judge it fairly.

Tools: generative models used inside Cursor; no fully autonomous “agent publish”—a human reviewed the repo-facing claims.

Your responsibility: release filenames and flags can change between tags. Always confirm commands and asset names on GitHub Releases and in the latest README before production use.

Percentages are honest estimates (not measured tokens); they reflect effort and decision ownership, not word count.