From 58211153db39e888758deaa738cb4dd08f1da6b0 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 7 Jul 2022 13:56:48 +0200 Subject: [PATCH] Improve README (#418) * List missing plugins. * Fix short description. * Improve section on requirements. * Apply suggestions from code review Co-authored-by: Don Naro Co-authored-by: Don Naro --- README.md | 17 ++++++++++++++--- plugins/inventory/docker_containers.py | 2 +- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index de49411b..347c448a 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,26 @@ Please note that Ansible 2.9 and ansible-base 2.10 are no longer supported. If y ## External requirements -Most modules and plugins require the [Docker SDK for Python](https://pypi.org/project/docker/) and Python 2.7 or newer. Python 2.6 is no longer supported; use community.docker 2.x.y if you need to use Python 2.6. +Some modules and plugins require Docker CLI, or other external, programs. Some require the [Docker SDK for Python](https://pypi.org/project/docker/) and some use [requests](https://pypi.org/project/requests/) to directly communicate with the Docker daemon API. All modules and plugins require Python 2.7 or later. Python 2.6 is no longer supported; use community.docker 2.x.y if you need to use Python 2.6. -If you have Docker SDK for Python < 2.0.0 installed ([docker-py](https://pypi.org/project/docker-py/)), you can still use it, though we recommend to uninstall it and then install [docker](https://pypi.org/project/docker/), the Docker SDK for Python >= 2.0.0. Note that both libraries cannot be installed at the same time. If you accidentally did install them simultaneously, you have to uninstall *both* before re-installing one of them. +Installing the Docker SDK for Python also installs the requirements for the modules and plugins that use `requests`. If you want to directly install the Python libraries instead of the SDK, you need the following ones: + +- [requests](https://pypi.org/project/requests/); +- [pywin32](https://pypi.org/project/pywin32/) when using named pipes on Windows with the Windows 32 API; +- [paramiko](https://pypi.org/project/paramiko/) when using SSH to connect to the Docker daemon with `use_ssh_client=false`; +- [pyOpenSSL](https://pypi.org/project/pyOpenSSL/) when using TLS to connect to the Docker daemon; +- [backports.ssl_match_hostname](https://pypi.org/project/backports.ssl_match_hostname/) when using TLS to connect to the Docker daemon on Python 2. + +If you have Docker SDK for Python < 2.0.0 installed ([docker-py](https://pypi.org/project/docker-py/)), you can still use it for modules that support it, though we recommend to uninstall it and then install [docker](https://pypi.org/project/docker/), the Docker SDK for Python >= 2.0.0. Note that both libraries cannot be installed at the same time. If you accidentally did install them simultaneously, you have to uninstall *both* before re-installing one of them. ## Included content * Connection plugins: - - community.docker.docker: use Docker containers as remotes + - community.docker.docker: use Docker containers as remotes using the Docker CLI program + - community.docker.docker_api: use Docker containers as remotes using the Docker API + - community.docker.nsenter: execute commands on the host running the controller container * Inventory plugins: + - community.docker.docker_containers: dynamic inventory plugin for Docker containers - community.docker.docker_machine: collect Docker machines as inventory - community.docker.docker_swarm: collect Docker Swarm nodes as inventory * Modules: diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py index 78ff4bb6..af0a0fd0 100644 --- a/plugins/inventory/docker_containers.py +++ b/plugins/inventory/docker_containers.py @@ -13,7 +13,7 @@ __metaclass__ = type DOCUMENTATION = ''' name: docker_containers -short_description: Ansible dynamic inventory plugin for Docker containers. +short_description: Ansible dynamic inventory plugin for Docker containers version_added: 1.1.0 author: - Felix Fontein (@felixfontein)