diff --git a/docs/docsite/rst/scenario_guide.rst b/docs/docsite/rst/scenario_guide.rst index 60f8d845..11684664 100644 --- a/docs/docsite/rst/scenario_guide.rst +++ b/docs/docsite/rst/scenario_guide.rst @@ -49,7 +49,7 @@ Parameters Most plugins and modules can be configured by the following parameters: docker_host - The URL or Unix socket path used to connect to the Docker API. Defaults to ``unix://var/run/docker.sock``. To connect to a remote host, provide the TCP connection string (for example: ``tcp://192.0.2.23:2376``). If TLS is used to encrypt the connection to the API, then the module will automatically replace 'tcp' in the connection URL with 'https'. + The URL or Unix socket path used to connect to the Docker API. Defaults to ``unix:///var/run/docker.sock``. To connect to a remote host, provide the TCP connection string (for example: ``tcp://192.0.2.23:2376``). If TLS is used to encrypt the connection to the API, then the module will automatically replace ``tcp`` in the connection URL with ``https``. api_version The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by the Docker SDK for Python installed. @@ -78,6 +78,58 @@ Most plugins and modules can be configured by the following parameters: ssl_version Provide a valid SSL version number. The default value is determined by the Docker SDK for Python. + This option is not available for the CLI based plugins. It is mainly needed for legacy systems and should be avoided. + + +Module default group +.................... + +To avoid having to specify common parameters for all the modules in every task, you can use the ``community.docker.docker`` :ref:`module defaults group `, or its short name ``docker``. Please note that the Docker Swarm stack modules (:ansplugin:`community.docker.docker_stack#module`, :ansplugin:`community.docker.docker_stack_info#module`, and :ansplugin:`community.docker.docker_stack_task_info#module`) are not part of the defaults group. + +.. note:: + + Module default groups only work for modules, not for plugins (connection and inventory plugins). + +The following example shows how the module default group can be used in a playbook: + +.. code-block:: yaml+jinja + + --- + - name: Pull and image and start the container + hosts: localhost + gather_facts: false + module_defaults: + group/community.docker.docker: + # Select Docker Daemon on other host + docker_host: tcp://192.0.2.23:2376 + # Configure TLS + tls: true + validate_certs: true + tls_hostname: docker.example.com + cacert_path: /path/to/cacert.pem + # Increase timeout + timeout: 120 + tasks: + - name: Pull image + community.docker.docker_image_pull: + name: python + tag: 3.12 + + - name: Start container + community.docker.docker_container: + cleanup: true + command: python --version + detach: false + image: python:3.12 + name: my-python-container + output_logs: true + + - name: Show output + ansible.builtin.debug: + msg: "{{ output.container.Output }}" + +Here the two ``community.docker`` tasks will use the options set for the module defaults group. + Environment variables ..................... @@ -148,12 +200,27 @@ For working with a plain Docker daemon, that is without Swarm, there are connect docker_image module The :ansplugin:`community.docker.docker_image module ` provides full control over images, including: build, pull, push, tag and remove. - docker_image_load - The :ansplugin:`community.docker.docker_image_load module ` allows you to import one or multiple images from tarballs. + docker_image_build + The :ansplugin:`community.docker.docker_image_build module ` allows you to build a Docker image using Docker buildx. docker_image_info module The :ansplugin:`community.docker.docker_image_info module ` allows you to list and inspect images. + docker_image_load + The :ansplugin:`community.docker.docker_image_load module ` allows you to import one or multiple images from tarballs. + + docker_image_pull + The :ansplugin:`community.docker.docker_image_pull module ` allows you to pull a Docker image from a registry. + + docker_image_push + The :ansplugin:`community.docker.docker_image_push module ` allows you to push a Docker image to a registry. + + docker_image_remove + The :ansplugin:`community.docker.docker_image_remove module ` allows you to remove and/or untag a Docker image from the Docker daemon. + + docker_image_tag + The :ansplugin:`community.docker.docker_image_tag module ` allows you to tag a Docker image with additional names and/or tags. + docker_network module The :ansplugin:`community.docker.docker_network module ` provides full control over Docker networks. @@ -185,11 +252,23 @@ For working with a plain Docker daemon, that is without Swarm, there are connect Docker Compose -------------- +Docker Compose v2 +................. + +The :ansplugin:`community.docker.docker_compose_v2 module ` +allows you to use your existing Docker compose files to orchestrate containers on a single Docker daemon or on Swarm. +This module uses the Docker CLI "compose" plugin (``docker compose``), and thus needs access to the Docker CLI tool. +No further requirements next to to the CLI tool and its Docker Compose plugin are needed. + +Docker Compose v1 +................. + The :ansplugin:`community.docker.docker_compose module ` allows you to use your existing Docker compose files to orchestrate containers on a single Docker daemon or on Swarm. -Supports compose versions 1 and 2. +This module uses the out-dated and End of Life version 1.x of Docker Compose. It should mainly be used for legacy systems +which still have to use that version of Docker Compose. -Next to Docker SDK for Python, you need to install `docker-compose `_ on the remote machines to use the module. +You need to install the `old Python docker-compose `_ on the remote machines to use the module. Docker Machine @@ -198,10 +277,10 @@ Docker Machine The :ansplugin:`community.docker.docker_machine inventory plugin ` allows you to dynamically add Docker Machine hosts to your Ansible inventory. -Docker stack ------------- +Docker Swarm stack +------------------ -The :ansplugin:`community.docker.docker_stack module ` module allows you to control Docker stacks. Information on stacks can be retrieved by the :ansplugin:`community.docker.docker_stack_info module `, and information on stack tasks can be retrieved by the :ansplugin:`community.docker.docker_stack_task_info module `. +The :ansplugin:`community.docker.docker_stack module ` module allows you to control Docker Swarm stacks. Information on Swarm stacks can be retrieved by the :ansplugin:`community.docker.docker_stack_info module `, and information on Swarm stack tasks can be retrieved by the :ansplugin:`community.docker.docker_stack_task_info module `. Docker Swarm @@ -240,16 +319,7 @@ The community.docker collection offers modules to manage Docker Swarm configurat docker_secret module The :ansplugin:`community.docker.docker_secret module ` allows you to create and modify Docker Swarm secrets. - Swarm services .............. Docker Swarm services can be created and updated with the :ansplugin:`community.docker.docker_swarm_service module `, and information on them can be queried by the :ansplugin:`community.docker.docker_swarm_service_info module `. - - -Helpful links -------------- - -Still using Dockerfile to build images? Check out `ansible-bender `_, and start building images from your Ansible playbooks. - -Use `Ansible Operator `_ to launch your docker-compose file on `OpenShift `_. Go from an app on your laptop to a fully scalable app in the cloud with Kubernetes in just a few moments. diff --git a/plugins/doc_fragments/docker.py b/plugins/doc_fragments/docker.py index 747b8191..99cb9f1d 100644 --- a/plugins/doc_fragments/docker.py +++ b/plugins/doc_fragments/docker.py @@ -320,7 +320,6 @@ options: - When verifying the authenticity of the Docker Host server, provide the expected name of the server. - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS_HOSTNAME) will be used instead. If the environment variable is not set, the default value will be used. - - Note that this option had a default value V(localhost) in older versions. It was removed in community.docker 3.0.0. type: str api_version: description: