feat: support cpuperiod and cpuquota build arguments (Docker v1.19+)

Add support for the new container limits introduced in Docker v1.19
for restricting cpu usage during build.

See https://docs.docker.com/engine/api/version-history/#v119-api-changes

Signed-off-by: Lucy Linder <[email protected]>

Author: derlin

docker/api/build.py

@@ -83,6 +83,10 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
                 - cpushares (int): CPU shares (relative weight)
                 - cpusetcpus (str): CPUs in which to allow execution, e.g.,
                     ``"0-3"``, ``"0,1"``
+                - cpuperiod (int): (Docker API v1.19+) The length of a CPU
+                    period in microseconds
+                - cpuquota (int): (Docker API v1.19+) Microseconds of CPU
+                    time that the container can get in a CPU period
             decode (bool): If set to ``True``, the returned stream will be
                 decoded into dicts on the fly. Default ``False``
             shmsize (int): Size of `/dev/shm` in bytes. The size must be
@@ -135,6 +139,13 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
                 raise errors.DockerException(
                     f"invalid tag '{tag}': invalid reference format"
                 )
+            introduced_in = constants.CONTAINER_LIMITS_KEYS[key]
+            if introduced_in is not None:
+                if utils.version_lt(self._version, introduced_in):
+                    raise errors.InvalidVersion(
+                        f"container limit '{key}' was only introduced"
+                        f" in API version {introduced_in}"
+                    )
         if custom_context:
             if not fileobj:
                 raise TypeError("You must specify fileobj with custom_context")

docker/constants.py

@@ -6,9 +6,14 @@
 MINIMUM_DOCKER_API_VERSION = '1.24'
 DEFAULT_TIMEOUT_SECONDS = 60
 STREAM_HEADER_SIZE_BYTES = 8
-CONTAINER_LIMITS_KEYS = [
-    'memory', 'memswap', 'cpushares', 'cpusetcpus'
-]
+CONTAINER_LIMITS_KEYS = {
+    'memory': None,
+    'memswap': None,
+    'cpushares': None,
+    'cpusetcpus': None,
+    'cpuperiod': "1.19",
+    'cpuquota': "1.19",
+}
 
 DEFAULT_HTTP_HOST = "127.0.0.1"
 DEFAULT_UNIX_SOCKET = "http+unix:///var/run/docker.sock"

docker/models/images.py

@@ -259,6 +259,10 @@ def build(self, **kwargs):
                 - cpushares (int): CPU shares (relative weight)
                 - cpusetcpus (str): CPUs in which to allow execution, e.g.,
                     ``"0-3"``, ``"0,1"``
+                - cpuperiod (int): (Docker API v1.19+) The length of a CPU
+                    period in microseconds
+                - cpuquota (int): (Docker API v1.19+) Microseconds of CPU
+                    time that the container can get in a CPU period
             shmsize (int): Size of `/dev/shm` in bytes. The size must be
                 greater than 0. If omitted the system uses 64MB
             labels (dict): A dictionary of labels to set on the image

tests/unit/api_build_test.py

@@ -8,7 +8,7 @@
 from docker import auth, errors
 from docker.api.build import process_dockerfile
 
-from ..helpers import make_tree
+from ..helpers import make_tree, requires_api_version
 from .api_test import BaseAPIClientTest, fake_request, url_prefix
 
 
@@ -133,6 +133,16 @@ def test_build_container_with_container_limits(self):
             },
         )
 
+    @requires_api_version('1.19')
+    def test_build_container_with_container_limits_cpu(self):
+        self.client.build(
+            ".",
+            container_limits={
+                "cpuquota": 50000,
+                "cpuperiod": 100000,
+            },
+        )
+
     def test_build_container_invalid_container_limits(self):
         with pytest.raises(docker.errors.DockerException):
             self.client.build(".", container_limits={"foo": "bar"})