kubernetes/kops · error

failed to create cgroupv2 mount unit: %w

Error message

failed to create cgroupv2 mount unit: %w

What it means

CiliumBuilder.Build also creates a cgroupv2 mount unit for /run/cilium/cgroupv2 via buildCgroup2Mount; failures are wrapped in this error. Cilium needs a writable cgroupv2 hierarchy for its datapath, so nodeup stops building the Cilium model if this unit cannot be created.

Source

Thrown at nodeup/pkg/model/networking/cilium.go:58

// Build is responsible for configuring the network cni
func (b *CiliumBuilder) Build(c *fi.NodeupModelBuilderContext) error {
	// As long as the Cilium Etcd cluster exists, we should do this
	if b.NodeupConfig.UseCiliumEtcd {
		if err := b.buildCiliumEtcdSecrets(c); err != nil {
			return err
		}
	}

	if b.NodeupConfig.Networking.Cilium == nil {
		return nil
	}

	if err := b.buildBPFMount(c); err != nil {
		return fmt.Errorf("failed to create bpf mount unit: %w", err)
	}

	if err := b.buildCgroup2Mount(c); err != nil {
		return fmt.Errorf("failed to create cgroupv2 mount unit: %w", err)
	}

	disableManageForeignRoutes(c, b.Distribution)
	disableCloudInitNetworkHotplug(c, b.Distribution)

	if b.NodeupConfig.Networking.Cilium.IPAM == kops.CiliumIpamEni {
		maskEC2NetUtilsUdevRules(c, b.Distribution)
		setMACAddressPolicyNone(c, b.Distribution)
		if err := markSecondaryENIsUnmanaged(c, b.Distribution); err != nil {
			return err
		}
	}

	return nil
}

func (b *CiliumBuilder) buildBPFMount(c *fi.NodeupModelBuilderContext) error {
	var fsdata unix.Statfs_t

View on GitHub (pinned to 4c8573c808)

Solutions

1. Inspect the wrapped error to see whether Statfs failed for reasons other than ENOENT
2. Ensure the node has cgroup v2 enabled (kernel ≥ 4.x, systemd with cgroup2) or the path can be auto-created by systemd
3. Check /run is writable when nodeup runs
4. Verify the generated systemd mount unit has valid settings

Example fix

// before (grub)
GRUB_CMDLINE_LINUX="... systemd.unified_cgroup_hierarchy=0"
// after
GRUB_CMDLINE_LINUX="... systemd.unified_cgroup_hierarchy=1"

if _, err := os.Stat("/run/cilium"); err != nil {
    if mkErr := os.MkdirAll("/run/cilium", 0755); mkErr != nil {
        return fmt.Errorf("/run/cilium not creatable, cgroupv2 unit build would fail: %v", mkErr)
    }
}

if err := b.buildCgroup2Mount(c); err != nil {
    klog.Errorf("cgroupv2 mount unit creation failed: %v", err)
    return fmt.Errorf("failed to create cgroupv2 mount unit: %w", err)
}

When it happens

Trigger: buildCgroup2Mount(c) returns an error during nodeup Build with Cilium enabled — practically unix.Statfs on the cgroup path failing with an error other than NotExist (see error 718), or a task-add failure.

Common situations: cgroupfs2 misconfigured on the host image; permission problems creating /run/cilium/cgroupv2; unusual distributions where /run is read-only at nodeup time.

Related errors

• failed to create bpf mount unit: %w
• error checking for /run/cilium/cgroupv2: %v
• error building kubelet flags: %v
• error checking for /sys/fs/bpf: %v
• failed to ensure the directory: %s, error: %w

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/895911a36229f714. Report an issue: GitHub.