fix(installer): pin the k3d release (K3D_VERSION) — deterministic, rate-limit-proof installs

[LukasWodka]

Summary

The upstream k3d install script resolves its version via a GitHub releases/latest redirect that breaks under GitHub rate limiting on shared egress IPs (CI runners, corporate NAT). That took down 2/9 distro CI jobs on main on 2026-07-21 (Prereqs — amazonlinux:2023, Prereqs — ubuntu:24.04) with a bare curl: (22) 404 / Failed to install k3d — and the same failure mode can hit real customer installs behind shared NAT (hospitals, enterprises).

This pins k3d the same way K8S_VERSION already pins k3s: a K3D_VERSION default (v5.9.0) in common.sh. Since review, upstream's install.sh is no longer used at all — @saadqbal pulled the pinned script and found it performs no checksum verification (its downloadFile fetches the bare binary; installFile just chmod+cp), contrary to what this PR originally claimed. The installer now fetches k3d-linux-<arch>plus the release's checksums.txt directly from the pinned release and sha256-verifies before installing (fail-closed; mirrors the existing _fetch_kubectl pattern). This also removes the releases/latest lookup from the default path entirely, so the rate-limit failure can't occur there. K3D_VERSION=latest resolves the newest tag at install time via the plain /releases/latest redirect (no API) and then takes the same verified path; an empty value falls back to the pin, and malformed values fail closed before any fetch (a /-carrying value could otherwise traverse outside k3d-io/k3d — Bugbot). Both the Tier-0 (user-space) and sudo paths install via a plain verified mv.

Windows rider (same review finding):install-k8s.ps1 fetched sha256sum.txt, an asset name that has never existed on k3d releases (it's checksums.txt) — the request 404'd into a fail-open catch, so the Windows k3d verification silently never ran. URL fixed; verification is now live there too.

Also: the preflight tool-host probe for a missing k3d now points at github.com (the raw.githubusercontent.com install script is no longer fetched).

Related

Failing run: https://github.com/tracebloc/client/actions/runs/29839314271

Type of change

• Bug fix

Test plan

• bats scripts/tests/setup-linux.bats → 50/50, incl. 5 tests for the new path: verified direct download (asserts binary + checksums.txt fetched at the tag, sha256sum --check ran, no install.sh anywhere), checksum-mismatch fails closed with nothing installed, asset-missing-from-checksums fails closed, sudo install target, latest resolves then takes the same verified path
• bats scripts/tests/preflight.bats → 52/52
• shellcheck --severity=error clean; bash -n clean; scripts/check-style.sh clean; scripts/gen-manifest.sh regenerated
• CI Prereqs matrix (9 distros) exercises the real download + verification end-to-end on this PR

Deployment notes

Pin bump procedure: update K3D_VERSION in scripts/lib/common.sh (+ help text/golden/manifest) when we want a newer k3d — same convention as the K8S_VERSION pin.

Checklist

• Tests added / updated and passing locally
• Docs updated if behavior or config changed (--help env list + script headers)
• No secrets / credentials in the diff
• For security-sensitive paths: appropriate reviewer requested (@saadqbal reviewing)
• Terminal output follows STYLE.MD — bash scripts/check-style.sh passes

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches privileged installer download paths and supply-chain verification on Linux and Windows; behavior change is intentional hardening but misconfiguration or GitHub egress issues will now hard-fail k3d install instead of silently proceeding.

Overview
Linux installs no longer pipe through upstream k3d install.sh (no checksum verification, releases/latest failures under GitHub rate limits). The installer adds K3D_VERSION (default v5.9.0) and downloads k3d-linux-<arch> plus checksums.txt from that tag, SHA256-verifying before install—same pattern as kubectl. K3D_VERSION=latest resolves the tag via /releases/latest, then uses the same verified path; invalid tags abort before any fetch.

Windows direct-download path is fixed: checksums came from a non-existent sha256sum.txt URL and errors were swallowed, so verification never ran. It now uses checksums.txt and fails closed (remove binary on fetch/mismatch/missing line).

Docs/help/golden, preflight egress hint (github.com for k3d), manifest hashes, and bats coverage for pin/latest/mismatch/sudo/malformed version are updated.

^{Reviewed by Cursor Bugbot for commit ab9eabc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e69ec70. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6b25719. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

Functional review \u2014 passed\n\nBasis: the behavioural suites that ran on this PR at merge against real environments, not mocks:\n\n- on multiple Ubuntu releases + \u2014 a real install exercised end-to-end on real distros, behind a TLS-inspecting proxy\n\nI could not reach the dev API (no dev credentials), so rather than rubber-stamp I used the strongest evidence available: these suites exercise the actual behaviour this change alters, on real infrastructure. Advancing \u2192 .\n\nIf the functional reviewer wants a manual pass on dev in addition, please move it back and say so.