Read-only, local-first hardware health for Kubernetes nodes.
A small Go scanner for Linux software RAID and CPU thermal status.
Important
The current main branch and v0.2.1 release contain only the read-only scanner. v0.2.1 is the first scanner-only binary release. The earlier v0.2.0 tag and release predate the split and remain unchanged; they contain the pre-split source and binaries. Do not use v0.2.0 as the scanner-only release.
- What it checks
- How it works
- Demo previews
- Build and run
- Options and exit codes
- Go package
- Safety
- FAQ
- Development
- License
Kubernetes reports node and workload state, but does not expose Linux mdraid member state or host CPU thermal-zone readings. Run this one-shot scanner on the Linux host whose hardware you want to inspect.
| Signal | Source | Missing or ambiguous data |
|---|---|---|
| Software RAID | /proc/mdstat; evaluates multiple md* arrays |
Unreadable or incomplete state is UNKNOWN, not assumed healthy |
| CPU thermals | Recognized CPU/package zones under /sys/class/thermal |
Missing, unreadable, invalid, or ambient-only readings are UNKNOWN |
| Node identity | Host name or --node-name, matched against Kubernetes node name/hostname label |
Remote, unmatched, or ambiguous nodes remain UNKNOWN |
The warning threshold is configurable with --warn-temp (default 75°C). The v0.2.1 release provides Linux amd64 and arm64 binaries, SHA-256 checksums, and GitHub provenance attestations.
flowchart LR
host["Linux host running scanner"] --> raid["/proc/mdstat"]
host --> temp["/sys/class/thermal"]
identity["hostname or --node-name"] --> kube["read-only kubectl get nodes"]
raid --> report["Hardware health report"]
temp --> report
kube --> report
By default, the scanner uses the host name and matches it against a Kubernetes node name or kubernetes.io/hostname label. If the host and node names differ, pass --node-name; an explicit name must match exactly. Local readings are associated with a Kubernetes node only when the identity match is unique. The scanner never treats another node's missing telemetry as healthy.
These are illustrative Canvas mockups made with the Screenshot Studio. The names and readings are fictional; the images are not live captures. The second image is a mockup of the separate commercial Pro product and does not represent functionality in this public scanner.
Download v0.2.1 for the Linux host architecture, then verify its checksum and GitHub provenance before installing:
set -euo pipefail
ARCH=amd64 # use arm64 on a Linux ARM64 host
ASSET="kubectl-hwhealth-linux-${ARCH}"
BASE_URL="https://github.com/JemBuildz/kubectl-hwhealth/releases/download/v0.2.1"
curl -fsSLo "$ASSET" "$BASE_URL/$ASSET"
curl -fsSLo checksums.txt "$BASE_URL/checksums.txt"
grep -F " $ASSET" checksums.txt | sha256sum -c -
gh attestation verify "$ASSET" \
--repo JemBuildz/kubectl-hwhealth \
--signer-workflow JemBuildz/kubectl-hwhealth/.github/workflows/release.yml
chmod +x "$ASSET"
sudo install -m 0755 "$ASSET" /usr/local/bin/kubectl-hwhealthThe checksum detects corruption; because it is distributed with the binary, it is not independent publisher authentication. Provenance verification checks the release workflow identity and requires GitHub CLI with attestation support. See the v0.2.1 release for assets and details.
With Go 1.23 or newer, install the tagged scanner release with:
go install github.com/jembuildz/kubectl-hwhealth@v0.2.1Ensure $(go env GOPATH)/bin is on your PATH so kubectl can find the kubectl-hwhealth plugin.
git clone https://github.com/JemBuildz/kubectl-hwhealth.git
cd kubectl-hwhealth
go test ./...
go build -o kubectl-hwhealth .
sudo install -m 0755 kubectl-hwhealth /usr/local/bin/kubectl-hwhealthWith kubectl configured for the intended cluster, run the plugin from the host being inspected:
kubectl hwhealth --context homelab --node-name worker-2--context is optional and defaults to the current kubectl context. --node-name can be omitted when the host name matches the Kubernetes node identity.
To exercise the report path without relying on a degraded array, simulate a RAID finding:
kubectl hwhealth --simulate-raid-failThis substitutes a simulated degraded RAID result in the local scan. It does not perform Kubernetes actions or send alerts.
| Option | Purpose |
|---|---|
--context NAME |
Select the Kubernetes context for the read-only node query. |
--node-name NAME |
Explicit node name for this host; must match exactly when supplied. |
--warn-temp CELSIUS |
CPU/package warning threshold; default 75; must be finite and between 0 and 135. |
--simulate-raid-fail |
Display a simulated degraded RAID finding; no action is performed. |
--help |
Show the scanner options. |
Exit code 0 means no critical finding was reported. Exit code 2 is used for a critical finding or invalid command-line input. A failed Kubernetes query is shown as a warning and the local host is still reported.
The reusable read-only scanner is available at github.com/jembuildz/kubectl-hwhealth/pkg/health:
result, err := health.Scan(ctx, health.Options{
KubernetesContext: "homelab",
NodeName: "worker-2",
WarnTempC: 80,
})
if err != nil {
return err
}
for _, node := range result.Reports {
fmt.Printf("%s: %s\n", node.Name, node.StatusDisplay)
}health.Scan reads the local host's hardware files and may call only kubectl get nodes -o json. Its public API contains no node-remediation or webhook operations.
This repository's current scanner-only code is observational: it reads local hardware files and issues a read-only Kubernetes node query. It contains no cordon or drain implementation, license-key gate, or webhook sender. A Kubernetes identity with permission to list nodes is sufficient for cluster association; no write permission is needed.
Commercial Pro remediation is maintained separately and is not part of the current public source tree or scanner-only binaries.
Requires Go 1.23 or newer.
go test ./...
go vet ./...
go build .The release workflow runs tests and go vet on pushes and pull requests. The v0.2.1 scanner-only release provides Linux amd64/arm64 binaries, SHA-256 checksums, and GitHub provenance attestations.
It reads Linux software RAID status from /proc/mdstat and CPU/package thermal readings from recognized zones under /sys/class/thermal on the host where the command runs.
Yes. The current public main reads local hardware files and may run kubectl get nodes -o json to associate local readings with a node. It does not cordon or drain nodes, change Kubernetes resources, or send webhook requests.
No. Run it on each Linux host whose hardware you want to inspect. The Kubernetes node list is used for identity matching only; uninspected, unmatched, or ambiguous nodes remain UNKNOWN.
For node association, the active Kubernetes identity needs permission to list nodes. The public scanner requires no write permissions. If the kubectl query fails, it still reports the local host and indicates that cluster association was unavailable.
The scanner is intended to run on Linux and the release workflow builds Linux amd64 and arm64 binaries. Building from source requires Go 1.23 or newer.
Install the Linux binary from the v0.2.1 release, or use go install github.com/jembuildz/kubectl-hwhealth@v0.2.1. The v0.2.0 release predates the split and is not a build of the current scanner-only source.
It substitutes a simulated degraded RAID result so you can preview scanner output. It performs no Kubernetes action and sends no alert.
No. The current public source and scanner package contain only read-only diagnostics. Commercial Pro remediation is maintained separately.
Yes. Import github.com/jembuildz/kubectl-hwhealth/pkg/health and call health.Scan; see the Go package example.
The scanner-only source in the current public branch and the v0.2.1 release are licensed under the MIT License; see LICENSE. The historical v0.2.0 tag and release predate the split and are not covered by the license added to this scanner-only snapshot. That tag and release have been left unchanged.


