Single-node k3s installer with sane defaults for local dev

install-k3s-like-rancher-desktop.md

install-k3s-like-rancher-desktop.sh

Rancher Desktop's "it just works" experience — without the VM overhead.

Installs a single-node k3s cluster directly on your Linux host with a kubeconfig that's ready to use immediately, just like Rancher Desktop would set up, but native.

What it does

1. Writes a minimal k3s config (Traefik disabled by default, world-readable kubeconfig)
2. Installs k3s via the official install script (stable channel)
3. Waits for the node to be Ready
4. Symlinks the kubeconfig to ~/.kube/config for the calling user
5. Configures kubelet graceful node shutdown (pods are terminated cleanly on reboot/poweroff)
6. Detects your shell rc file and suggests the KUBECONFIG export if missing

Usage

sudo ./install-k3s-like-rancher-desktop.sh

To keep the bundled Traefik ingress controller:

sudo ./install-k3s-like-rancher-desktop.sh --keep-traefik

Notes

• Traefik is disabled by default — pass --keep-traefik to keep it, or bring your own ingress controller.
• The kubeconfig is set to mode 0644 so the symlink works without root. On multi-user systems, consider restricting permissions.
• Graceful node shutdown is set to 15s (5s for critical pods). Adjust /var/lib/rancher/k3s/agent/etc/kubelet.conf.d/99-shutdown.conf if needed.
• Linux only. If you're on macOS/Windows, you probably want Rancher Desktop (with the VM).

install-k3s-like-rancher-desktop.sh

#!/usr/bin/env bash
set -euo pipefail

# Rancher Desktop's "it just works" k3s setup — without the VM.
# Installs a single-node k3s server with kubeconfig ready to use.
#
# Usage: sudo ./install-k3s-like-rancher-desktop.sh [--keep-traefik]
#
# Options:
#   --keep-traefik  Don't disable the bundled Traefik ingress controller
#
# Note: the kubeconfig is set to mode 0644 so the symlink works
# without root. On multi-user systems, consider restricting this.

KEEP_TRAEFIK=false
for arg in "$@"; do
  case "$arg" in
    --keep-traefik) KEEP_TRAEFIK=true ;;
    *) echo "Unknown option: $arg"; exit 1 ;;
  esac
done

if [[ $EUID -ne 0 ]]; then
  echo "This script must be run as root (sudo ./install-k3s-like-rancher-desktop.sh)"
  exit 1
fi

REAL_USER="${SUDO_USER:-$USER}"
REAL_HOME=$(eval echo "~$REAL_USER")

echo "==> Writing k3s config..."
mkdir -p /etc/rancher/k3s
if $KEEP_TRAEFIK; then
  cat > /etc/rancher/k3s/config.yaml <<'EOF'
write-kubeconfig-mode: "0644"
EOF
else
  cat > /etc/rancher/k3s/config.yaml <<'EOF'
write-kubeconfig-mode: "0644"
disable:
  - traefik
EOF
fi

echo "==> Installing k3s (stable channel)..."
curl -sfL https://get.k3s.io | sh -

echo "==> Waiting for node to be Ready..."
until k3s kubectl get nodes | grep -q ' Ready'; do
  sleep 2
done

echo "==> Symlinking kubeconfig to $REAL_HOME/.kube/config..."
mkdir -p "$REAL_HOME/.kube"
chown "$REAL_USER":"$REAL_USER" "$REAL_HOME/.kube"
ln -sf /etc/rancher/k3s/k3s.yaml "$REAL_HOME/.kube/config"

k3s kubectl get nodes
echo ""

# Kubelet drop-in: graceful node shutdown (kill pods cleanly on poweroff/reboot)
echo "==> Configuring kubelet graceful shutdown..."
KUBELET_DROPIN="/var/lib/rancher/k3s/agent/etc/kubelet.conf.d/99-shutdown.conf"
mkdir -p "$(dirname "$KUBELET_DROPIN")"
cat > "$KUBELET_DROPIN" <<'KUBELET_EOF'
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
shutdownGracePeriod: 15s
shutdownGracePeriodCriticalPods: 5s
KUBELET_EOF
systemctl restart k3s
echo "Kubelet graceful shutdown configured (15s grace, 5s critical)."

# Detect shell rc file and suggest KUBECONFIG export
SHELL_NAME=$(basename "$(getent passwd "$REAL_USER" | cut -d: -f7)")
case "$SHELL_NAME" in
  zsh)  RC_FILE="$REAL_HOME/.zshrc" ;;
  bash) RC_FILE="$REAL_HOME/.bashrc" ;;
  *)    RC_FILE="$REAL_HOME/.profile" ;;
esac

KUBECONFIG_LINE='export KUBECONFIG="$HOME/.kube/config"'
if grep -qF 'KUBECONFIG' "$RC_FILE" 2>/dev/null; then
  echo "k3s is up. KUBECONFIG already set in $RC_FILE, nothing to add."
else
  echo "k3s is up. Add this to $RC_FILE:"
  echo "  $KUBECONFIG_LINE"
fi