fix(utils): make install-minikube-cluster.sh work on macOS by HumphreySun98 · Pull Request #970 · vllm-project/production-stack

HumphreySun98 · 2026-06-04T22:09:36Z

Fixes #931.

Summary

The script assumed Linux throughout and failed on macOS in three distinct ways. All are fixed in this PR without changing Linux behavior.

Fixes

Minikube binary selection. Previously downloaded `minikube-linux-amd64` unconditionally even on Darwin. Also short-circuited on "minikube already on PATH" without checking the binary is actually executable — a Linux ELF copied to `/usr/local/bin/minikube` would never get replaced (matches the issue's reproduction: `/usr/local/bin/minikube: cannot execute binary file`). Now detects OS (`uname -s`) and arch (`uname -m`), downloads the matching `minikube-{linux,darwin}-{amd64,arm64}` release, and requires the existing binary to actually `minikube version` cleanly before treating it as installed.
`calculate_safe_memory`. Read `/proc/meminfo`, which doesn't exist on macOS. Now uses `sysctl -n hw.memsize` on Darwin (with a ~60% available estimate, since Docker Desktop's VM budget has no clean equivalent to Linux's `MemAvailable`) and keeps the existing `/proc/meminfo` path on Linux. cgroup-v2 detection stays Linux-only.
`systemctl restart docker` / `sudo sysctl fs.protected_regular=0`. Both Linux-only — `systemctl` isn't on macOS, and `fs.protected_regular` is a Linux sysctl. Now guarded on `HOST_OS == linux`, with a hint on macOS to restart Docker Desktop manually.

The BPF section was already guarded on `/proc/sys/net/core/bpf_jit_harden` existence, so no change needed there.

Test plan

`bash -n utils/install-minikube-cluster.sh` (syntax check) — passes.
Reading the diff: every Linux-only path is now behind an `HOST_OS == linux` (or pre-existing `/proc` existence) gate, so Linux behavior is byte-for-byte identical when those guards evaluate the same way.
On macOS, the previously-failing path now downloads `minikube-darwin-arm64` (or `-amd64` on Intel), skips `systemctl` and `sysctl fs.protected_regular`, and uses `sysctl -n hw.memsize` for memory sizing.

Out of scope

Docker Desktop restart automation on macOS (would need `osascript` + user permission). Left as a printed instruction. Same for the GPU Operator step — NVIDIA GPU passthrough on Apple Silicon Docker Desktop isn't supported by NVIDIA Container Toolkit, so users on macOS will hit the `No NVIDIA GPU detected` branch anyway.

Fixes vllm-project#931. The script previously assumed Linux throughout and failed on macOS in three distinct ways: 1. **Minikube binary selection.** Unconditionally downloaded minikube-linux-amd64 even on Darwin. Also short-circuited on 'minikube already on PATH' without checking the binary is executable, so a Linux ELF copied to /usr/local/bin/minikube would never get replaced. Now detects OS (uname -s) and arch (uname -m), downloads the matching minikube-{linux,darwin}-{amd64,arm64} release, and requires the existing binary to actually run before considering it installed. 2. **calculate_safe_memory.** Read /proc/meminfo, which doesn't exist on macOS. Now uses 'sysctl -n hw.memsize' on Darwin (with ~60% available estimate, since Docker Desktop's VM budget has no clean equivalent to MemAvailable) and keeps the existing /proc/meminfo path on Linux. cgroup-v2 detection stays Linux-only. 3. **systemctl restart docker / sudo sysctl fs.protected_regular=0.** Both Linux-only — systemctl isn't on macOS, and fs.protected_regular is a Linux sysctl. Now guarded on HOST_OS == linux, with a hint on macOS to restart Docker Desktop manually. BPF section was already guarded on /proc/sys path existence, no change needed there. Signed-off-by: HumphreySun98 <[email protected]>

gemini-code-assist

Code Review

This pull request updates utils/install-minikube-cluster.sh to support macOS and ARM64 architectures by adding OS and architecture detection, adjusting memory calculation, and restricting Linux-specific commands (like systemctl and sysctl fs.protected_regular) to Linux environments. Feedback points out that install-kubectl.sh (called by this script) still unconditionally downloads the Linux AMD64 binary, which will fail on macOS. Additionally, it is recommended to use the -f flag with curl when downloading Minikube to ensure the script fails immediately on HTTP errors.

gemini-code-assist · 2026-06-04T22:11:39Z

+OS_KERNEL="$(uname -s)"
+case "$OS_KERNEL" in
+  Linux)  HOST_OS=linux ;;
+  Darwin) HOST_OS=darwin ;;
+  *)      echo "ERROR: unsupported OS: $OS_KERNEL" >&2; exit 1 ;;
+esac


While this PR successfully adds OS and architecture detection to install-minikube-cluster.sh, the script still calls install-kubectl.sh (on line 38), which unconditionally downloads the Linux AMD64 binary of kubectl:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

On macOS, this results in an unexecutable Linux ELF binary being installed to ~/.local/bin/kubectl, causing any subsequent kubectl commands to fail with an execution format error.

To fully support macOS, utils/install-kubectl.sh also needs to be updated to detect the OS and architecture (similar to how it is done here) and download the correct binary.

gemini-code-assist · 2026-06-04T22:11:39Z

+  curl -LO "https://github.com/kubernetes/minikube/releases/latest/download/minikube-${HOST_OS}-${HOST_ARCH}"
+  sudo install "minikube-${HOST_OS}-${HOST_ARCH}" /usr/local/bin/minikube && rm "minikube-${HOST_OS}-${HOST_ARCH}"


Using curl -LO without the -f (or --fail) option can be problematic. If the server returns an HTTP error (such as a 404 or 500), curl will still exit with status 0 and save the error page's HTML content to the destination file. The script will then proceed to install this HTML file as the minikube binary, leading to confusing failures.

Adding the -f flag ensures curl fails immediately on server errors, allowing set -e to abort the script safely.

Suggested change

curl -LO "https://github.com/kubernetes/minikube/releases/latest/download/minikube-${HOST_OS}-${HOST_ARCH}"

sudo install "minikube-${HOST_OS}-${HOST_ARCH}" /usr/local/bin/minikube && rm "minikube-${HOST_OS}-${HOST_ARCH}"

curl -fLO "https://github.com/kubernetes/minikube/releases/latest/download/minikube-${HOST_OS}-${HOST_ARCH}"

sudo install "minikube-${HOST_OS}-${HOST_ARCH}" /usr/local/bin/minikube && rm "minikube-${HOST_OS}-${HOST_ARCH}"

ruizhang0101

LGTM

…-macos

Without -f, curl saves the server's error page (e.g. a 404/500 HTML body) to minikube-${HOST_OS}-${HOST_ARCH} and exits 0, so the script then tries to install that HTML as the minikube binary. -f makes curl exit non-zero on HTTP errors, letting set -e abort cleanly. Addresses review feedback on vllm-project#970. Signed-off-by: HumphreySun98 <[email protected]>

HumphreySun98 · 2026-06-16T16:16:25Z

Thanks for the review! Addressed both points:

curl -fLO — applied (1b1c450). Agreed; without -f, curl saves the error page and exits 0, so the script would try to install HTML as the binary.
install-kubectl.sh hardcodes linux/amd64 — good catch, and a real gap for a fresh macOS host (it does early-exit when kubectl is already on PATH, e.g. via brew, so it isn't always hit). Since it's a separate script and outside the scope of Bug: install-minikube-cluster.sh fails on macOS (wrong Minikube binary, Linux-only assumptions) #931 (which is specifically install-minikube-cluster.sh), I'll fix it in a small follow-up PR that gives install-kubectl.sh the same uname-based OS/arch detection — happy to link it here once it's up.

Also updated the branch to latest main (it had gone BEHIND). @ruizhang0101 — rebased + review feedback addressed, ready when you are. Thanks!

HumphreySun98 · 2026-06-16T16:23:33Z

Follow-up for the install-kubectl.sh OS/arch point is up: #976.

install-kubectl.sh always downloaded the linux/amd64 kubectl, so on macOS it installed an unexecutable Linux ELF (later kubectl calls fail with an exec format error). Detect OS (uname -s) and arch (uname -m) and download the matching bin/{linux,darwin}/{amd64,arm64}/kubectl, mirroring the OS/arch detection added to install-minikube-cluster.sh in #970. Also: treat an existing kubectl as installed only if it actually runs (`kubectl version --client`), so a stale Linux binary left on PATH on macOS is replaced rather than skipped; and use `curl -f` so HTTP errors abort instead of saving an error page as the binary. Follow-up to the review on #970; relates to #931. Signed-off-by: HumphreySun98 <[email protected]> Co-authored-by: Rui Zhang <[email protected]>

HumphreySun98 · 2026-06-23T04:08:30Z

Thanks for merging #976! I noticed #970 was closed but #931 (the install-minikube-cluster.sh macOS support) is still open — should I reopen/rebase this one, or did the minikube changes land elsewhere? Happy to resubmit a clean rebase if it's still useful.

ruizhang0101

LGTM

gemini-code-assist Bot reviewed Jun 4, 2026

View reviewed changes

ruizhang0101 previously approved these changes Jun 15, 2026

View reviewed changes

HumphreySun98 added 2 commits June 16, 2026 11:14

Merge remote-tracking branch 'upstream/main' into fix-minikube-script…

53679e9

…-macos

HumphreySun98 dismissed ruizhang0101’s stale review via 1b1c450 June 16, 2026 16:15

HumphreySun98 mentioned this pull request Jun 16, 2026

fix(utils): make install-kubectl.sh work on macOS #976

Merged

ruizhang0101 closed this Jun 17, 2026

ruizhang0101 reopened this Jun 23, 2026

Merge branch 'main' into fix-minikube-script-macos

4b52b74

ruizhang0101 approved these changes Jun 25, 2026

View reviewed changes

Merge branch 'main' into fix-minikube-script-macos

799f3c1

ruizhang0101 merged commit 5261497 into vllm-project:main Jun 25, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(utils): make install-minikube-cluster.sh work on macOS#970

fix(utils): make install-minikube-cluster.sh work on macOS#970
ruizhang0101 merged 5 commits into
vllm-project:mainfrom
HumphreySun98:fix-minikube-script-macos

HumphreySun98 commented Jun 4, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 4, 2026

Uh oh!

gemini-code-assist Bot Jun 4, 2026

Uh oh!

ruizhang0101 left a comment

Uh oh!

HumphreySun98 commented Jun 16, 2026

Uh oh!

HumphreySun98 commented Jun 16, 2026

Uh oh!

HumphreySun98 commented Jun 23, 2026

Uh oh!

ruizhang0101 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		curl -LO "https://github.com/kubernetes/minikube/releases/latest/download/minikube-${HOST_OS}-${HOST_ARCH}"
		sudo install "minikube-${HOST_OS}-${HOST_ARCH}" /usr/local/bin/minikube && rm "minikube-${HOST_OS}-${HOST_ARCH}"

Uh oh!

Conversation

HumphreySun98 commented Jun 4, 2026

Summary

Fixes

Test plan

Out of scope

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

ruizhang0101 left a comment

Choose a reason for hiding this comment

Uh oh!

HumphreySun98 commented Jun 16, 2026

Uh oh!

HumphreySun98 commented Jun 16, 2026

Uh oh!

HumphreySun98 commented Jun 23, 2026

Uh oh!

ruizhang0101 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants