Gentoo Linux 5.4.97内核Docker容器启动失败 cgroup v2报错排查

故障现象 #

• 运行环境为内核版本5.4.97的Gentoo Linux，Docker守护进程已通过systemd配置为正常运行状态
• 执行测试启动命令docker run kubler/mariadb时，Docker守护进程返回OCI运行时创建失败错误，完整报错内容为：

docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:415: setting cgroup config for procHooks process caused \\\"error while setting cgroup v2: [failed to load program: function not implemented]\\\"\"": unknown. ERRO[0000] error waiting for container: context canceled

排查过程记录 #

• 运行Docker官方环境检测脚本定位问题，脚本因系统不存在/proc/config.gz，自动从/boot/config-5.4.97-gentoo路径读取内核配置，完整检测输出如下：

warning: /proc/config.gz does not exist, searching other paths for kernel config ...
info: reading kernel config from /boot/config-5.4.97-gentoo ...

Generally Necessary:
- cgroup hierarchy: cgroupv2
- CONFIG_NAMESPACES: enabled
- CONFIG_NET_NS: enabled
- CONFIG_PID_NS: enabled
- CONFIG_IPC_NS: enabled
- CONFIG_UTS_NS: enabled
- CONFIG_CGROUPS: enabled
- CONFIG_CGROUP_CPUACCT: enabled
- CONFIG_CGROUP_DEVICE: enabled
- CONFIG_CGROUP_FREEZER: enabled
- CONFIG_CGROUP_SCHED: enabled
- CONFIG_CPUSETS: enabled
- CONFIG_MEMCG: enabled
- CONFIG_KEYS: enabled
- CONFIG_VETH: enabled
- CONFIG_BRIDGE: enabled
- CONFIG_BRIDGE_NETFILTER: enabled (as module)
- CONFIG_IP_NF_FILTER: enabled
- CONFIG_IP_NF_TARGET_MASQUERADE: enabled (as module)
- CONFIG_NETFILTER_XT_MATCH_ADDRTYPE: enabled (as module)
- CONFIG_NETFILTER_XT_MATCH_CONNTRACK: enabled
- CONFIG_NETFILTER_XT_MATCH_IPVS: missing
- CONFIG_NETFILTER_XT_MARK: enabled (as module)
- CONFIG_IP_NF_NAT: enabled
- CONFIG_NF_NAT: enabled
- CONFIG_POSIX_MQUEUE: enabled

Optional Features:
- CONFIG_USER_NS: enabled
- CONFIG_SECCOMP: enabled
- CONFIG_CGROUP_PIDS: enabled
- CONFIG_MEMCG_SWAP: enabled
- CONFIG_MEMCG_SWAP_ENABLED: enabled
- CONFIG_BLK_CGROUP: enabled
- CONFIG_BLK_DEV_THROTTLING: enabled
- CONFIG_CGROUP_PERF: enabled
- CONFIG_CGROUP_HUGETLB: enabled
- CONFIG_NET_CLS_CGROUP: enabled
- CONFIG_CGROUP_NET_PRIO: enabled
- CONFIG_CFS_BANDWIDTH: missing
- CONFIG_FAIR_GROUP_SCHED: enabled
- CONFIG_RT_GROUP_SCHED: missing
- CONFIG_IP_NF_TARGET_REDIRECT: missing
- CONFIG_IP_VS: enabled
- CONFIG_IP_VS_NFCT: missing
- CONFIG_IP_VS_PROTO_TCP: missing
- CONFIG_IP_VS_PROTO_UDP: missing
- CONFIG_IP_VS_RR: missing
- CONFIG_EXT4_FS: enabled
- CONFIG_EXT4_FS_POSIX_ACL: enabled
- CONFIG_EXT4_FS_SECURITY: enabled
- Network Drivers:
- "overlay":
- CONFIG_VXLAN: missing
- CONFIG_BRIDGE_VLAN_FILTERING: missing
Optional (for encrypted networks):
- CONFIG_CRYPTO: enabled
- CONFIG_CRYPTO_AEAD: enabled
- CONFIG_CRYPTO_GCM: enabled
- CONFIG_CRYPTO_SEQIV: enabled
- CONFIG_CRYPTO_GHASH: enabled
- CONFIG_XFRM: enabled
- CONFIG_XFRM_USER: enabled
- CONFIG_XFRM_ALGO: enabled
- CONFIG_INET_ESP: missing
- "ipvlan":
- CONFIG_IPVLAN: missing
- "macvlan":
- CONFIG_MACVLAN: missing
- CONFIG_DUMMY: missing
- "ftp,tftp client in container":
- CONFIG_NF_NAT_FTP: enabled (as module)
- CONFIG_NF_CONNTRACK_FTP: enabled
- CONFIG_NF_NAT_TFTP: missing
- CONFIG_NF_CONNTRACK_TFTP: missing
- Storage Drivers:
- "aufs":
- CONFIG_AUFS_FS: missing
- "btrfs":
- CONFIG_BTRFS_FS: enabled
- CONFIG_BTRFS_FS_POSIX_ACL: enabled
- "devicemapper":
- CONFIG_BLK_DEV_DM: enabled
- CONFIG_DM_THIN_PROVISIONING: missing
- "overlay":
- CONFIG_OVERLAY_FS: enabled
- "zfs":
- /dev/zfs: missing
- zfs command: missing
- zpool command: missing

Limits:
- /proc/sys/kernel/keys/root_maxkeys: 1000000

• 检测输出对应的核心异常点：
  • 当前内核已启用cgroupv2层级，缺失多项Docker运行所需的配置项
  • 缺失CONFIG_NETFILTER_XT_MATCH_IPVS配置
  • 尝试启用CONFIG_RT_GROUP_SCHED配置后系统启动失败：流程显示“[OK] terminate plymouth...”后卡死，无登录提示符，也无法进入sddm图形界面
  • Gentoo Wiki中的Docker配置指引与5.4.97内核不匹配：文档要求启用CFQ IO调度器，但当前内核配置中无该选项，仅提供BFQ调度器
• 已尝试的无效操作：先后在内核启动参数中设置systemd.unified_cgroup_hierarchy=0和systemd.unified_cgroup_hierarchy=1，均无法解决容器启动失败问题，报错始终指向cgroup v2程序加载失败

问题解决方案 #

• 根因匹配：报错中“error while setting cgroup v2: [failed to load program: function not implemented]”的核心触发原因，是5.4版本内核对cgroup v2的eBPF接口支持不全，而高版本runc默认使用eBPF路径处理cgroup v2配置，触发内核不支持的函数调用
• 定向调整步骤：
  • 降级runc至1.0.x稳定版本，关闭runc对cgroup v2 eBPF处理路径的依赖，恢复传统cgroup配置写入逻辑，避免触发内核未实现的函数调用
  • 内核配置遵循最小修改原则：
    • 无需强制启用CONFIG_RT_GROUP_SCHED，该配置仅用于实时进程的cgroup资源隔离，Docker默认运行路径不依赖该配置；之前启用后卡机是因为该配置与已开启的CONFIG_FAIR_GROUP_SCHED存在编译冲突，只需确认CONFIG_FAIR_GROUP_SCHED、CONFIG_CFS_BANDWIDTH处于开启状态，即可覆盖Docker对CPU资源管控的需求
    • 缺失的CONFIG_NETFILTER_XT_MATCH_IPVS仅在Docker切换为IPVS负载均衡模式时需要，当前Docker默认使用iptables模式，该配置缺失不会造成启动阻断，可按需后续补充
    • IO调度器使用现有BFQ配置即可，无需强行找回CFQ选项，5.4内核已将CFQ从默认编译选项中移除，BFQ对块设备IO的管控完全能满足Docker存储驱动的运行要求
  • 正确配置cgroup v1启动参数：
    • 不要仅设置单个cgroup参数，在GRUB内核启动行同时追加systemd.unified_cgroup_hierarchy=0 systemd.legacy_systemd_cgroup_controller=1——5.4内核配套的systemd版本需要同时搭配两个参数才能完全切换到v1层级，单独设置单个参数会导致systemd仍然部分加载cgroup v2组件，触发runc兼容问题
    • 执行grub-mkconfig -o /boot/grub/grub.cfg更新引导配置，重启后通过stat -fc %T /sys/fs/cgroup/命令确认层级：若输出为cgroup2fs说明仍处于v2层级，需要重新检查启动参数配置

内容的提问来源于stack exchange，提问作者Gerald Ortner