community.docker/plugins/modules/docker_stack.py

#!/usr/bin/python

# Copyright (c) 2018 Dario Zanzico (git@dariozanzico.com)
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later

from __future__ import annotations


DOCUMENTATION = r"""
module: docker_stack
author: "Dario Zanzico (@dariko)"
short_description: docker stack module
description:
  - Manage docker stacks using the C(docker stack) command on the target node (see examples).
extends_documentation_fragment:
  - community.docker._docker.cli_documentation
  - community.docker._attributes
  - community.docker._attributes.actiongroup_docker
attributes:
  check_mode:
    support: none
  diff_mode:
    support: none
  action_group:
    version_added: 3.6.0
  idempotent:
    support: full
options:
  name:
    description:
      - Stack name.
    type: str
    required: true
  state:
    description:
      - Service state.
    type: str
    default: "present"
    choices:
      - present
      - absent
  compose:
    description:
      - List of compose definitions. Any element may be a string referring to the path of the compose file on the target host
        or the YAML contents of a compose file nested as dictionary.
    type: list
    elements: raw
    default: []
  prune:
    description:
      - If true will add the C(--prune) option to the C(docker stack deploy) command. This will have docker remove the services
        not present in the current stack definition.
    type: bool
    default: false
  detach:
    description:
      - If V(false), the C(--detach=false) option is added to the C(docker stack deploy) command, allowing Docker to wait
        for tasks to converge before exiting.
      - If V(true) (default), Docker exits immediately instead of waiting for tasks to converge.
    type: bool
    default: true
    version_added: 4.1.0
  with_registry_auth:
    description:
      - If true will add the C(--with-registry-auth) option to the C(docker stack deploy) command. This will have docker send
        registry authentication details to Swarm agents.
    type: bool
    default: false
  resolve_image:
    description:
      - If set will add the C(--resolve-image) option to the C(docker stack deploy) command. This will have docker query the
        registry to resolve image digest and supported platforms. If not set, docker use "always" by default.
    type: str
    choices: ["always", "changed", "never"]
  absent_retries:
    description:
      - If larger than V(0) and O(state=absent) the module will retry up to O(absent_retries) times to delete the stack until
        all the resources have been effectively deleted. If the last try still reports the stack as not completely removed
        the module will fail.
    type: int
    default: 0
  absent_retries_interval:
    description:
      - Interval in seconds between consecutive O(absent_retries).
    type: int
    default: 1
  docker_cli:
    version_added: 3.6.0
  docker_host:
    version_added: 3.6.0
  tls_hostname:
    version_added: 3.6.0
  api_version:
    version_added: 3.6.0
  ca_path:
    version_added: 3.6.0
  client_cert:
    version_added: 3.6.0
  client_key:
    version_added: 3.6.0
  tls:
    version_added: 3.6.0
  validate_certs:
    version_added: 3.6.0
  cli_context:
    version_added: 3.6.0

requirements:
  - Docker CLI tool C(docker)
  - jsondiff
  - pyyaml
"""

RETURN = r"""
stack_spec_diff:
  description: |-
    Dictionary containing the differences between the 'Spec' field
    of the stack services before and after applying the new stack
    definition.
  sample: >
    "stack_spec_diff":
    {'test_stack_test_service': {'TaskTemplate': {'ContainerSpec': {delete: ['Env']}}}}
  returned: on change
  type: dict
"""

EXAMPLES = r"""
---
- name: Deploy stack from a compose file
  community.docker.docker_stack:
    state: present
    name: mystack
    compose:
      - /opt/docker-compose.yml

- name: Deploy stack from base compose file and override the web service
  community.docker.docker_stack:
    state: present
    name: mystack
    compose:
      - /opt/docker-compose.yml
      - version: '3'
        services:
          web:
            image: nginx:latest
            environment:
              ENVVAR: envvar

- name: Remove stack
  community.docker.docker_stack:
    name: mystack
    state: absent
"""


import json
import os
import tempfile
import traceback
import typing as t
from time import sleep

from ansible.module_utils.common.text.converters import to_text

from ansible_collections.community.docker.plugins.module_utils._common_cli import (
    AnsibleModuleDockerClient,
    DockerException,
)


try:
    from jsondiff import diff as json_diff

    HAS_JSONDIFF = True
except ImportError:
    HAS_JSONDIFF = False

try:
    from yaml import dump as yaml_dump

    HAS_YAML = True
except ImportError:
    HAS_YAML = False


def docker_stack_services(
    client: AnsibleModuleDockerClient, stack_name: str
) -> list[str]:
    dummy_rc, out, err = client.call_cli(
        "stack", "services", stack_name, "--format", "{{.Name}}"
    )
    if to_text(err) == f"Nothing found in stack: {stack_name}\n":
        return []
    return to_text(out).strip().split("\n")


def docker_service_inspect(
    client: AnsibleModuleDockerClient, service_name: str
) -> dict[str, t.Any] | None:
    rc, out, dummy_err = client.call_cli("service", "inspect", service_name)
    if rc != 0:
        return None
    ret = json.loads(out)[0]["Spec"]
    return ret


def docker_stack_deploy(
    client: AnsibleModuleDockerClient, stack_name: str, compose_files: list[str]
) -> tuple[int, str, str]:
    command = ["stack", "deploy"]
    if client.module.params["prune"]:
        command += ["--prune"]
    if not client.module.params["detach"]:
        command += ["--detach=false"]
    if client.module.params["with_registry_auth"]:
        command += ["--with-registry-auth"]
    if client.module.params["resolve_image"]:
        command += ["--resolve-image", client.module.params["resolve_image"]]
    for compose_file in compose_files:
        command += ["--compose-file", compose_file]
    command += [stack_name]
    rc, out, err = client.call_cli(*command)
    return rc, to_text(out), to_text(err)


def docker_stack_inspect(
    client: AnsibleModuleDockerClient, stack_name: str
) -> dict[str, dict[str, t.Any] | None]:
    ret: dict[str, dict[str, t.Any] | None] = {}
    for service_name in docker_stack_services(client, stack_name):
        ret[service_name] = docker_service_inspect(client, service_name)
    return ret


def docker_stack_rm(
    client: AnsibleModuleDockerClient,
    stack_name: str,
    retries: int,
    interval: int | float,
) -> tuple[int, str, str]:
    command = ["stack", "rm", stack_name]
    if not client.module.params["detach"]:
        command += ["--detach=false"]
    rc, out, err = client.call_cli(*command)

    while to_text(err) != f"Nothing found in stack: {stack_name}\n" and retries > 0:
        sleep(interval)
        retries = retries - 1
        rc, out, err = client.call_cli(*command)
    return rc, to_text(out), to_text(err)


def main() -> None:
    client = AnsibleModuleDockerClient(
        argument_spec={
            "name": {"type": "str", "required": True},
            "compose": {"type": "list", "elements": "raw", "default": []},
            "prune": {"type": "bool", "default": False},
            "detach": {"type": "bool", "default": True},
            "with_registry_auth": {"type": "bool", "default": False},
            "resolve_image": {"type": "str", "choices": ["always", "changed", "never"]},
            "state": {
                "type": "str",
                "default": "present",
                "choices": ["present", "absent"],
            },
            "absent_retries": {"type": "int", "default": 0},
            "absent_retries_interval": {"type": "int", "default": 1},
        },
        supports_check_mode=False,
    )

    if not HAS_JSONDIFF:
        client.fail("jsondiff is not installed, try 'pip install jsondiff'")

    if not HAS_YAML:
        client.fail("yaml is not installed, try 'pip install pyyaml'")

    try:
        state = client.module.params["state"]
        compose = client.module.params["compose"]
        name = client.module.params["name"]
        absent_retries = client.module.params["absent_retries"]
        absent_retries_interval = client.module.params["absent_retries_interval"]

        if state == "present":
            if not compose:
                client.fail(
                    "compose parameter must be a list containing at least one element"
                )

            compose_files = []
            for compose_def in compose:
                if isinstance(compose_def, dict):
                    compose_file_fd, compose_file = tempfile.mkstemp()
                    client.module.add_cleanup_file(compose_file)
                    with os.fdopen(compose_file_fd, "w") as stack_file:
                        compose_files.append(compose_file)
                        stack_file.write(yaml_dump(compose_def))
                elif isinstance(compose_def, str):
                    compose_files.append(compose_def)
                else:
                    client.fail(
                        f"compose element '{compose_def}' must be a string or a dictionary"
                    )

            before_stack_services = docker_stack_inspect(client, name)

            rc, out, err = docker_stack_deploy(client, name, compose_files)

            after_stack_services = docker_stack_inspect(client, name)

            if rc != 0:
                client.fail(
                    "docker stack up deploy command failed",
                    rc=rc,
                    stdout=out,
                    stderr=err,
                )

            before_after_differences = json_diff(
                before_stack_services, after_stack_services
            )
            for k in before_after_differences:
                if isinstance(before_after_differences[k], dict):
                    before_after_differences[k].pop("UpdatedAt", None)
                    before_after_differences[k].pop("Version", None)
                    if not list(before_after_differences[k].keys()):
                        before_after_differences.pop(k)

            if not before_after_differences:
                client.module.exit_json(
                    changed=False,
                    rc=rc,
                    stdout=out,
                    stderr=err,
                )
            else:
                client.module.exit_json(
                    changed=True,
                    rc=rc,
                    stdout=out,
                    stderr=err,
                    stack_spec_diff=json_diff(
                        before_stack_services,
                        after_stack_services,
                        dump=True,
                    ),
                )

        else:
            if docker_stack_services(client, name):
                rc, out, err = docker_stack_rm(
                    client, name, absent_retries, absent_retries_interval
                )
                if rc != 0:
                    client.module.fail_json(
                        msg="'docker stack down' command failed",
                        rc=rc,
                        stdout=out,
                        stderr=err,
                    )
                else:
                    client.module.exit_json(
                        changed=True,
                        msg=out,
                        rc=rc,
                        stdout=out,
                        stderr=err,
                    )
            client.module.exit_json(changed=False)
    except DockerException as e:
        client.fail(
            f"An unexpected Docker error occurred: {e}",
            exception=traceback.format_exc(),
        )


if __name__ == "__main__":
    main()