Add healthcheck start-interval option (#848)

changelogs/fragments/848-docker_api-healthcheck-start-interval.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - docker_container - adds ``healthcheck.start_interval`` to support healthcheck start interval setting on containers (https://github.com/ansible-collections/community.docker/pull/848).

plugins/module_utils/module_container/base.py

@@ -938,6 +938,7 @@ OPTION_HEALTHCHECK = (
         interval=dict(type='str'),
         timeout=dict(type='str'),
         start_period=dict(type='str'),
+        start_interval=dict(type='str'),
         retries=dict(type='int'),
     ))
 )

plugins/module_utils/module_container/docker_api.py

@@ -436,6 +436,7 @@ class DockerAPIEngine(Engine):
         min_api_version=None,
         preprocess_value=None,
         update_parameter=None,
+        extra_option_minimal_versions=None,
     ):
         def preprocess_value_(module, client, api_version, options, values):
             if len(options) != 1:
@@ -499,6 +500,7 @@ class DockerAPIEngine(Engine):
             set_value=set_value,
             min_api_version=min_api_version,
             update_value=update_value,
+            extra_option_minimal_versions=extra_option_minimal_versions,
         )
 
     @classmethod
@@ -512,6 +514,7 @@ class DockerAPIEngine(Engine):
         min_api_version=None,
         preprocess_value=None,
         update_parameter=None,
+        extra_option_minimal_versions=None,
     ):
         def preprocess_value_(module, client, api_version, options, values):
             if len(options) != 1:
@@ -577,6 +580,7 @@ class DockerAPIEngine(Engine):
             set_value=set_value,
             min_api_version=min_api_version,
             update_value=update_value,
+            extra_option_minimal_versions=extra_option_minimal_versions,
         )
 
 
@@ -751,6 +755,7 @@ def _preprocess_healthcheck(module, client, api_version, value):
         'Interval': value.get('interval'),
         'Timeout': value.get('timeout'),
         'StartPeriod': value.get('start_period'),
+        'StartInterval': value.get('start_interval'),
         'Retries': value.get('retries'),
     })
 
@@ -1300,7 +1305,16 @@ OPTION_ETC_HOSTS.add_engine('docker_api', DockerAPIEngine.host_config_value('Ext
 OPTION_GROUPS.add_engine('docker_api', DockerAPIEngine.host_config_value('GroupAdd'))
 
 OPTION_HEALTHCHECK.add_engine('docker_api', DockerAPIEngine.config_value(
-    'Healthcheck', preprocess_value=_preprocess_healthcheck, postprocess_for_get=_postprocess_healthcheck_get_value))
+    'Healthcheck',
+    preprocess_value=_preprocess_healthcheck,
+    postprocess_for_get=_postprocess_healthcheck_get_value,
+    extra_option_minimal_versions={
+        'healthcheck.start_interval': {
+            'docker_api_version': '1.44',
+            'detect_usage': lambda c: c.module.params['healthcheck'] and c.module.params['healthcheck']['start_interval'] is not None,
+        },
+    },
+))
 
 OPTION_HOSTNAME.add_engine('docker_api', DockerAPIEngine.config_value('Hostname'))
 

plugins/module_utils/util.py

@@ -348,9 +348,9 @@ def normalize_healthcheck(healthcheck, normalize_test=False):
     result = dict()
 
     # All supported healthcheck parameters
-    options = ('test', 'interval', 'timeout', 'start_period', 'retries')
+    options = ('test', 'interval', 'timeout', 'start_period', 'start_interval', 'retries')
 
-    duration_options = ('interval', 'timeout', 'start_period')
+    duration_options = ('interval', 'timeout', 'start_period', 'start_interval')
 
     for key in options:
         if key in healthcheck:

plugins/modules/docker_container.py

@@ -369,7 +369,7 @@ options:
       - Configure a check that is run to determine whether or not containers for this service are "healthy".
       - "See the docs for the L(HEALTHCHECK Dockerfile instruction,https://docs.docker.com/engine/reference/builder/#healthcheck)
         for details on how healthchecks work."
-      - "O(healthcheck.interval), O(healthcheck.timeout) and O(healthcheck.start_period) are specified as durations.
+      - "O(healthcheck.interval), O(healthcheck.timeout), O(healthcheck.start_period), and O(healthcheck.start_interval) are specified as durations.
         They accept duration as a string in a format that look like: V(5h34m56s), V(1m30s), and so on.
         The supported units are V(us), V(ms), V(s), V(m) and V(h)."
     type: dict
@@ -399,6 +399,12 @@ options:
           - Start period for the container to initialize before starting health-retries countdown.
           - The default used by the Docker daemon is V(0s).
         type: str
+      start_interval:
+        description:
+          - Time between health checks during the start period. This option requires Docker Engine version 25.0 or later.
+          - The default used by the Docker daemon is V(5s).
+        type: str
+        version_added: 3.10.0
   hostname:
     description:
       - The container's hostname.
@@ -1196,6 +1202,7 @@ EXAMPLES = '''
       timeout: 10s
       retries: 3
       start_period: 30s
+      start_interval: 10s
 
 - name: Remove healthcheck from container
   community.docker.docker_container: