DevOps

How to Install Rancher Desktop on Arch Linux.

A complete guide to installing Rancher Desktop on Arch Linux, including fixing VMX Unsupported errors and verifying your cluster with k9s

#rancher #kubernetes #arch-linux #kvm #k9s

If you are running Arch Linux (BTW) and trying to set up a local Kubernetes environment, Rancher Desktop is a fantastic alternative to Docker Desktop. However, getting it to play nice with a custom setup, especially if you are using a window manager like Hyprland, can be tricky.

I recently spent time debugging why Rancher wouldn’t start, only to find out it was a mix of missing BIOS flags and a missing credential manager.

Here is the complete, step-by-step guide to installing Rancher Desktop on Arch Linux, including how to fix “VMX Unsupported” errors on HP hardware and how to verify your cluster with k9s.

Step 1: The “Silent” Blocker (BIOS Settings)

Before you even touch the terminal, you must verify your hardware is ready. Rancher Desktop relies on KVM (Kernel-based Virtual Machine). If your CPU isn’t exposing virtualization extensions, the app will simply crash or fail to start the internal VM.

The Check

Run this command to check your status:

LC_ALL=C lscpu | grep Virtualization

If this returns nothing (or if lscpu shows KVM: Mitigation: VMX unsupported), your virtualization is disabled at the firmware level. You need to fix this in the BIOS.

The Fix (HP EliteBook Specifics)

On HP laptops, the settings are tucked away. Here is exactly how to configure it:

Enter BIOS:

Restart your laptop.

Immediately start tapping the Esc key repeatedly (don’t hold it; tap it like you’re trying to wake it up).

When the “Startup Menu” appears, press F10 to enter BIOS Setup.

The Configuration: Navigate to the System Configuration tab. You need to verify three specific checkboxes (as shown in the screenshot below):

  • Virtualization Technology (VTx): MUST BE CHECKED.

    • Why? This is the engine that allows Rancher to run a Virtual Machine. Without it, the app dies.

  • Virtualization Technology for Directed I/O (VTd): CHECK THIS TOO.

    • Why? This isn’t strictly required to boot, but it improves performance by allowing the VM to handle memory and hardware more efficiently.

  • Trusted Execution Technology (TXT): UNCHECK THIS.

    • Why? This is critical. If enabled, it attempts to secure the boot process in a way that often conflicts with Arch Linux’s KVM drivers, preventing the virtualization engine from loading.

Save your settings (usually F10) and reboot.

Step 2: The Prerequisites (KVM & Pass)

Rancher Desktop has two strict requirements that it doesn’t always warn you about clearly.

1. Enable KVM Modules

The KVM drivers are usually loaded automatically by Arch Linux, but we should verify they are active.

lsmod | grep kvm

# Add your user to the KVM group so you don't need root to run VMs
sudo usermod -aG kvm $USER

(Note: You usually need to log out and back in for the group change to take effect).

2. The Credential Manager (pass)

Rancher Desktop requires a secure way to store credentials. On Linux, it expects pass. If you skip this, Rancher Desktop will likely hang on the “Initializing” screen.

# 1. Install pass
sudo pacman -S pass

# 2. Generate a GPG key if you don't have one
gpg --generate-key
# (Copy the GPG Key ID generated at the end, e.g., 8CBBDE9E)

# 3. Initialize pass with that ID
pass init <YOUR_GPG_KEY_ID>

Step 3: Installation

Now that the environment is actually ready, the installation is straightforward. I recommend using the AUR version as it handles dependencies (like QEMU) automatically.

Using yay (or your preferred helper):

yay -S rancher-desktop-bin

Note: The -bin version installs the pre-compiled binary, which saves you from compiling from source.

Step 4: The Tooling (Kubectl & K9s)

While Rancher Desktop bundles some binaries, managing your own CLI tools is the “Arch way.” It ensures you have the latest versions and cleaner integration with your shell.

1. Install kubectl

This is the standard command-line tool for controlling Kubernetes clusters.

sudo pacman -S kubectl

If kubectl is the steering wheel, k9s is the dashboard. It provides a terminal-based UI to interact with your cluster, view logs, and ssh into pods instantly.

yay -S k9s

Step 5: Verification (Don’t Trust, Verify)

Once Rancher Desktop is running, don’t just rely on the UI “Green Light.” As engineers, we verify at the terminal using the tools we just installed.

1. Check the Cluster Health

Is the Kubernetes control plane actually alive?

kubectl get pods -A

What to see: You should see a list of system pods (like coredns and metrics-server) with a status of Running or Completed.

Trouble? If you see Pending or ImagePullBackOff for a long time, check your internet connection or disk space.

2. Deep Dive with K9s

For a real-time view of your cluster, launch k9s.

k9s

Once inside the interface (as seen in the screenshot below):

  • View All Pods (0): By default, k9s might only show the default namespace (which is usually empty). Press the 0 key (zero) to switch the view to All Namespaces.
  • You will see pods like coredns, traefik, and local-path-provisioner appear.
  • Look for the blue rows, these indicate active, selected items.
  • Check Status: The STATUS column is your best friend. You want to see Running (green/white) or Completed. If you see red text here, that pod is crashing.
  • Quit (:q): To exit k9s and return to your terminal, type :q and hit Enter.

3. Verify the Container Runtime

If you selected dockerd (moby) as your container engine in Rancher settings (which I recommend for a Docker Desktop replacement), verify that the system images are present:

docker images

What to see: You should see images like rancher/k3s and rancher/mirrored-coredns. This confirms the engine is active and can pull images.

4. Verify the Config Context

Rancher Desktop automatically modifies your kubeconfig. Ensure you are targeting the right cluster:

cat ~/.kube/config

Look for: current-context: rancher-desktop.

Why? This ensures your kubectl commands are hitting your local Rancher cluster and not accidentally deploying test pods to your company’s production server!

Troubleshooting Cheat Sheet

  • “Error starting lima”: You likely forgot to add your user to the kvm group (sudo usermod -aG kvm $USER).
  • “CredsStore error”: You skipped the pass init step.
  • VS Code not finding Docker: Add export DOCKER_HOST=unix://$HOME/.rd/docker.sock to your .bashrc or .zshrc.

Conclusion

Installing Rancher Desktop on Arch requires a little more manual labor than on macOS or Windows, but the control you get is worth it. By ensuring your BIOS virtualization is unlocked and using k9s for visibility, you get a powerful, local Kubernetes environment that fits perfectly into a terminal-centric workflow.

Comments