Kubernetes Deployment Health-Check CLI Tool
Build a Go command-line tool that checks whether deployments on a Kubernetes cluster rolled out successfully, made for CI/CD pipelines. After a pipeline deploys a new version, it runs the tool, which waits until every pod of the new version is ready or a timeout passes, spots common failures early (a container crashing repeatedly, an image that can't be downloaded, a pod stuck waiting), prints the recent logs of failing pods to explain what went wrong, and exits with a code the pipeline can act on. It uses client-go, the official Go library for the Kubernetes API, and is organized as cobra subcommands. You'll learn how Kubernetes deployments and rollouts work, using client-go and watches, designing CI-friendly tools, and testing with fake clients.
- Estimate
- ~13h
- Steps
- 6
- Completed by
- 0
- Proposed by
- codeseed.app
client-go · Kubernetes API · cobra
Project roadmap
- 01
Connect to the cluster
~2hCreate a local cluster with kind or minikube to develop against. Create a Go module with client-go and cobra. Load the configuration from --kubeconfig, the KUBECONFIG variable or ~/.kube/config (and in-cluster config when running inside a pod), with a --context option. Add a version command that prints the cluster's version. Done when: the tool connects to your local cluster and prints its version.
- 02
Show deployment status
~2hAdd a status command that lists deployments in a namespace (or those matching a label selector) with their desired, updated, ready and available replicas and their conditions. Mark each as healthy, progressing or failing, based on the replica counts and the Progressing and Available conditions. Done when: status shows correct information for a few test deployments.
- 03
Wait for a rollout
~2.5hAdd a wait command taking deployment names and a --timeout. Use a watch (or polling) to follow each deployment until its observed generation matches, all replicas are updated and available, and old replicas are gone, the same checks kubectl rollout status uses. Fail when the timeout passes or the ProgressDeadlineExceeded condition appears. Done when: waiting on a good deployment succeeds, and waiting on a broken one fails with the reason.
- 04
Explain failures
~2.5hWhen a rollout isn't healthy, find the new version's pods and look for known problems: CrashLoopBackOff, ImagePullBackOff or ErrImagePull, pods stuck Pending (unschedulable), and failing readiness probes. Print a clear diagnosis per pod, and the last 50 log lines from crashing containers (including the previous run's logs). Fail fast when a known fatal problem is detected, instead of waiting for the timeout. Done when: a deployment with a wrong image name fails quickly with a clear explanation.
- 05
Make it CI-friendly
~1.5hUse distinct exit codes: 0 for success, 1 for a failed rollout, 2 for a timeout, and 3 for configuration or connection errors. Add --output json with a structured result per deployment, and a quiet mode for pipelines. Write an example CI job in README.md. Done when: the exit codes match each case, and the JSON output is valid.
- 06
Test it
~2.5hWrite unit tests with client-go's fake clientset (k8s.io/client-go/kubernetes/fake), creating deployments and pods in various states: healthy, progressing, crash-looping, image errors, and pending. Test the status logic, the diagnosis and the exit codes. Add an end-to-end script that deploys good and broken apps to a kind cluster. Done when: go test ./... passes, and the end-to-end script works.
Resources
Ready to build this?
Get a GitHub repo and start building. Your AI reviewer checks each step as you go.
Tech stack