Skip to content

About

Read-only Linux hardware health scanner for Kubernetes nodes: mdraid status and CPU thermals. Go CLI and importable package.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

Repository files navigation

kubectl-hwhealth: Kubernetes Node Hardware Health Scanner

kubectl-hwhealth banner

Main CI MIT license for scanner core Go version Supported release platforms GitHub stars

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.

Contents

What it checks

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.

How it works

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
Loading

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.

Demo previews

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.

Illustrative read-only scan with fictional local and remote node data Illustrative mockup of the separate Pro dry-run product; not included in the public scanner

Build and run

Install a Linux release binary

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-hwhealth

The 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.

Install with go install

With Go 1.23 or newer, install the tagged scanner release with:

go install github.com/jembuildz/kubectl-hwhealth@v0.2.1

Ensure $(go env GOPATH)/bin is on your PATH so kubectl can find the kubectl-hwhealth plugin.

Build from source

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-hwhealth

With 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-fail

This substitutes a simulated degraded RAID result in the local scan. It does not perform Kubernetes actions or send alerts.

Options and exit codes

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.

Go package

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.

Safety

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.

Development

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.

FAQ

What hardware does kubectl-hwhealth check?

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.

Is the public scanner read-only?

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.

Does it collect hardware telemetry from every node remotely?

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.

What Kubernetes permissions are required?

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.

Which operating systems and CPU architectures are supported?

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.

How do I install the current scanner-only version?

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.

What does --simulate-raid-fail do?

It substitutes a simulated degraded RAID result so you can preview scanner output. It performs no Kubernetes action and sends no alert.

Are Pro remediation features included in this repository?

No. The current public source and scanner package contain only read-only diagnostics. Commercial Pro remediation is maintained separately.

Can I call the scanner from another Go program?

Yes. Import github.com/jembuildz/kubectl-hwhealth/pkg/health and call health.Scan; see the Go package example.

License

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.

About

Read-only Linux hardware health scanner for Kubernetes nodes: mdraid status and CPU thermals. Go CLI and importable package.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages