{"record":{"id":"f4e9b7f2cff1159c","repo":"k3s-io/k3s","slug":"delegated-cgroup-v2-controllers-are-required-for-r","errorCode":null,"errorMessage":"delegated cgroup v2 controllers are required for rootless","messagePattern":"delegated cgroup v2 controllers are required for rootless","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/daemons/agent/agent_linux.go","lineNumber":32,"sourceCode":"\t\"github.com/k3s-io/k3s/pkg/util\"\n\t\"github.com/sirupsen/logrus\"\n\t\"golang.org/x/sys/unix\"\n\tkubeletconfig \"k8s.io/kubelet/config/v1beta1\"\n\tutilsnet \"k8s.io/utils/net\"\n\tutilsptr \"k8s.io/utils/ptr\"\n)\n\nconst socketPrefix = \"unix://\"\n\nfunc createRootlessConfig(argsMap map[string]string, controllers map[string]bool) error {\n\targsMap[\"feature-gates=KubeletInUserNamespace\"] = \"true\"\n\t// \"/sys/fs/cgroup\" is namespaced\n\tcgroupfsWritable := unix.Access(\"/sys/fs/cgroup\", unix.W_OK) == nil\n\tif controllers[\"cpu\"] && controllers[\"pids\"] && cgroupfsWritable {\n\t\tlogrus.Info(\"cgroup v2 controllers are delegated for rootless.\")\n\t\treturn nil\n\t}\n\treturn errors.New(\"delegated cgroup v2 controllers are required for rootless\")\n}\n\nfunc kubeProxyArgs(cfg *config.Agent) map[string]string {\n\tbindAddress := \"127.0.0.1\"\n\tif utilsnet.IsIPv6(net.ParseIP(cfg.NodeIP)) {\n\t\tbindAddress = \"::1\"\n\t}\n\targsMap := map[string]string{\n\t\t\"proxy-mode\":                        \"iptables\",\n\t\t\"healthz-bind-address\":              bindAddress,\n\t\t\"kubeconfig\":                        cfg.KubeConfigKubeProxy,\n\t\t\"cluster-cidr\":                      util.JoinIPNets(cfg.ClusterCIDRs),\n\t\t\"conntrack-max-per-core\":            \"0\",\n\t\t\"conntrack-tcp-timeout-established\": \"0s\",\n\t\t\"conntrack-tcp-timeout-close-wait\":  \"0s\",\n\t}\n\tif cfg.NodeName != \"\" {\n\t\targsMap[\"hostname-override\"] = cfg.NodeName","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/daemons/agent/agent_linux.go#L14-L50","documentation":"createRootlessConfig requires, for rootless k3s: the 'cpu' and 'pids' cgroup v2 controllers delegated to the user and /sys/fs/cgroup writable inside the user namespace (unix.Access W_OK). Missing any of the three returns this error; kubelet cannot enforce cpu/pids limits without delegation.","triggerScenarios":"Running k3s rootless without systemd Delegate=yes for the user slice; cgroup v1 host (no delegation model); rootless inside a container/CI where /sys/fs/cgroup is mounted read-only; user@.service without enable-linger and proper drop-ins.","commonSituations":"Following rootless setup docs but skipping the systemd override; running rootless k3s inside Docker/Podman without --cgroupns=private and delegated controllers; host booted with hybrid cgroups.","solutions":["Apply the standard rootless systemd override: mkdir -p ~/.config/systemd/user/service.d with [Service] Delegate=yes, then systemctl daemon-reload and re-login (see k3s rootless docs).","Ensure the host boots with cgroup v2 unified mode only (systemd.unified_cgroup_hierarchy=1).","cat /sys/fs/cgroup/cgroup.controllers from the user session and verify cpu and pids appear in cgroup.subtree_control after delegation.","In containers, run the rootless container itself with delegated cgroups (e.g., podman run --cgroupns=host with systemd) rather than nesting k3s rootless."],"exampleFix":"# before: no delegation, k3s rootless fails\n# after\nmkdir -p ~/.config/systemd/user/service.d\ncat > ~/.config/systemd/user/service.d/delegate.conf <<EOF\n[Service]\nDelegate=yes\nEOF\nsystemctl --user daemon-reload\nloginctl enable-linger $USER","handlingStrategy":"validation","validationCode":"// Reproduce createRootlessConfig's gate before launching:\nfunc rootlessReady(controllers map[string]bool) error {\n\tif !controllers[\"cpu\"] || !controllers[\"pids\"] {\n\t\treturn errors.New(\"delegate cpu and pids controllers to the user (systemd Delegate=yes)\")\n\t}\n\tif unix.Access(\"/sys/fs/cgroup\", unix.W_OK) != nil {\n\t\treturn errors.New(\"/sys/fs/cgroup not writable: fix user-namespace mount/delegation\")\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install the systemd Delegate=yes user drop-in as part of rootless provisioning, before first start.","Enable lingering (loginctl enable-linger) so delegation survives logout.","Verify with: cat /sys/fs/cgroup/cgroup.controllers shows cpu and pids from the user session.","Do not nest k3s rootless inside containers lacking cgroup delegation."],"tags":["k3s","rootless","cgroups","cgroup-v2","linux","kubelet"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}