From 765a5130d513addfef28c04cc951335424ce3b97 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 11 Jul 2018 23:57:39 +0200 Subject: [PATCH] Docker modules: improve documentation on docker vs. docker-py Python package requirements (#42457) * Make sure all docker-py/docker requirements are listed, and clarify about docker vs. docker-py. * Adjusting changes made in #40839. --- lib/ansible/module_utils/docker_common.py | 9 +++++---- .../modules/cloud/docker/docker_container.py | 14 ++++++++++---- lib/ansible/modules/cloud/docker/docker_image.py | 6 ++++++ .../modules/cloud/docker/docker_image_facts.py | 8 +++++++- lib/ansible/modules/cloud/docker/docker_login.py | 6 ++++++ lib/ansible/modules/cloud/docker/docker_network.py | 8 +++++++- lib/ansible/modules/cloud/docker/docker_secret.py | 6 +++++- lib/ansible/modules/cloud/docker/docker_service.py | 7 +++++++ lib/ansible/modules/cloud/docker/docker_swarm.py | 7 ++++++- lib/ansible/modules/cloud/docker/docker_volume.py | 8 +++++++- 10 files changed, 66 insertions(+), 13 deletions(-) diff --git a/lib/ansible/module_utils/docker_common.py b/lib/ansible/module_utils/docker_common.py index b97fa3f35d..0955e79748 100644 --- a/lib/ansible/module_utils/docker_common.py +++ b/lib/ansible/module_utils/docker_common.py @@ -167,14 +167,15 @@ class AnsibleDockerClient(Client): if HAS_DOCKER_MODELS and HAS_DOCKER_SSLADAPTER: self.fail("Cannot have both the docker-py and docker python modules installed together as they use the same namespace and " - "cause a corrupt installation. Please uninstall both packages, and re-install only the docker-py or docker python module") + "cause a corrupt installation. Please uninstall both packages, and re-install only the docker-py or docker python " + "module. It is recommended to install the docker module if no support for Python 2.6 is required.") if not HAS_DOCKER_PY: - self.fail("Failed to import docker-py - %s. Try `pip install docker-py`" % HAS_DOCKER_ERROR) + self.fail("Failed to import docker or docker-py - %s. Try `pip install docker` or `pip install docker-py` (Python 2.6)" % HAS_DOCKER_ERROR) if LooseVersion(docker_version) < LooseVersion(MIN_DOCKER_VERSION): - self.fail("Error: docker-py version is %s. Minimum version required is %s." % (docker_version, - MIN_DOCKER_VERSION)) + self.fail("Error: docker / docker-py version is %s. Minimum version required is %s." % (docker_version, + MIN_DOCKER_VERSION)) self.debug = self.module.params.get('debug') self.check_mode = self.module.check_mode diff --git a/lib/ansible/modules/cloud/docker/docker_container.py b/lib/ansible/modules/cloud/docker/docker_container.py index 38d30884e5..e2012695e3 100644 --- a/lib/ansible/modules/cloud/docker/docker_container.py +++ b/lib/ansible/modules/cloud/docker/docker_container.py @@ -96,7 +96,6 @@ options: description: - Path to a file containing environment variables I(FOO=BAR). - If variable also present in C(env), then C(env) value will override. - - Requires docker >= 2.3.0. entrypoint: description: - Command that overwrites the default ENTRYPOINT of the image. @@ -421,7 +420,13 @@ author: requirements: - "python >= 2.6" - - "docker >= 2.3.0" + - "docker-py >= 1.7.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "Docker API >= 1.20" ''' @@ -619,7 +624,7 @@ try: from docker.utils.types import Ulimit, LogConfig from ansible.module_utils.docker_common import docker_version except: - # missing docker handled in ansible.module_utils.docker + # missing docker-py handled in ansible.module_utils.docker pass @@ -2016,7 +2021,8 @@ class AnsibleDockerClientContainer(AnsibleDockerClient): init_supported = init_supported and LooseVersion(docker_version) >= LooseVersion('2.2') if self.module.params.get("init") and not init_supported: - self.fail('docker-py version is %s. Minimum version required is 2.2 to set init option.' % (docker_version,)) + self.fail("docker or docker-py version is %s. Minimum version required is 2.2 to set init option. " + "If you use the 'docker-py' module, you have to switch to the docker 'Python' package." % (docker_version,)) self.HAS_INIT_OPT = init_supported self.HAS_AUTO_REMOVE_OPT = HAS_DOCKER_PY_2 or HAS_DOCKER_PY_3 diff --git a/lib/ansible/modules/cloud/docker/docker_image.py b/lib/ansible/modules/cloud/docker/docker_image.py index 7d497fb901..7dacf1c76a 100644 --- a/lib/ansible/modules/cloud/docker/docker_image.py +++ b/lib/ansible/modules/cloud/docker/docker_image.py @@ -168,6 +168,12 @@ extends_documentation_fragment: requirements: - "python >= 2.6" - "docker-py >= 1.7.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "Docker API >= 1.20" author: diff --git a/lib/ansible/modules/cloud/docker/docker_image_facts.py b/lib/ansible/modules/cloud/docker/docker_image_facts.py index fe2e91aec7..9e205f8f64 100644 --- a/lib/ansible/modules/cloud/docker/docker_image_facts.py +++ b/lib/ansible/modules/cloud/docker/docker_image_facts.py @@ -36,6 +36,12 @@ extends_documentation_fragment: requirements: - "python >= 2.6" - "docker-py >= 1.7.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "Docker API >= 1.20" author: @@ -152,7 +158,7 @@ images: try: from docker import utils except ImportError: - # missing docker-py handled in docker_common + # missing docker-py handled in ansible.module_utils.docker_common pass from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass diff --git a/lib/ansible/modules/cloud/docker/docker_login.py b/lib/ansible/modules/cloud/docker/docker_login.py index 606dc654cc..cadb2459d9 100644 --- a/lib/ansible/modules/cloud/docker/docker_login.py +++ b/lib/ansible/modules/cloud/docker/docker_login.py @@ -77,6 +77,12 @@ extends_documentation_fragment: requirements: - "python >= 2.6" - "docker-py >= 1.7.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "Docker API >= 1.20" - 'Only to be able to logout (state=absent): the docker command line utility' author: diff --git a/lib/ansible/modules/cloud/docker/docker_network.py b/lib/ansible/modules/cloud/docker/docker_network.py index fbdf6b3b3f..304edaf3d8 100644 --- a/lib/ansible/modules/cloud/docker/docker_network.py +++ b/lib/ansible/modules/cloud/docker/docker_network.py @@ -96,6 +96,12 @@ author: requirements: - "python >= 2.6" - "docker-py >= 1.7.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "The docker server >= 1.9.0" ''' @@ -156,7 +162,7 @@ try: if HAS_DOCKER_PY_2 or HAS_DOCKER_PY_3: from docker.types import IPAMPool, IPAMConfig except: - # missing docker-py handled in ansible.module_utils.docker + # missing docker-py handled in ansible.module_utils.docker_common pass diff --git a/lib/ansible/modules/cloud/docker/docker_secret.py b/lib/ansible/modules/cloud/docker/docker_secret.py index d7d6a28bb1..5656a4130a 100644 --- a/lib/ansible/modules/cloud/docker/docker_secret.py +++ b/lib/ansible/modules/cloud/docker/docker_secret.py @@ -60,6 +60,10 @@ extends_documentation_fragment: requirements: - "docker-py >= 2.1.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + Version 2.1.0 or newer is only available with the C(docker) module." - "Docker API >= 1.25" author: @@ -140,7 +144,7 @@ import hashlib try: from docker.errors import APIError except ImportError: - # missing docker-py handled in ansible.module_utils.docker + # missing docker-py handled in ansible.module_utils.docker_common pass from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass diff --git a/lib/ansible/modules/cloud/docker/docker_service.py b/lib/ansible/modules/cloud/docker/docker_service.py index 75f9f0615a..28992947d2 100644 --- a/lib/ansible/modules/cloud/docker/docker_service.py +++ b/lib/ansible/modules/cloud/docker/docker_service.py @@ -143,6 +143,13 @@ extends_documentation_fragment: requirements: - "python >= 2.6" + - "docker-py >= 1.8.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "docker-compose >= 1.7.0" - "Docker API >= 1.20" - "PyYAML >= 3.11" diff --git a/lib/ansible/modules/cloud/docker/docker_swarm.py b/lib/ansible/modules/cloud/docker/docker_swarm.py index 204c605d9c..9fbb1a2bd6 100644 --- a/lib/ansible/modules/cloud/docker/docker_swarm.py +++ b/lib/ansible/modules/cloud/docker/docker_swarm.py @@ -136,6 +136,11 @@ extends_documentation_fragment: - docker requirements: - python >= 2.7 + - "docker-py >= 2.6.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + Version 2.1.0 or newer is only available with the C(docker) module." - Docker API >= 1.35 author: - Thierry Bouvet (@tbouvet) @@ -214,7 +219,7 @@ from time import sleep try: from docker.errors import APIError except ImportError: - # missing docker-py handled in ansible.module_utils.docker + # missing docker-py handled in ansible.module_utils.docker_common pass from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass diff --git a/lib/ansible/modules/cloud/docker/docker_volume.py b/lib/ansible/modules/cloud/docker/docker_volume.py index 31ced623de..7e0ab11f22 100644 --- a/lib/ansible/modules/cloud/docker/docker_volume.py +++ b/lib/ansible/modules/cloud/docker/docker_volume.py @@ -68,6 +68,12 @@ author: requirements: - "python >= 2.6" - "docker-py >= 1.10.0" + - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python + module has been superseded by L(docker,https://pypi.org/project/docker/) + (see L(here,https://github.com/docker/docker-py/issues/1310) for details). + For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to + install the C(docker) Python module. Note that both modules should I(not) + be installed at the same time." - "The docker server >= 1.9.0" ''' @@ -100,7 +106,7 @@ facts: try: from docker.errors import APIError except ImportError: - # missing docker-py handled in ansible.module_utils.docker + # missing docker-py handled in ansible.module_utils.docker_common pass from ansible.module_utils.docker_common import DockerBaseClass, AnsibleDockerClient