996
stars
74
forks
21
watchers
296
prs
121
issues
59
releases
README
Usernetes: Kubernetes without the root privileges (Generation 3) Usernetes deploys a Kubernetes cluster without requiring root privileges on the host, so as to mitigate potential container-breakout vulnerabilities. Two deployment modes are supported: - Kubernetes-in-Docker (default): Deploys a Kubernetes cluster inside Rootless Docker, Rootless Podman, or Rootless nerdctl. This mode is similar to Rootless kind and Rootless minikube, but Usernetes supports creating a cluster with multiple hosts. - Kubernetes-in-Kubernetes: Usernetes runs inside an existing Kubernetes cluster, as UserNS-enabled pods (hostUsers: false). Project history - Generation 1 (gen1 branch, 2018-2023): The original Usernetes, implemented in the style of "Kubernetes The Hard Way". This generation was hard to use due to lack of support for kubeadm. - Generation 2 (gen2 branch, 2023-2026): Switched to Kubernetes-in-Docker mode for simplicity. This switch enabled supporting kubeadm. - Generation 3 (2026-present): Additionally added support for Kubernetes-in-Kubernetes mode. Components - Cluster configuration: kubeadm - CRI: containerd - OCI: runc - CNI: Flannel (default) or Calico (VXLAN mode; Kubernetes-in-Docker mode only) [!NOTE] The documentation below is for the Kubernetes-in-Docker mode. See ./kubernetes for the Kubernetes-in-Kubernetes mode. Requirements - One of the following host operating system: |Host operating system|Minimum version| |---------------------|---------------| |Ubuntu (recommended) |22.04 | |Rocky Linux |9 | |AlmaLinux |9 | |Fedora |(?) | - One of the following container engines: |Container Engine |Minimum version| |------------------------------------------------------------------------------------|---------------| |Rootless Docker (recommended)|v20.10 | |Rootless Podman |v4.x | |Rootless nerdctl |v1.6 | bash curl -o install.sh -fsSL https://get.docker.com sudo sh install.sh dockerd-rootless-setuptool.sh install - systemd lingering: bash sudo loginctl enable-linger $(whoami) - cgroup v2 delegation: bash sudo mkdir -p /etc/systemd/system/[email protected] sudo tee /etc/systemd/system/[email protected]/delegate.conf /dev/null [Service] Delegate=cpu cpuset io memory pids EOF sudo systemctl daemon-reload - Kernel modules: sudo tee /etc/modules-load.d/usernetes.conf /dev/null br_netfilter vxlan EOF sudo systemctl restart systemd-modules-load.service - sysctl: sudo tee /etc/sysctl.d/99-usernetes.conf /dev/null net.ipv4.conf.default.rp_filter = 2 EOF sudo sysctl --system - [Podman only] Custom configuration (since Podman v5): Podman v5 mkdir -p "$HOME/.config/containers/containers.conf.d" cat "$HOME/.config/containers/containers.conf.d/slirp4netns.conf" [network] change the network mode from pasta to slirp4netns default_rootl
Top issues
#121Fails on Chrome OS Crostini8 comments · 2020-01-15#311Issue pulling image with insufficient sub/guids6 comments · 2023-11-23#242Devices support6 comments · 2021-09-08#347Cluster port: expose 0.0.0.05 comments · 2024-12-05#378[WSL2] Build my own image from source Dockerfile4 comments · 2025-07-28#412calico (vxlan) packets drop with rootless podman3 comments · 2026-09-24#385question about uids3 comments · 2026-02-13#357Bug: logs / exec interactive for container with custom ports3 comments · 2024-12-11
Discussions
#370Rootless CSI drivers?0 comments · 2025-04-27#329bypass4netns benchmark result (with multiple EC2 instances)1 comments · 2024-04-10#325Question about offline installation0 comments · 2024-04-05#304CNCF TAG Runtime Discussion/Presentation3 comments · 2023-09-15
Latest release
gen3-v20260902.0 gen3-v20260902.0 2026-09-01What's Changed Support running Kubernetes in Podman 6 (404) Support running Kubernetes in Rootful Docker (405 , thanks to @vsoch for the original PR 366) Similar to kind and minikube, but supports creating a cluster with multiple hosts Support Calico (VXLAN mode) in addition to Flannel (406) Clean up udev rules (407, 408) Full Changelog: https://github.com/rootless-containers/usernetes/compare/gen3-v20260828.0...gen3-v20260902.0