Add cgroup v2 support while maintaining v1 compatibility by jiechen0826 · Pull Request #2632 · microsoft/hcsshim

jiechen0826 · 2026-03-17T18:01:10Z

This pull request introduces comprehensive improvements to cgroup (control group) initialization and management, especially around supporting both cgroup v1 and v2, and adds extensive testing for cgroup resource handling and memory event monitoring. It also updates several dependencies to newer versions for improved compatibility and stability.

Cgroup Initialization and Detection Improvements:

Refactored init/init.c to robustly detect and initialize cgroup v1 or v2 at boot. The system now checks for kernel parameters disabling cgroup v2, attempts a test mount to verify v2 availability, and mounts tmpfs for v1 only if needed. This ensures correct cgroup setup based on the environment, with improved logging for troubleshooting.

Cross-distribution compatibility:

Automatic cgroup version detection: The implementation tests cgroup v2 availability by attempting a test mount and checking for controllers
- Yocto: Uses cgroup v1 due to kernel configuration (v2 not available)
- Azure Linux: Uses cgroup v2 if available and working, otherwise falls back to v1
- Ubuntu: Uses cgroup v2 (available and working by default)
Kernel parameter override: All distributions can use cgroup_no_v2=all kernel parameter to force cgroup v1 usage, which is properly detected and respected
The implementation provides automatic fallback from v2 to v1 when v2 is unavailable, disabled, or non-functional, ensuring compatibility across all supported distributions without requiring distribution-specific code paths

Testing Enhancements for Cgroup Management:

Added cmd/gcs/cgroup_manager_test.go with tests covering interface compatibility, resource conversion, cgroup version detection, error handling for invalid paths and permissions, and edge cases for resource limits and stats conversion.
Added cmd/gcs/memory_event_test.go with tests for cgroup v2 memory event monitoring, OOM event file descriptors, memory threshold detection, error handling, and resource creation scenarios.

Dependency and Compatibility Updates:

Updated go.mod to newer versions of several dependencies, including containerd/cgroups, containerd/containerd, opencontainers/runtime-spec, urfave/cli/v2, and others, improving compatibility with recent upstream changes and bug fixes.
Added cgroup v2 imports to internal/guest/runtime/hcsv2/container.go to support the new functionality.

Other Codebase Improvements:

Included missing header <dirent.h> in init/init.c for directory operations.
Added forward declarations and improved code organization in init/init.c for better maintainability.

These changes collectively improve the reliability and test coverage of cgroup management, ensure compatibility with modern Linux systems, and lay the groundwork for future enhancements.

helsaawy · 2026-03-17T19:55:31Z

tools.go

we already have these in go.mod via tool directives.
also, why do we need the "github.com/containerd/containerd/v2/pkg/oci" import? it doest look like its being used anywhere

helsaawy · 2026-03-17T20:04:23Z

cmd/gcs/cgroup_manager_test.go

+func TestCgroupManagerInterface_Compatibility(t *testing.T) {
+	// Test that both managers implement the CgroupManager interface
+	var v1mgr CgroupManager = &V1Manager{}
+	var v2mgr CgroupManager = &V2Manager{path: "/test/path"}
+
+	// Test that both managers implement the interface
+	_ = v1mgr
+	_ = v2mgr
+}


in main.go:

var _ CgroupManager = &V1Manager{} var _ CgroupManager = &V2Manager{}

helsaawy · 2026-03-17T20:05:47Z

cmd/gcs/main.go

+	return false
+}
+
+// CgroupManager provides a unified interface for cgroup v1 and v2 operations


probably best to move the CgroupManager code to internal/guest/cgroup (or something similarly named)

helsaawy · 2026-03-17T20:14:38Z

init/init.c

+}
+
+// Try mounting cgroup v2 to see if it works
+bool is_cgroup_v2_available() {


Suggested change

bool is_cgroup_v2_available() {

bool try_init_cgroups_v2() {

so that way we can remove void init_cgroups_v2()

helsaawy · 2026-03-17T20:19:04Z

init/init.c

 #ifdef DEBUG
    printf("init_cgroups\n");
 #endif
+    dmesgInfo("Microsoft.hcsshim init: cgroup migration version starting\n");


is this log needed? we already get cgroup info from init_cgroups

helsaawy · 2026-03-17T20:20:56Z

cmd/gcs/main.go

+func isCgroupV2() bool {
+	// Check if cgroup v2 was disabled via kernel parameter
+	if isCgroupV2DisabledByKernel() {
+		return false
+	}
+
+	_, err := os.Stat("/sys/fs/cgroup/cgroup.controllers")
+	return err == nil
+}


semiduplicated by isCgroupV2 in internal/guest/runtime/hcsv2/container.go

helsaawy · 2026-03-17T20:24:14Z

cmd/gcs/main.go

+}
+
+// convertV2StatsToV1Stats converts cgroup v2 stats to v1 stats format
+func convertV2StatsToV1Stats(v2Stats *cgroups2stats.Metrics) *cgroups1stats.Metrics {


(semi?) duplicated by convertV2StatsToV1 in internal/guest/runtime/hcsv2/container.go

helsaawy · 2026-03-17T20:33:08Z

internal/guest/runtime/hcsv2/uvm.go

 	NetworkNamespace string
 	CgroupPath       string
-	CgroupControl    cgroups.Cgroup
+	CgroupControl    interface{}     // Can be either cgroups.Cgroup (v1) or *cgroups2.Manager (v2)


we already have the CgroupManager defined in cmd/gcs/main.go (which we probably should extract and move elsewhere)
can we just rely on that here and for virtualPodsCgroupParent so we dont need to recreate and reimplement all the same manager creation and stat code?

helsaawy · 2026-03-17T20:35:27Z

cmd/gcs/main.go

+	_, err := os.Stat("/sys/fs/cgroup/cgroup.controllers")
+	return err == nil


"github.com/containerd/cgroups/v3".Mode() == "github.com/containerd/cgroups/v3".Unified
(probably also want to return true for hybrid cgroup mode)

- Change go:generate from 'go tool' to 'go run' syntax for mkwinsyscall calls - This fixes CI failures in the 'go-gen' job where external tools cannot be invoked with 'go tool' syntax - All mkwinsyscall calls now use proper 'go run' syntax that works with vendored dependencies - Addresses PR microsoft#2632 CI pipeline failures Files updated: - computestorage/storage.go - hcn/hcn.go - hcsshim.go - internal/hns/hns.go - internal/interop/interop.go - internal/regstate/regstate.go

cmd/containerd-shim-runhcs-v1/options/runhcs.pb.go

jiechen0826 requested a review from a team as a code owner March 17, 2026 18:01

msscotb assigned msscotb and anmaxvl Mar 17, 2026

helsaawy requested changes Mar 17, 2026

View reviewed changes

jiechen0826 force-pushed the cgroup-v2-clean branch from 3e6e5cd to 9f85d63 Compare March 18, 2026 22:35

anmaxvl reviewed Mar 19, 2026

View reviewed changes

cmd/containerd-shim-runhcs-v1/options/runhcs.pb.go Outdated Show resolved Hide resolved

jiechen0826 force-pushed the cgroup-v2-clean branch from da130ab to c51e88a Compare March 19, 2026 21:34

jiechen0826 added 3 commits March 19, 2026 14:50

add support for cgroup v1/v2 dual compatibility

0411626

add unit tests for cgroup

956584a

update go mod dependencies

fb65d11

jiechen0826 force-pushed the cgroup-v2-clean branch from c51e88a to fb65d11 Compare March 19, 2026 22:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add cgroup v2 support while maintaining v1 compatibility#2632

Add cgroup v2 support while maintaining v1 compatibility#2632
jiechen0826 wants to merge 3 commits intomicrosoft:mainfrom
jiechen0826:cgroup-v2-clean

jiechen0826 commented Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

helsaawy Mar 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		_, err := os.Stat("/sys/fs/cgroup/cgroup.controllers")
		return err == nil

Conversation

jiechen0826 commented Mar 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants