ssh
Overview
This document is written for system integrators who wish to run minikube within a customized VM environment. The ssh driver allows advanced minikube users to skip VM creation, allowing minikube to be run on a user-supplied VM.
Requirements
A Linux VM with the following:
- systemd or OpenRC
- a container runtime, such as containerd, CRI-O or Docker
- cri-dockerd (if using Kubernetes +v1.24 &
dockercontainer-runtime) - a user with SSH key access and passwordless
sudo
This VM must also meet the kubeadm requirements, such as:
- 2 CPU’s
- 2GB RAM
- iptables
- conntrack
- crictl
- cni-plugins
- SELinux permissive
Usage
The ssh driver requires the IP address of the VM to use.
minikube start --driver=ssh --ssh-ip-address=vm.example.com
Example: Ubuntu LTS with containerd
This example prepares a fresh Ubuntu Server LTS VM and starts minikube on it using containerd. It was tested with Ubuntu 26.04 LTS (arm64) on a VM with 2 CPUs and 8 GB of RAM.
Note: Using
--container-runtime=containerdwith the ssh driver requires a minikube version that includes the fix for #23968.
On the host: copy your SSH key to the VM
ssh-copy-id -i ~/.ssh/id_ed25519.pub <user>@<vm-ip>
On the VM: allow passwordless sudo
minikube runs sudo non-interactively over SSH.
echo "$USER ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/minikube
On the VM: install containerd and dependencies
sudo apt-get update
sudo apt-get install -y containerd conntrack socat
Ubuntu’s containerd package does not create /etc/containerd/config.toml,
which minikube needs. Create the default configuration:
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo systemctl restart containerd
On the VM: install crictl and the CNI plugins
ARCH=$(dpkg --print-architecture)
CRICTL_VERSION=v1.35.0
curl -fsSL "https://github.com/kubernetes-sigs/cri-tools/releases/download/${CRICTL_VERSION}/crictl-${CRICTL_VERSION}-linux-${ARCH}.tar.gz" \
| sudo tar -xz -C /usr/local/bin
CNI_PLUGIN_VERSION=v1.9.1
sudo mkdir -p /opt/cni/bin
curl -fsSL "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGIN_VERSION}/cni-plugins-linux-${ARCH}-${CNI_PLUGIN_VERSION}.tgz" \
| sudo tar -xz -C /opt/cni/bin
On the host: start minikube
minikube start \
--driver=ssh \
--ssh-ip-address=<vm-ip> \
--ssh-user=<user> \
--ssh-key=~/.ssh/id_ed25519 \
--container-runtime=containerd
kubectl get nodes
The node should be Ready with containerd as its container runtime.
Issues
Troubleshooting
- Run
minikube start --alsologtostderr -v=4to debug crashes
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.