config-linux: add more info about hugetlb page size

Currently the docs don't say anything about what the "pageSize" is other than the fact that it is a string. This makes it easier for developers to understand how it works, and may help avoiding mistakes which are hard to spot. Signed-off-by: Odin Ugedal <[email protected]>
opencontainers · Jun 3, 2019 · fa389cb · fa389cb
1 parent 5b71a03
commit fa389cb
Show file tree

Hide file tree

Showing 6 changed files with 33 additions and 1 deletion.
diff --git a/config-linux.md b/config-linux.md
@@ -394,6 +394,8 @@ For more information, see the kernel cgroups documentation about [HugeTLB][cgrou
 Each entry has the following structure:
 
 * **`pageSize`** *(string, REQUIRED)* - hugepage size
+    The value has the format "<size><unit-prefix>B" (64KB, 2MB, 1GB), and must match the <hugepagesize> of the
+    corresponding control file found in "/sys/fs/cgroup/hugetlb/hugetlb.<hugepagesize>.max_usage_in_bytes"
 * **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage
 
 #### Example
@@ -403,6 +405,10 @@ Each entry has the following structure:
         {
             "pageSize": "2MB",
             "limit": 209715200
+        },
+        {
+            "pageSize": "64KB",
+            "limit": 1000000
         }
    ]
 ```

diff --git a/config.md b/config.md
@@ -710,6 +710,10 @@ Here is a full example `config.json` for reference.
                 {
                     "pageSize": "2MB",
                     "limit": 9223372036854772000
+                },
+                {
+                    "pageSize": "64KB",
+                    "limit": 1000000
                 }
             ],
             "memory": {

diff --git a/schema/config-linux.json b/schema/config-linux.json
@@ -124,7 +124,8 @@
                             "type": "object",
                             "properties": {
                                 "pageSize": {
-                                    "type": "string"
+                                    "type": "string",
+                                    "pattern": "^[1-9][0-9]*[KMG]B$"
                                 },
                                 "limit": {
                                     "$ref": "defs.json#/definitions/uint64"

diff --git a/schema/test/config/bad/linux-hugepage.json b/schema/test/config/bad/linux-hugepage.json
@@ -0,0 +1,16 @@
+{
+    "ociVersion": "1.0.0",
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "resources": {
+            "hugepageLimits": [
+                {
+                    "limit": 1234123,
+                    "pageSize": "64kB"
+                }
+            ]
+        }
+    }
+}
diff --git a/schema/test/config/good/spec-example.json b/schema/test/config/good/spec-example.json
@@ -232,6 +232,10 @@
                 {
                     "pageSize": "2MB",
                     "limit": 9223372036854772000
+                },
+                {
+                    "pageSize": "64KB",
+                    "limit": 1000000
                 }
             ],
             "oomScoreAdj": 100,

diff --git a/specs-go/config.go b/specs-go/config.go
@@ -219,6 +219,7 @@ type POSIXRlimit struct {
 // LinuxHugepageLimit structure corresponds to limiting kernel hugepages
 type LinuxHugepageLimit struct {
 	// Pagesize is the hugepage size
+	// Format: "<size><unit-prefix>B' (e.g. 64KB, 2MB, 1GB, etc.)
 	Pagesize string `json:"pageSize"`
 	// Limit is the limit of "hugepagesize" hugetlb usage
 	Limit uint64 `json:"limit"`