Merge pull request #1620 from docker/healthcheck-start-period

Add support for start_period in Healthcheck spec

Author: shin-

docker/api/container.py

@@ -418,6 +418,8 @@ def create_container(self, image, command=None, hostname=None, user=None,
             networking_config (dict): A networking configuration generated
                 by :py:meth:`create_networking_config`.
             runtime (str): Runtime to use with this container.
+            healthcheck (dict): Specify a test to perform to check that the
+                container is healthy.
 
         Returns:
             A dictionary with an image 'Id' key and a 'Warnings' key.

docker/models/containers.py

@@ -516,6 +516,8 @@ def run(self, image, command=None, stdout=True, stderr=False,
                 container, as a mapping of hostname to IP address.
             group_add (:py:class:`list`): List of additional group names and/or
                 IDs that the container process will run as.
+            healthcheck (dict): Specify a test to perform to check that the
+                container is healthy.
             hostname (str): Optional hostname for the container.
             init (bool): Run an init inside the container that forwards
                 signals and reaps processes

docker/types/containers.py

@@ -565,10 +565,17 @@ def __init__(
                 'stop_timeout was only introduced in API version 1.25'
             )
 
-        if healthcheck is not None and version_lt(version, '1.24'):
-            raise errors.InvalidVersion(
-                'Health options were only introduced in API version 1.24'
-            )
+        if healthcheck is not None:
+            if version_lt(version, '1.24'):
+                raise errors.InvalidVersion(
+                    'Health options were only introduced in API version 1.24'
+                )
+
+            if version_lt(version, '1.29') and 'StartPeriod' in healthcheck:
+                raise errors.InvalidVersion(
+                    'healthcheck start period was introduced in API '
+                    'version 1.29'
+                )
 
         if isinstance(command, six.string_types):
             command = split_command(command)

docker/types/healthcheck.py

@@ -12,12 +12,14 @@ def __init__(self, **kwargs):
         interval = kwargs.get('interval', kwargs.get('Interval'))
         timeout = kwargs.get('timeout', kwargs.get('Timeout'))
         retries = kwargs.get('retries', kwargs.get('Retries'))
+        start_period = kwargs.get('start_period', kwargs.get('StartPeriod'))
 
         super(Healthcheck, self).__init__({
             'Test': test,
             'Interval': interval,
             'Timeout': timeout,
-            'Retries': retries
+            'Retries': retries,
+            'StartPeriod': start_period
         })
 
     @property
@@ -51,3 +53,11 @@ def retries(self):
     @retries.setter
     def retries(self, value):
         self['Retries'] = value
+
+    @property
+    def start_period(self):
+        return self['StartPeriod']
+
+    @start_period.setter
+    def start_period(self, value):
+        self['StartPeriod'] = value

tests/integration/api_healthcheck_test.py

@@ -28,8 +28,8 @@ def test_healthcheck_passes(self):
         container = self.client.create_container(
             BUSYBOX, 'top', healthcheck=dict(
                 test="true",
-                interval=1*SECOND,
-                timeout=1*SECOND,
+                interval=1 * SECOND,
+                timeout=1 * SECOND,
                 retries=1,
             ))
         self.tmp_containers.append(container)
@@ -41,10 +41,27 @@ def test_healthcheck_fails(self):
         container = self.client.create_container(
             BUSYBOX, 'top', healthcheck=dict(
                 test="false",
-                interval=1*SECOND,
-                timeout=1*SECOND,
+                interval=1 * SECOND,
+                timeout=1 * SECOND,
                 retries=1,
             ))
         self.tmp_containers.append(container)
         self.client.start(container)
         wait_on_health_status(self.client, container, "unhealthy")
+
+    @helpers.requires_api_version('1.29')
+    def test_healthcheck_start_period(self):
+        container = self.client.create_container(
+            BUSYBOX, 'top', healthcheck=dict(
+                test="echo 'x' >> /counter.txt && "
+                     "test `cat /counter.txt | wc -l` -ge 3",
+                interval=1 * SECOND,
+                timeout=1 * SECOND,
+                retries=1,
+                start_period=3 * SECOND
+            )
+        )
+
+        self.tmp_containers.append(container)
+        self.client.start(container)
+        wait_on_health_status(self.client, container, "healthy")