rootless-containers /usernetes

Kubernetes without the root privileges

★ 996⑂ 74👁 21⑃ 296● 121▤ 59
下载:gen3-v20260902.0gen3-v20260902.0 ↓20260902.02026-09-01
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

Discussions

Latest release

gen3-v20260902.0 gen3-v20260902.0 2026-09-01
What'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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON