Fix parsing of hugetlb.<size>.events files

[voidbar]

Fixes #378

According to the docs:

hugetlb.<hugepagesize>.events
A read-only flat-keyed file which exists on non-root cgroups.

max
   The number of allocation failure due to HugeTLB limit

[akhilerm]

@voidbar You can refer https://github.com/containerd/project/blob/main/CONTRIBUTING.md#sign-your-work to add the DCO to fix the Project Checks failure

[voidbar]

@akhilerm done

[akhilerm]

/cc @dcantah

[thaJeztah]

Should this fail hard if the file doesn't exist, or ignore non-existing (os.IsNotExist(err)) ? (Not sure if it's guaranteed to exist?)

[voidbar]

From the docs it can be absent
A read-only flat-keyed file which **exists on non-root** cgroups.
we can wrap this logic in existence check and fail hard in case we failed to parse it

[thaJeztah]

Yes, it looks like getStatFileContentUint64 (used for non-KV-files) is fairly relaxed on errors, and at most logs an error;

cgroups/cgroup2/utils.go

Lines 266 to 293 in f1e92d8

	// Gets uint64 parsed content of single value cgroup stat file
	func getStatFileContentUint64(filePath string) uint64 {
	f, err := os.Open(filePath)
	if err != nil {
	return 0
	}
	defer f.Close()
	// We expect an unsigned 64 bit integer, or a "max" string
	// in some cases.
	buf := make([]byte, 32)
	n, err := f.Read(buf)
	if err != nil {
	return 0
	}
	trimmed := strings.TrimSpace(string(buf[:n]))
	if trimmed == "max" {
	return math.MaxUint64
	}
	res, err := parseUint(trimmed, 10, 64)
	if err != nil {
	log.L.Errorf("unable to parse %q as a uint from Cgroup file %q", trimmed, filePath)
	return res
	}
	return res

To keep aligned with that behavior, perhaps a getKVStatsFileContentUint64 utility that handles things similarly would make sense; it could get the name of the property looked for ("max") passed as an argument, which would allow returning early (instead of reading all properties potentialy present in the file);

// Gets uint64 parsed content of key-value cgroup stat file
func getKVStatsFileContentUint64(filePath string, propertyName string) uint64 {
	f, err := os.Open(filepath.Join(path, file))
	if err != nil {
		return 0
	}
	defer f.Close()

	s := bufio.NewScanner(f)
	for s.Scan() {
		name, value, err := parseKV(s.Text())
		if name == propertyName {
			if err != nil {
				log.L.Errorf("unable to parse %q as a uint from Cgroup file %q: %w", propertyName, filePath, err)
				return 0
			}
			return value
		}
	}
	return s.Err()
}

Perhaps a log for failing to open the file for reasons other than the file not being found would be good (the above was based on the getStatFileContentUint64 code, which doesn't do so, but ... maybe should?).

Do we know if these KV-files could also have magic values (like max)? I see the other utility has some special handling for that before attempting to parse it as an uint;

cgroups/cgroup2/utils.go

Lines 282 to 288 in f1e92d8

	trimmed := strings.TrimSpace(string(buf[:n]))
	if trimmed == "max" {
	return math.MaxUint64
	}
	res, err := parseUint(trimmed, 10, 64)
	if err != nil {

[ningmingxiao]

hugetlb..max
Set/show the hard limit of “hugepagesize” hugetlb usage. The default value is “max”. It exists for all the cgroup except root.
the max value is used for hugetlb..max file @thaJeztah

[ningmingxiao]

we can refer https://github.com/opencontainers/cgroups/blob/v0.0.6/fs2/hugetlb.go#L60

[voidbar]

I implemented a simple getKVStatsFileContentUint64. I think it strikes the balance between being too strict and too lenient. It follows the same assumptions as getStatsFileContentUint64 and provides only the value required.

[voidbar]

@akhilerm @thaJeztah can we take this to main?

[AkihiroSuda]

Thanks

[Charlesm54]

Why do I have still this issue on my Ubuntu server.
Running this on zimaboard with runtipi dashboard...
My Proxmox servers are not affected...only my server on zimaboard.

Client: Docker
Version:
Engine - Community
API version:
29.1.2
Go version:
1.52
Git commit:
g01.25.5
890dcca
Tue Dec
Built:
2 21:55:19
2025
OS/Arch:
linux/amd64
Context:
default
Engine:
Server: Docker Engine - Community
Version:
API version:
Go version:
Git commit:
29.1.2
1.52 (minimum
go1 .25.5
de45c2a
Tue Dec 2 21:55:19
linux/amd64
false
version
1.24)
Built:
OS/Arch:
2025
Experimental:
containerd:
Version:
V2.2.0
GitCommit:
1c4457e00facac03ce1d75f7b6777a7a851e5runc:
Version:
GitCommit:
1.3.4
docker-init:
V1.3.4-0-gd6d73eb8
Version:
0.19.0
de40ad0
GitCommit:

[thaJeztah]

@Charlesm54 containerd v2.2.0 does not yet have this fix; it's back ported to be included in a v2.2.1 patch release, but it's not released yet.