Improve docs sharing for docker_compose_v2* modules; fix examples and return docs for docker_compose_v2_pull (#761)

* Move more common documentation to docs fragment. * Fix examples and return values for docker_compose_v2_pull. * Remove ignore.
2025-12-15 19:42:06 +00:00 · 2024-01-17 07:53:44 +01:00 · 2024-01-17 07:53:44 +01:00 · 6082efc855
commit 6082efc855
parent 22d956efa8
5 changed files with 29 additions and 251 deletions
--- a/plugins/doc_fragments/compose_v2.py
+++ b/plugins/doc_fragments/compose_v2.py
@ -35,4 +35,19 @@ options:
          - Equivalent to C(docker compose --profile).
        type: list
        elements: str
+notes:
+  - |-
+    The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
+    and for the main operations also no machine friendly output format. The module tries to accomodate this with various
+    version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
+
+    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
+    will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
+'''
+
+    # The following needs to be kept in sync with the compose_v2 module utils
+    MINIMUM_VERSION = r'''
+options: {}
+requirements:
+  - "Docker CLI with Docker compose plugin 2.18.0 or later"
 '''
--- a/plugins/module_utils/compose_v2.py
+++ b/plugins/module_utils/compose_v2.py
@ -166,6 +166,9 @@ _RE_SKIPPED_EVENT = re.compile(
    r'$'
 )

+# The following needs to be kept in sync with the MINIMUM_VERSION compose_v2 docs fragment
+MINIMUM_COMPOSE_VERSION = '2.18.0'
+

 def _extract_event(line):
    match = _RE_RESOURCE_EVENT.match(line)
@ -410,7 +413,7 @@ def combine_text_output(*outputs):


 class BaseComposeManager(DockerBaseClass):
-    def __init__(self, client, min_version='2.18.0'):
+    def __init__(self, client, min_version=MINIMUM_COMPOSE_VERSION):
        super(BaseComposeManager, self).__init__()
        self.client = client
        self.check_mode = self.client.check_mode
--- a/plugins/modules/docker_compose_v2.py
+++ b/plugins/modules/docker_compose_v2.py
@ -23,6 +23,7 @@ description:

 extends_documentation_fragment:
  - community.docker.compose_v2
+  - community.docker.compose_v2.minimum_version
  - community.docker.docker.cli_documentation
  - community.docker.attributes
  - community.docker.attributes.actiongroup_docker
@ -117,23 +118,12 @@ options:
    type: list
    elements: str

-requirements:
-  - "Docker CLI with Docker compose plugin 2.18.0 or later"
-
 author:
  - Felix Fontein (@felixfontein)

-notes:
-  - |-
-    The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
-    and for the main operations also no machine friendly output format. The module tries to accomodate this with various
-    version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
-
-    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
-    will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
-
 seealso:
  - module: community.docker.docker_compose
+  - module: community.docker.docker_compose_v2_pull
 '''

 EXAMPLES = '''
@ -400,12 +390,9 @@ from ansible_collections.community.docker.plugins.module_utils.compose_v2 import
 )


-DOCKER_COMPOSE_MINIMAL_VERSION = '2.18.0'
-
-
 class ServicesManager(BaseComposeManager):
    def __init__(self, client):
-        super(ServicesManager, self).__init__(client, min_version=DOCKER_COMPOSE_MINIMAL_VERSION)
+        super(ServicesManager, self).__init__(client)
        parameters = self.client.module.params

        self.state = parameters['state']
--- a/plugins/modules/docker_compose_v2_pull.py
+++ b/plugins/modules/docker_compose_v2_pull.py
@ -21,6 +21,7 @@ description:

 extends_documentation_fragment:
  - community.docker.compose_v2
+  - community.docker.compose_v2.minimum_version
  - community.docker.docker.cli_documentation
  - community.docker.attributes
  - community.docker.attributes.actiongroup_docker
@ -43,232 +44,20 @@ options:
      - missing
    default: always

-requirements:
-  - "Docker CLI with Docker compose plugin 2.18.0 or later"
-
 author:
  - Felix Fontein (@felixfontein)

-notes:
-  - |-
-    The Docker compose CLI plugin has no stable output format (see for example U(https://github.com/docker/compose/issues/10872)),
-    and for the main operations also no machine friendly output format. The module tries to accomodate this with various
-    version-dependent behavior adjustments and with testing older and newer versions of the Docker compose CLI plugin.
-
-    Currently the module is tested with multiple plugin versions between 2.18.1 and 2.23.3. The exact list of plugin versions
-    will change over time. New releases of the Docker compose CLI plugin can break this module at any time.
-
 seealso:
-  - module: community.docker.docker_compose
+  - module: community.docker.docker_compose_v2
 '''

 EXAMPLES = '''
-# Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the
-# flask directory
-
- name: Run using a project directory
-  hosts: localhost
-  gather_facts: false
-  tasks:
-    - name: Tear down existing services
-      community.docker.docker_compose_v2:
-        project_src: flask
-        state: absent
-
-    - name: Create and start services
-      community.docker.docker_compose_v2:
-        project_src: flask
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - name: Run `docker-compose up` again
-      community.docker.docker_compose_v2:
-        project_src: flask
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - ansible.builtin.assert:
-        that: not output.changed
-
-    - name: Stop all services
-      community.docker.docker_compose_v2:
-        project_src: flask
-        state: stopped
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - name: Verify that web and db services are not running
-      ansible.builtin.assert:
-        that:
-          - "not output.services.web.flask_web_1.state.running"
-          - "not output.services.db.flask_db_1.state.running"
-
-    - name: Restart services
-      community.docker.docker_compose_v2:
-        project_src: flask
-        state: restarted
-      register: output
-
-    - name: Show results
-      ansible.builtin.debug:
-        var: output
-
-    - name: Verify that web and db services are running
-      ansible.builtin.assert:
-        that:
-          - "output.services.web.flask_web_1.state.running"
-          - "output.services.db.flask_db_1.state.running"
+- name: Pull images for flask project
+  community.docker.docker_compose_v2_pull:
+    project_src: /path/to/flask
 '''

 RETURN = '''
-containers:
-  description:
-    - A list of containers associated to the service.
-  returned: success
-  type: list
-  elements: dict
-  contains:
-    Command:
-      description:
-        - The container's command.
-      type: raw
-    CreatedAt:
-      description:
-        - The timestamp when the container was created.
-      type: str
-      sample: "2024-01-02 12:20:41 +0100 CET"
-    ExitCode:
-      description:
-        - The container's exit code.
-      type: int
-    Health:
-      description:
-        - The container's health check.
-      type: raw
-    ID:
-      description:
-        - The container's ID.
-      type: str
-      sample: "44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135"
-    Image:
-      description:
-        - The container's image.
-      type: str
-    Labels:
-      description:
-        - Labels for this container.
-      type: dict
-    LocalVolumes:
-      description:
-        - The local volumes count.
-      type: str
-    Mounts:
-      description:
-        - Mounts.
-      type: str
-    Name:
-      description:
-        - The container's primary name.
-      type: str
-    Names:
-      description:
-        - List of names of the container.
-      type: list
-      elements: str
-    Networks:
-      description:
-        - List of networks attached to this container.
-      type: list
-      elements: str
-    Ports:
-      description:
-        - List of port assignments as a string.
-      type: str
-    Publishers:
-      description:
-        - List of port assigments.
-      type: list
-      elements: dict
-      contains:
-        URL:
-          description:
-            - Interface the port is bound to.
-          type: str
-        TargetPort:
-          description:
-            - The container's port the published port maps to.
-          type: int
-        PublishedPort:
-          description:
-            - The port that is published.
-          type: int
-        Protocol:
-          description:
-            - The protocol.
-          type: str
-          choices:
-            - tcp
-            - udp
-    RunningFor:
-      description:
-        - Amount of time the container runs.
-      type: str
-    Service:
-      description:
-        - The name of the service.
-      type: str
-    Size:
-      description:
-        - The container's size.
-      type: str
-      sample: "0B"
-    State:
-      description:
-        - The container's state.
-      type: str
-      sample: running
-    Status:
-      description:
-        - The container's status.
-      type: str
-      sample: Up About a minute
-images:
-  description:
-    - A list of images associated to the service.
-  returned: success
-  type: list
-  elements: dict
-  contains:
-    ID:
-      description:
-        - The image's ID.
-      type: str
-      sample: sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1
-    ContainerName:
-      description:
-        - Name of the conainer this image is used by.
-      type: str
-    Repository:
-      description:
-        - The repository where this image belongs to.
-      type: str
-    Tag:
-      description:
-        - The tag of the image.
-      type: str
-    Size:
-      description:
-        - The image's size in bytes.
-      type: int
 actions:
  description:
    - A list of actions that have been applied.
@ -282,12 +71,8 @@ actions:
      type: str
      sample: container
      choices:
-        - container
        - image
-        - network
-        - service
        - unknown
-        - volume
    id:
      description:
        - The ID of the resource that was changed.
@ -297,16 +82,8 @@ actions:
      description:
        - The status change that happened.
      type: str
-      sample: Creating
+      sample: Pulling
      choices:
-        - Starting
-        - Exiting
-        - Restarting
-        - Creating
-        - Stopping
-        - Killing
-        - Removing
-        - Recreating
        - Pulling
 '''

@ -327,12 +104,9 @@ from ansible_collections.community.docker.plugins.module_utils.compose_v2 import
 from ansible_collections.community.docker.plugins.module_utils.version import LooseVersion


-DOCKER_COMPOSE_MINIMAL_VERSION = '2.18.0'
-
-
 class PullManager(BaseComposeManager):
    def __init__(self, client):
-        super(PullManager, self).__init__(client, min_version=DOCKER_COMPOSE_MINIMAL_VERSION)
+        super(PullManager, self).__init__(client)
        parameters = self.client.module.params

        self.policy = parameters['policy']
--- a/tests/sanity/ignore-2.13.txt
+++ b/tests/sanity/ignore-2.13.txt
@ -1,4 +1,3 @@
 .azure-pipelines/scripts/publish-codecov.py replace-urlopen
 plugins/modules/docker_compose_v2.py validate-modules:return-syntax-error
-plugins/modules/docker_compose_v2_pull.py validate-modules:return-syntax-error
 plugins/modules/docker_container_copy_into.py validate-modules:undocumented-parameter # _max_file_size_for_diff is used by the action plugin