Skip to content

Latest commit

 

History

History
1679 lines (1210 loc) · 138 KB

CHANGELOG.md

File metadata and controls

1679 lines (1210 loc) · 138 KB
Raw

Docker Community Collection Release Notes

Topics

v4.0.0

Release Summary

Major release with removed deprecated features.

Minor Changes

  • docker_compose_v2 - add renew_anon_volumes parameter for docker compose up (#977).

Breaking Changes / Porting Guide

  • docker_container - the default of image_name_mismatch changed from ignore to recreate (#971).

Removed Features (previously deprecated)

  • The collection no longer supports ansible-core 2.11, 2.12, 2.13, and 2.14. You need ansible-core 2.15.0 or newer to use community.docker 4.x.y (#971).
  • The docker_compose module has been removed. Please migrate to community.docker.docker_compose_v2 (#971).
  • docker_container - the ignore_image option has been removed. Use image: ignore in comparisons instead (#971).
  • docker_container - the purge_networks option has been removed. Use networks: strict in comparisons instead and make sure that networks is specified (#971).
  • various modules and plugins - remove the ssl_version option (#971).

v3.13.1

Release Summary

Bugfix release.

Bugfixes

  • docker_compose_v2 - improve parsing of dry-run image build operations from JSON events (#975, #976).

v3.13.0

Release Summary

Feature release.

New Modules

  • community.docker.docker_compose_v2_exec - Run command in a container of a Compose service.
  • community.docker.docker_compose_v2_run - Run command in a new container of a Compose service.

v3.12.2

Release Summary

Bugfix release.

Bugfixes

  • docker_prune - fix handling of lists for the filter options (#961, #966).

v3.12.1

Release Summary

Maintenance release with updated documentation and changelog.

Deprecated Features

  • The collection deprecates support for all ansible-core versions that are currently End of Life, according to the ansible-core support matrix. This means that the next major release of the collection will no longer support ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14.

v3.12.0

Release Summary

Bugfix and feature release.

Minor Changes

  • docker, docker_api connection plugins - allow to determine the working directory when executing commands with the new working_dir option (#943).
  • docker, docker_api connection plugins - allow to execute commands with extended privileges with the new privileges option (#943).
  • docker, docker_api connection plugins - allow to pass extra environment variables when executing commands with the new extra_env option (#937, #940).
  • docker_compose_v2* modules - support Docker Compose 2.29.0's json progress writer to avoid having to parse text output (#931).
  • docker_compose_v2_pull - add new options ignore_buildable, include_deps, and services (#941, #942).
  • docker_container - when creating a container, directly pass all networks to connect to to the Docker Daemon for API version 1.44 and newer. This makes creation more efficient and works around a bug in Docker Daemon that does not use the specified MAC address in at least some cases, though only for creation (#933).

Bugfixes

  • docker_compose_v2 - handle yet another random unstructured error output from pre-2.29.0 Compose versions (#948, #949).
  • docker_compose_v2 - make sure that services provided in services are appended to the command line after -- and not before it (#942).
  • docker_compose_v2* modules, docker_image_build - provide better error message when required fields are not present in docker version or docker info output. This can happen if Podman is used instead of Docker (#891, #935).
  • docker_container - fix idempotency if network_mode=default and Docker 26.1.0 or later is used. There was a breaking change in Docker 26.1.0 regarding normalization of NetworkMode (#934, #936).
  • docker_container - restore behavior of the module from community.docker 2.x.y that passes the first network to the Docker Deamon while creating the container (#933).
  • docker_image_build - fix --output parameter composition for type=docker and type=image (#946, #947).

Known Issues

  • docker_container - when specifying a MAC address for a container's network, and the network is attached after container creation (for example, due to idempotency checks), the MAC address is at least in some cases ignored by the Docker Daemon (#933).

v3.11.0

Minor Changes

  • docker_container - add support for device_cgroup_rules (#910).
  • docker_container - the new state=healthy allows to wait for a container to become healthy on startup. The healthy_wait_timeout option allows to configure the maximum time to wait for this to happen (#890, #921).

Bugfixes

  • docker_compose_v2* modules - fix parsing of skipped pull messages for Docker Compose 2.28.x (#911, #916).
  • docker_compose_v2*, docker_stack*, docker_image_build modules - using cli_context no longer leads to an invalid parameter combination being passed to the corresponding Docker CLI tool, unless docker_host is also provided. Combining cli_context and docker_host is no longer allowed (#892, #895).
  • docker_container - fix possible infinite loop if removal_wait_timeout is set (#922).
  • vendored Docker SDK for Python - use LooseVersion instead of StrictVersion to compare urllib3 versions. This is needed for development versions (#902).

v3.10.4

Release Summary

Bugfix release.

Bugfixes

  • docker_compose - make sure that the module uses the api_version parameter (#881).
  • docker_compose_v2* modules - there was no check to make sure that one of project_src and definition is provided. The modules crashed if none were provided (#885, #886).

v3.10.3

Release Summary

Bugfix release.

Bugfixes

  • docker and nsenter connection plugins, docker_container_exec module - avoid using the deprecated ansible.module_utils.compat.selectors module util with Python 3 (#870, #871).

v3.10.2

Release Summary

Bugfix release.

Bugfixes

v3.10.1

Release Summary

Hotfix release for requests 2.32.0 compatibility.

Bugfixes

Known Issues

  • Please note that the fix for requests 2.32.0 included in community.docker 3.10.1 only fixes problems with the vendored Docker SDK for Python code. Modules and plugins that use Docker SDK for Python can still fail due to the SDK currently being incompatible with requests 2.32.0.

    If you still experience problems with requests 2.32.0, such as error messages like Not supported URL scheme http+docker, please restrict requests to <2.32.0.

v3.10.0

Release Summary

Feature release.

Minor Changes

  • docker_container - adds healthcheck.start_interval to support healthcheck start interval setting on containers (#848).
  • docker_container - adds healthcheck.test_cli_compatible to allow omit test option on containers without remove existing image test (#847).
  • docker_image_build - add outputs option to allow configuring outputs for the build (#852).
  • docker_image_build - add secrets option to allow passing secrets to the build (#852).
  • docker_image_build - allow platform to be a list of platforms instead of only a single platform for multi-platform builds (#852).
  • docker_network - adds config_only and config_from to support creating and using config only networks (#395).
  • docker_prune - add new options builder_cache_all, builder_cache_filters, and builder_cache_keep_storage, and a new return value builder_cache_caches_deleted for pruning build caches (#844, #845).
  • docker_swarm_service - adds sysctls to support sysctl settings on swarm services (#190).

Deprecated Features

  • docker_compose - the Docker Compose v1 module is deprecated and will be removed from community.docker 4.0.0. Please migrate to the community.docker.docker_compose_v2 module, which works with Docker Compose v2 (#823, #833).
  • various modules and plugins - the ssl_version option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues (#853).

v3.9.0

Release Summary

Bugfix and feature release.

Minor Changes

  • The EE requirements now include PyYAML, since the docker_compose_v2* modules depend on it when the definition option is used. This should not have a noticable effect on generated EEs since ansible-core itself depends on PyYAML as well, and ansible-builder explicitly ignores this dependency (#832).
  • docker_compose_v2* - the new option check_files_existing allows to disable the check for one of the files compose.yaml, compose.yml, docker-compose.yaml, and docker-compose.yml in project_src if files is not specified. This is necessary if a non-standard compose filename is specified through other means, like the COMPOSE_FILE environment variable (#838, #839).
  • docker_compose_v2* modules - allow to provide an inline definition of the compose content instead of having to provide a project_src directory with the compose file written into it (#829, #832).
  • vendored Docker SDK for Python - remove unused code that relies on functionality deprecated in Python 3.12 (#834).

Bugfixes

  • docker_compose_v2* - allow project_src to be a relative path, by converting it to an absolute path before using it (#827, #828).
  • docker_compose_v2* modules - abort with a nice error message instead of crash when the Docker Compose CLI plugin version is dev (#825, #826).
  • inventory plugins - add unsafe wrapper to avoid marking strings that do not contain { or } as unsafe, to work around a bug in AWX (#835).

v3.8.1

Release Summary

Bugfix release

Security Fixes

Bugfixes

  • docker_compose_v2 - do not fail when non-fatal errors occur. This can happen when pulling an image fails, but then the image can be built for another service. Docker Compose emits an error in that case, but docker compose up still completes successfully (#807, #810, #811).
  • docker_compose_v2* modules - correctly parse Warning events emitted by Docker Compose (#807, #811).
  • docker_compose_v2* modules - parse logfmt warnings emitted by Docker Compose (#787, #811).
  • docker_compose_v2_pull - fixing idempotence by checking actual pull progress events instead of service-level pull request when policy=always. This stops the module from reporting changed=true if no actual change happened when pulling. In check mode, it has to assume that a change happens though (#813, #814).

v3.8.0

Release Summary

Bugfix and feature release.

Minor Changes

  • docker_compose_v2 - allow to wait until containers are running/health when running docker compose up with the new wait option (#794, #796).
  • docker_container - the pull_check_mode_behavior option now allows to control the module's behavior in check mode when pull=always (#792, #797).
  • docker_container - the pull option now accepts the three values never, missing_image (default), and never, next to the previously valid values true (equivalent to always) and false (equivalent to missing_image). This allows the equivalent to --pull=never from the Docker command line (#783, #797).

Bugfixes

  • docker_compose_v2 - do not consider a Waiting event as an action/change (#804).
  • docker_compose_v2 - do not treat service-level pull events as changes to avoid incorrect changed=true return value of pull=always (#802, #803).
  • docker_compose_v2, docker_compose_v2_pull - fix parsing of pull messages for Docker Compose 2.20.0 (#785, #786).

v3.7.0

Release Summary

Bugfix and feature release.

Minor Changes

  • docker_compose_v2 - add scale option to allow to explicitly scale services (#776).
  • docker_compose_v2, docker_compose_v2_pull - support files parameter to specify multiple Compose files (#772, #775).

Bugfixes

  • docker_compose_v2 - properly parse dry-run build events from stderr (#778, #779).
  • docker_compose_v2_pull - the module was documented as part of the community.docker.docker action group, but was not actually part of it. That has now been fixed (#773).

New Modules

  • community.docker.docker_image_export - Export (archive) Docker images

v3.6.0

Release Summary

Bugfix and feature release.

The collection now includes a bunch of new docker_image_* modules that move features out of the rather complex docker_image module. These new modules are easier to use and can better declare whether they support check mode, diff mode, or none of them.

This version also features modules that support the Docker CLI plugins buildx and compose. The docker_image_build module uses the docker buildx command under the hood, and the docker_compose_v2 and docker_compose_v2_pull modules uses the docker compose command. All these modules use the Docker CLI instead of directly talking to the API. The modules support mostly the same interface as the API based modules, so the main difference is that instead of some Python requirements, they depend on the Docker CLI tool docker.

Major Changes

  • The community.docker collection now depends on the community.library_inventory_filtering_v1 collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ansible-galaxy collection install, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (#698).

Minor Changes

  • The ca_cert option available to almost all modules and plugins has been renamed to ca_path. The name ca_path is also used for similar options in ansible-core and other collections. The old name has been added as an alias and can still be used (#744).
  • The docker_stack* modules now use the common CLI-based module code added for the docker_image_build and docker_compose_v2 modules. This means that the modules now have various more configuration options with respect to talking to the Docker Daemon, and now also are part of the community.docker.docker and docker module default groups (#745).
  • docker_container - add networks[].mac_address option for Docker API 1.44+. Note that Docker API 1.44 no longer uses the global mac_address option, this new option is the only way to set the MAC address for a container (#763).
  • docker_image - allow to specify labels and /dev/shm size when building images (#726, #727).
  • docker_image - allow to specify memory size and swap memory size in other units than bytes (#727).
  • inventory plugins - add filter option which allows to include and exclude hosts based on Jinja2 conditions (#698, #610).

Bugfixes

  • Use unix:///var/run/docker.sock instead of the legacy unix://var/run/docker.sock as default for docker_host (#736).
  • docker_image - fix archiving idempotency with Docker API 1.44 or later (#765).

New Modules

  • community.docker.docker_compose_v2 - Manage multi-container Docker applications with Docker Compose CLI plugin
  • community.docker.docker_compose_v2_pull - Pull a Docker compose project
  • community.docker.docker_image_build - Build Docker images using Docker buildx
  • community.docker.docker_image_pull - Pull Docker images from registries
  • community.docker.docker_image_push - Push Docker images to registries
  • community.docker.docker_image_remove - Remove Docker images
  • community.docker.docker_image_tag - Tag Docker images with new names and/or tags

v3.5.0

Release Summary

Bugfix and feature release.

Minor Changes

  • docker_container - implement better platform string comparisons to improve idempotency (#654, #705).
  • docker_container - internal refactorings which allow comparisons to use more information like details of the current image or the Docker host config (#713).

Deprecated Features

  • docker_container - the default ignore for the image_name_mismatch parameter has been deprecated and will switch to recreate in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes (#703).

Bugfixes

  • modules and plugins using the Docker SDK for Python - remove ssl_version from the parameters passed to Docker SDK for Python 7.0.0+. Explicitly fail with a nicer error message if it was explicitly set in this case (#715).
  • modules and plugins using the Docker SDK for Python - remove tls_hostname from the parameters passed to Docker SDK for Python 7.0.0+. Explicitly fail with a nicer error message if it was explicitly set in this case (#721).
  • vendored Docker SDK for Python - avoid passing on ssl_version and tls_hostname if they were not provided by the user. Remove dead code. (#722).

v3.4.11

Release Summary

Bugfix release.

Bugfixes

  • docker_volume - fix crash caused by accessing an empty dictionary. The has_different_config() was raising an AttributeError because the self.existing_volume["Labels"] dictionary was None (#702).

v3.4.10

Release Summary

Bugfix release.

Bugfixes

  • docker_swarm - make init and join operations work again with Docker SDK for Python before 4.0.0 (#695, #696).

v3.4.9

Release Summary

Maintenance release with updated documentation and vendored Docker SDK for Python code.

Bugfixes

  • vendored Docker SDK for Python code - cherry-pick changes from the Docker SDK for Python code to align code. These changes should not affect the parts used by the collection's code (#694).

v3.4.8

Release Summary

Maintenance release with updated documentation.

From this version on, community.docker is using the new Ansible semantic markup in its documentation. If you look at documentation with the ansible-doc CLI tool from ansible-core before 2.15, please note that it does not render the markup correctly. You should be still able to read it in most cases, but you need ansible-core 2.15 or later to see it as it is intended. Alternatively you can look at the devel docsite for the rendered HTML version of the documentation of the latest release.

Known Issues

v3.4.7

Release Summary

Bugfix release.

Bugfixes

  • docker_swarm_info - if service=true is used, do not crash when a service without an endpoint spec is encountered (#636, #637).

v3.4.6

Release Summary

Bugfix release with documentation warnings about using certain functionality when connecting to the Docker daemon with TCP TLS.

Bugfixes

  • socket_handler module utils - make sure this fully works when Docker SDK for Python is not available (#620).
  • vendored Docker SDK for Python code - fix for errors on pipe close in Windows (#619).
  • vendored Docker SDK for Python code - respect timeouts on Windows named pipes (#619).
  • vendored Docker SDK for Python code - use poll() instead of select() except on Windows (#619).

Known Issues

  • docker_api connection plugin - does not work with TCP TLS sockets! This is caused by the inability to send an close_notify TLS alert without closing the connection with Python's SSLSocket (#605, #621).
  • docker_container_exec - does not work with TCP TLS sockets when the stdin option is used! This is caused by the inability to send an close_notify TLS alert without closing the connection with Python's SSLSocket (#605, #621).

v3.4.5

Release Summary

Maintenance release which adds compatibility with requests 2.29.0 and 2.30.0 and urllib3 2.0.

Bugfixes

  • Make vendored Docker SDK for Python code compatible with requests 2.29.0 and urllib3 2.0 (#613).

v3.4.4

Release Summary

Maintenance release with updated EE requirements and updated documentation.

Minor Changes

  • Restrict requests to versions before 2.29.0, and urllib3 to versions before 2.0.0. This is necessary until the vendored code from Docker SDK for Python has been fully adjusted to work with a feature of urllib3 that is used since requests 2.29.0 (#611, #612).

Known Issues

  • The modules and plugins using the vendored code from Docker SDK for Python currently do not work with requests 2.29.0 and/or urllib3 2.0.0. The same is currently true for the latest version of Docker SDK for Python itself (#611, #612).

v3.4.3

Release Summary

Maintenance release with improved documentation.

v3.4.2

Release Summary

Bugfix release.

Bugfixes

  • docker_prune - return correct value for changed. So far the module always claimed that nothing changed (#593).

v3.4.1

Release Summary

Regular bugfix release.

Bugfixes

  • docker_api connection plugin, docker_container_exec, docker_container_copy_into - properly close socket to Daemon after executing commands in containers (#582).
  • docker_container - fix tmfs_size and tmpfs_mode not being set (#580).
  • various plugins and modules - remove unnecessary imports (#574).

v3.4.0

Release Summary

Regular bugfix and feature release.

Minor Changes

  • docker_api connection plugin - when copying files to/from a container, stream the file contents instead of first reading them to memory (#545).
  • docker_host_info - allow to list all containers with new option containers_all (#535, #538).

Bugfixes

  • docker_api connection plugin - fix error handling when 409 Conflict is returned by the Docker daemon in case of a stopped container (#546).
  • docker_container_exec - fix error handling when 409 Conflict is returned by the Docker daemon in case of a stopped container (#546).
  • docker_plugin - do not crash if plugin is installed in check mode (#552, #553).
  • most modules - fix handling of DOCKER_TIMEOUT environment variable, and improve handling of other fallback environment variables (#551, #554).

New Modules

  • community.docker.docker_container_copy_into - Copy a file into a Docker container

v3.3.2

Release Summary

Bugfix release.

Bugfixes

  • docker_container - when detach=false, wait indefinitely and not at most one minute. This was the behavior with Docker SDK for Python, and was accidentally changed in 3.0.0 (#526, #527).

v3.3.1

Release Summary

Bugfix release.

Bugfixes

  • current_container_facts - make container detection work better in more cases (#522).

v3.3.0

Release Summary

Feature and bugfix release.

Minor Changes

  • current_container_facts - make work with current Docker version, also support Podman (#510).
  • docker_image - when using archive_path, detect whether changes are necessary based on the image ID (hash). If the existing tar archive matches the source, do nothing. Previously, each task execution re-created the archive (#500).

Bugfixes

  • docker_container_exec - fix chdir option which was ignored since community.docker 3.0.0 (#517, #518).
  • vendored latest Docker SDK for Python bugfix (#513, docker/docker-py#3045).

v3.2.2

Release Summary

Bugfix release.

Bugfixes

  • docker_container - the kill_signal option erroneously did not accept strings anymore since 3.0.0 (#505, #506).

v3.2.1

Release Summary

Maintenance release with improved documentation.

v3.2.0

Release Summary

Feature and deprecation release.

Minor Changes

  • docker_container - added image_name_mismatch option which allows to control the behavior if the container uses the image specified, but the container's configuration uses a different name for the image than the one provided to the module (#485, #488).

Deprecated Features

  • docker_container - the ignore_image option is deprecated and will be removed in community.docker 4.0.0. Use image: ignore in comparisons instead (#487).
  • docker_container - the purge_networks option is deprecated and will be removed in community.docker 4.0.0. Use networks: strict in comparisons instead, and make sure to provide networks, with value [] if all networks should be removed (#487).

v3.1.0

Release Summary

Feature release.

Minor Changes

  • The collection repository conforms to the REUSE specification except for the changelog fragments (#462).
  • docker_swarm - allows usage of the data_path_port parameter when initializing a swarm (#296).

v3.0.2

Release Summary

Bugfix release.

Bugfixes

  • docker_image - fix build argument handling (#455, #456).

v3.0.1

Release Summary

Bugfix release.

Bugfixes

  • docker_container - fix handling of env_file (#451, #452).

v3.0.0

Release Summary

The 3.0.0 release features a rewrite of the docker_container module, and many modules and plugins no longer depend on the Docker SDK for Python.

Major Changes

  • The collection now contains vendored code from the Docker SDK for Python to talk to the Docker daemon. Modules and plugins using this code no longer need the Docker SDK for Python installed on the machine the module or plugin is running on (#398).
  • docker_api connection plugin - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#414).
  • docker_container - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#422).
  • docker_container - the module was completely rewritten from scratch (#422).
  • docker_container_exec - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#401).
  • docker_container_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#402).
  • docker_containers inventory plugin - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#413).
  • docker_host_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#403).
  • docker_image - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#404).
  • docker_image_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#405).
  • docker_image_load - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#406).
  • docker_login - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#407).
  • docker_network - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#408).
  • docker_network_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#409).
  • docker_plugin - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#429).
  • docker_prune - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#410).
  • docker_volume - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#411).
  • docker_volume_info - no longer uses the Docker SDK for Python. It requires requests to be installed, and depending on the features used has some more requirements. If the Docker SDK for Python is installed, these requirements are likely met (#412).

Minor Changes

  • All software licenses are now in the LICENSES/ directory of the collection root. Moreover, SPDX-License-Identifier: is used to declare the applicable license for every file that is not automatically generated (#430).
  • Remove vendored copy of distutils.version in favor of vendored copy included with ansible-core 2.12+. For ansible-core 2.11, uses distutils.version for Python < 3.12. There is no support for ansible-core 2.11 with Python 3.12+ (#271).
  • docker_container - add a new parameter image_comparison to control the behavior for which image will be used for idempotency checks (#421, #428).
  • docker_container - add support for cgroupns_mode (#338, #427).
  • docker_container - allow to specify platform (#123, #426).
  • modules and plugins communicating directly with the Docker daemon - improve default TLS version selection for Python 3.6 and newer. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).
  • modules and plugins communicating directly with the Docker daemon - simplify use of helper function that was removed in Docker SDK for Python to find executables (#438).
  • socker_handler and socket_helper module utils - improve Python forward compatibility, create helper functions for file blocking/unblocking (#415).

Breaking Changes / Porting Guide

  • This collection does not work with ansible-core 2.11 on Python 3.12+. Please either upgrade to ansible-core 2.12+, or use Python 3.11 or earlier (#271).
  • docker_container - exposed_ports is no longer ignored in comparisons. Before, its value was assumed to be identical with the value of published_ports (#422).
  • docker_container - log_options can no longer be specified when log_driver is not specified (#422).
  • docker_container - publish_all_ports is no longer ignored in comparisons (#422).
  • docker_container - restart_retries can no longer be specified when restart_policy is not specified (#422).
  • docker_container - stop_timeout is no longer ignored for idempotency if told to be not ignored in comparisons. So far it defaulted to ignore there, and setting it to strict had no effect (#422).
  • modules and plugins communicating directly with the Docker daemon - when connecting by SSH and not using use_ssh_client=true, reject unknown host keys instead of accepting them. This is only a breaking change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).

Removed Features (previously deprecated)

  • Execution Environments built with community.docker no longer include docker-compose < 2.0.0. If you need to use it with the docker_compose module, please install that requirement manually (#400).
  • Support for Ansible 2.9 and ansible-base 2.10 has been removed. If you need support for Ansible 2.9 or ansible-base 2.10, please use community.docker 2.x.y (#400).
  • Support for Docker API versions 1.20 to 1.24 has been removed. If you need support for these API versions, please use community.docker 2.x.y (#400).
  • Support for Python 2.6 has been removed. If you need support for Python 2.6, please use community.docker 2.x.y (#400).
  • Various modules - the default of tls_hostname (localhost) has been removed. If you want to continue using localhost, you need to specify it explicitly (#363).
  • docker_container - the all value is no longer allowed in published_ports. Use publish_all_ports=true instead (#399).
  • docker_container - the default of command_handling was changed from compatibility to correct. Older versions were warning for every invocation of the module when this would result in a change of behavior (#399).
  • docker_stack - the return values out and err have been removed. Use stdout and stderr instead (#363).

Security Fixes

  • modules and plugins communicating directly with the Docker daemon - when connecting by SSH and not using use_ssh_client=true, reject unknown host keys instead of accepting them. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).

Bugfixes

  • docker_image - when composing the build context, trim trailing whitespace from .dockerignore entries. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).
  • docker_plugin - fix crash when handling plugin options (#446, #447).
  • docker_stack - fix broken string formatting when reporting error in case compose was containing invalid values (#448).
  • modules and plugins communicating directly with the Docker daemon - do not create a subshell for SSH connections when using use_ssh_client=true. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).
  • modules and plugins communicating directly with the Docker daemon - fix ProxyCommand handling for SSH connections when not using use_ssh_client=true. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).
  • modules and plugins communicating directly with the Docker daemon - fix parsing of IPv6 addresses with a port in docker_host. This is only a change relative to older community.docker 3.0.0 pre-releases or with respect to Docker SDK for Python < 6.0.0. Docker SDK for Python 6.0.0 will also include this change (#434).
  • modules and plugins communicating directly with the Docker daemon - prevent crash when TLS is used (#432).

v2.7.0

Release Summary

Bugfix and deprecation release. The next 2.x.y releases will only be bugfix releases, the next expect minor/major release will be 3.0.0 with some major changes.

Minor Changes

  • Move common utility functions from the common module_util to a new module_util called util. This should not have any user-visible effect (#390).

Deprecated Features

  • Support for Docker API version 1.20 to 1.24 has been deprecated and will be removed in community.docker 3.0.0. The first Docker version supporting API version 1.25 was Docker 1.13, released in January 2017. This affects the modules docker_container, docker_container_exec, docker_container_info, docker_compose, docker_login, docker_image, docker_image_info, docker_image_load, docker_host_info, docker_network, docker_network_info, docker_node_info, docker_swarm_info, docker_swarm_service, docker_swarm_service_info, docker_volume_info, and docker_volume, whose minimally supported API version is between 1.20 and 1.24 (#396).
  • Support for Python 2.6 is deprecated and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with Python 2.6, but we will no longer try to ensure compatibility (#388).

Bugfixes

  • Docker SDK for Python based modules and plugins - if the API version is specified as an option, use that one to validate API version requirements of module/plugin options instead of the latest API version supported by the Docker daemon. This also avoids one unnecessary API call per module/plugin (#389).

v2.6.0

Release Summary

Bugfix and feature release.

Minor Changes

  • docker_container - added image_label_mismatch parameter (#314, #370).

Deprecated Features

  • Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.docker 3.0.0). Some modules might still work with these versions afterwards, but we will no longer keep compatibility code that was needed to support them (#361).
  • The dependency on docker-compose for Execution Environments is deprecated and will be removed in community.docker 3.0.0. The Python docker-compose library is unmaintained and can cause dependency issues. You can manually still install it in an Execution Environment when needed (#373).
  • Various modules - the default of tls_hostname that was supposed to be removed in community.docker 2.0.0 will now be removed in version 3.0.0 (#362).
  • docker_stack - the return values out and err that were supposed to be removed in community.docker 2.0.0 will now be removed in version 3.0.0 (#362).

Bugfixes

  • docker_container - fail with a meaningful message instead of crashing if a port is specified with more than three colon-separated parts (#367, #365).
  • docker_container - remove unused code that will cause problems with Python 3.13 (#354).

v2.5.1

Release Summary

Maintenance release.

Bugfixes

  • Include PSF-license.txt file for plugins/module_utils/_version.py.

v2.5.0

Release Summary

Regular feature release.

Minor Changes

  • docker_config - add support for template_driver with one option golang (#332, #345).
  • docker_swarm - adds data_path_addr parameter during swarm initialization or when joining (#339).

v2.4.0

Release Summary

Regular feature and bugfix release.

Minor Changes

  • Prepare collection for inclusion in an Execution Environment by declaring its dependencies. The docker_stack* modules are not supported (#336).
  • current_container_facts - add detection for GitHub Actions (#336).
  • docker_container - support returning Docker container log output when using Docker's local logging driver, an optimized local logging driver introduced in Docker 18.09 (#337).

Bugfixes

  • docker connection plugin - make sure that docker_extra_args is used for querying the Docker version. Also ensures that the Docker version is only queried when needed. This is currently the case if a remote user is specified (#325, #327).

v2.3.0

Release Summary

Regular feature and bugfix release.

Minor Changes

  • docker connection plugin - implement connection reset by clearing internal container user cache (#312).
  • docker connection plugin - simplify actual_user handling code (#311).
  • docker connection plugin - the plugin supports new ways to define the timeout. These are the ANSIBLE_DOCKER_TIMEOUT environment variable, the timeout setting in the docker_connection section of ansible.cfg, and the ansible_docker_timeout variable (#297).
  • docker_api connection plugin - implement connection reset by clearing internal container user/group ID cache (#312).
  • docker_api connection plugin - the plugin supports new ways to define the timeout. These are the ANSIBLE_DOCKER_TIMEOUT environment variable, the timeout setting in the docker_connection section of ansible.cfg, and the ansible_docker_timeout variable (#308).

Bugfixes

  • docker connection plugin - fix option handling to be compatible with ansible-core 2.13 (#297, #307).
  • docker_api connection plugin - fix option handling to be compatible with ansible-core 2.13 (#308).

v2.2.1

Release Summary

Regular bugfix release.

Bugfixes

  • docker_compose - fix Python 3 type error when extracting warnings or errors from docker-compose's output (#305).

v2.2.0

Release Summary

Regular feature and bugfix release.

Minor Changes

  • docker_config - add support for rolling update, set rolling_versions to true to enable (#295, #109).
  • docker_secret - add support for rolling update, set rolling_versions to true to enable (#293, #21).
  • docker_swarm_service - add support for setting capabilities with the cap_add and cap_drop parameters. Usage is the same as with the capabilities and cap_drop parameters for docker_container (#294).

Bugfixes

  • docker_container, docker_image - adjust image finding code to peculiarities of podman-docker's API emulation when Docker short names like redis are used (#292).

v2.1.1

Release Summary

Emergency release to amend breaking change in previous release.

Bugfixes

  • Fix unintended breaking change caused by an earlier fix by vendoring the deprecated Python standard library distutils.version until this collection stops supporting Ansible 2.9 and ansible-base 2.10 (#267, #269).

v2.1.0

Release Summary

Feature and bugfix release.

Minor Changes

  • docker_container_exec - add detach parameter (#250, #255).
  • docker_container_exec - add env option (#248, #254).

Bugfixes

  • Various modules and plugins - use vendored version of distutils.version included in ansible-core 2.12 if available. This avoids breakage when distutils is removed from the standard library of Python 3.12. Note that ansible-core 2.11, ansible-base 2.10 and Ansible 2.9 are right now not compatible with Python 3.12, hence this fix does not target these ansible-core/-base/2.9 versions (#258).
  • docker connection plugin - replace deprecated distutils.spawn.find_executable with Ansible's get_bin_path to find the docker executable (#257).
  • docker_container_exec - disallow using the chdir option for Docker API before 1.35 (#253).

v2.0.2

Release Summary

Bugfix release.

Bugfixes

  • docker_api connection plugin - avoid passing an unnecessary argument to a Docker SDK for Python call that is only supported by version 3.0.0 or later (#243).
  • docker_container_exec - chdir is only supported since Docker SDK for Python 3.0.0. Make sure that this option can only use when 3.0.0 or later is installed, and prevent passing this parameter on when chdir is not provided to this module (#243, #242).
  • nsenter connection plugin - ensure the nsenter_pid option is retrieved in _connect instead of __init__ to prevent a crash due to bad initialization order (#249).
  • nsenter connection plugin - replace the use of --all-namespaces with specific namespaces to support compatibility with Busybox nsenter (used on, for example, Alpine containers) (#249).

v2.0.1

Release Summary

Maintenance release with some documentation fixes.

v2.0.0

Release Summary

New major release with some deprecations removed and a breaking change in the docker_compose module regarding the timeout parameter.

Breaking Changes / Porting Guide

  • docker_compose - fixed timeout defaulting behavior so that stop_grace_period, if defined in the compose file, will be used if timeout is not specified (#163).

Deprecated Features

  • docker_container - using the special value all in published_ports has been deprecated. Use publish_all_ports=true instead (#210).

Removed Features (previously deprecated)

  • docker_container - the default value of container_default_behavior changed to no_defaults (#210).
  • docker_container - the default value of network_mode is now the name of the first network specified in networks if such are specified and networks_cli_compatible=true (#210).
  • docker_container - the special value all can no longer be used in published_ports next to other values. Please use publish_all_ports=true instead (#210).
  • docker_login - removed the email option (#210).

v1.10.0

Release Summary

Regular feature and bugfix release.

Minor Changes

  • Add the modules docker_container_exec, docker_image_load and docker_plugin to the docker module defaults group (#209).
  • docker_config - add option data_src to read configuration data from target (#64, #203).
  • docker_secret - add option data_src to read secret data from target (#64, #203).

v1.9.1

Release Summary

Regular bugfix release.

Bugfixes

  • docker_compose - fixed incorrect changed status for services with profiles defined, but none enabled (#192).

v1.9.0

Release Summary

New bugfixes and features release.

Minor Changes

  • docker_* modules - include ImportError traceback when reporting that Docker SDK for Python could not be found (#188).
  • docker_compose - added env_file option for specifying custom environment files (#174).
  • docker_container - added publish_all_ports option to publish all exposed ports to random ports except those explicitly bound with published_ports (this was already added in community.docker 1.8.0) (#162).
  • docker_container - added new command_handling option with current deprecated default value compatibility which allows to control how the module handles shell quoting when interpreting lists, and how the module handles empty lists/strings. The default will switch to correct in community.docker 3.0.0 (#186).
  • docker_container - lifted restriction preventing the creation of anonymous volumes with the mounts option (#181).

Deprecated Features

  • docker_container - the new command_handling's default value, compatibility, is deprecated and will change to correct in community.docker 3.0.0. A deprecation warning is emitted by the module in cases where the behavior will change. Please note that ansible-core will output a deprecation warning only once, so if it is shown for an earlier task, there could be more tasks with this warning where it is not shown (#186).

Bugfixes

  • docker_compose - fixes task failures when bringing up services while using docker-compose <1.17.0 (#180).
  • docker_container - make sure to also return container on detached=false when status code is non-zero (#178).
  • docker_stack_info - make sure that module isn't skipped in check mode (#183).
  • docker_stack_task_info - make sure that module isn't skipped in check mode (#183).

New Plugins

Connection

  • community.docker.nsenter - execute on host running controller container

v1.8.0

Release Summary

Regular bugfix and feature release.

Minor Changes

  • Avoid internal ansible-core module_utils in favor of equivalent public API available since at least Ansible 2.9 (#164).
  • docker_compose - added profiles option to specify service profiles when starting services (#167).
  • docker_containers inventory plugin - when connection_type=docker-api, now pass Docker daemon connection options from inventory plugin to connection plugin. This can be disabled by setting configure_docker_daemon=false (#157).
  • docker_host_info - allow values for keys in containers_filters, images_filters, networks_filters, and volumes_filters to be passed as YAML lists (#160).
  • docker_plugin - added alias option to specify local names for docker plugins (#161).

Bugfixes

  • docker_compose - fix idempotence bug when using stopped: true (#142, #159).

v1.7.0

Release Summary

Small feature and bugfix release.

Minor Changes

  • docker_image - allow to tag images by ID (#149).

v1.6.1

Release Summary

Bugfix release to reduce deprecation warning spam.

Bugfixes

  • docker_* modules and plugins, except docker_swarm connection plugin and docker_compose and docker_stack*` modules - only emit ``tls_hostname deprecation message if TLS is actually used (#143).

v1.6.0

Release Summary

Regular bugfix and feature release.

Minor Changes

  • common module utils - correct error messages for guiding to install proper Docker SDK for Python module (#125).
  • docker_container - allow memory_swap: -1 to set memory swap limit to unlimited. This is useful when the user cannot set memory swap limits due to cgroup limitations or other reasons, as by default Docker will try to set swap usage to two times the value of memory (#138).

Deprecated Features

  • docker_* modules and plugins, except docker_swarm connection plugin and docker_compose and docker_stack*` modules - the current default ``localhost for tls_hostname is deprecated. In community.docker 2.0.0 it will be computed from docker_host instead (#134).

Bugfixes

  • docker-compose - fix not pulling when state: present and stopped: true (#12, #119).
  • docker_plugin - also configure plugin after installing (#118, #135).
  • docker_swarm_services - avoid crash during idempotence check if published_port is not specified (#107, #136).

v1.5.0

Release Summary

Regular feature release.

Minor Changes

  • Add the use_ssh_client option to most docker modules and plugins (#108, #114).

Bugfixes

  • all modules - use to_native to convert exceptions to strings (#121).

New Modules

  • community.docker.docker_container_exec - Execute command in a docker container

v1.4.0

Release Summary

Security release to address another potential secret leak. Also includes regular bugfixes and features.

Minor Changes

  • docker_swarm_service - change publish.published_port option from mandatory to optional. Docker will assign random high port if not specified (#99).

Breaking Changes / Porting Guide

  • docker_swarm - if join_token is specified, a returned join token with the same value will be replaced by VALUE_SPECIFIED_IN_NO_LOG_PARAMETER. Make sure that you do not blindly use the join tokens from the return value of this module when the module is invoked with join_token specified! This breaking change appears in a minor release since it is necessary to fix a security issue (#103).

Security Fixes

  • docker_swarm - the join_token option is now marked as no_log so it is no longer written into logs (#103).

Bugfixes

  • docker_swarm_service - fix KeyError on caused by reference to deprecated option update_failure_action (#100).
  • docker_swarm_service - mark secrets module option with no_log=False since it does not leak secrets (ansible-collections/community.general#2001).

v1.3.0

Release Summary

Regular feature and bugfix release.

Minor Changes

  • docker_container - add storage_opts option to specify storage options (#91, #93).
  • docker_image - allows to specify platform to pull for source=pull with new option pull_platform (#79, #89).
  • docker_image - properly support image IDs (hashes) for loading and tagging images (#86, #87).
  • docker_swarm_service - adding support for maximum number of tasks per node (replicas_max_per_node) when running swarm service in replicated mode. Introduced in API 1.40 (#7, #92).

Bugfixes

  • docker_container - fix healthcheck disabling idempotency issue with strict comparison (#85).
  • docker_image - prevent module failure when removing image that is removed between inspection and removal (#87).
  • docker_image - prevent module failure when removing non-existent image by ID (#87).
  • docker_image_info - prevent module failure when image vanishes between listing and inspection (#87).
  • docker_image_info - prevent module failure when querying non-existent image by ID (#87).

New Modules

  • community.docker.docker_image_load - Load docker image(s) from archives
  • community.docker.docker_plugin - Manage Docker plugins

v1.2.2

Release Summary

Security bugfix release to address CVE-2021-20191.

Security Fixes

  • docker_swarm - enabled no_log for the option signing_ca_key to prevent accidental disclosure (CVE-2021-20191, #80).

v1.2.1

Release Summary

Bugfix release.

Bugfixes

  • docker connection plugin - fix Docker version parsing, as some docker versions have a leading v in the output of the command docker version --format "{{.Server.Version}}" (#76).

v1.2.0

Release Summary

Feature release with one new feature and two bugfixes.

Minor Changes

  • docker_container - added default_host_ip option which allows to explicitly set the default IP string for published ports without explicitly specified IPs. When using IPv6 binds with Docker 20.10.2 or newer, this needs to be set to an empty string ("") (#70, #71).

Bugfixes

  • docker_container - allow IPv6 zones (RFC 4007) in bind IPs (#66).
  • docker_image - fix crash on loading images with versions of Docker SDK for Python before 2.5.0 (#72, #73).

v1.1.0

Release Summary

Feature release with three new plugins and modules.

Minor Changes

  • docker_container - support specifying cgroup_parent (#6, #59).
  • docker_container - when a container is started with detached=false, status is now also returned when it is 0 (#26, #58).
  • docker_image - support platform when building images (#22, #54).

Deprecated Features

  • docker_container - currently published_ports can contain port mappings next to the special value all, in which case the port mappings are ignored. This behavior is deprecated for community.docker 2.0.0, at which point it will either be forbidden, or this behavior will be properly implemented similar to how the Docker CLI tool handles this (#8, #60).

Bugfixes

  • docker_image - if push=true is used with repository, and the image does not need to be tagged, still push. This can happen if repository and name are equal (#52, #53).
  • docker_image - report error when loading a broken archive that contains no image (#46, #55).
  • docker_image - report error when the loaded archive does not contain the specified image (#41, #55).

New Plugins

Connection

  • community.docker.docker_api - Run tasks in docker containers

Inventory

  • community.docker.docker_containers - Ansible dynamic inventory plugin for Docker containers.

New Modules

  • community.docker.current_container_facts - Return facts about whether the module runs in a Docker container

v1.0.1

Release Summary

Maintenance release with a bugfix for docker_container.

Bugfixes

  • docker_container - the validation for capabilities in device_requests was incorrect (#42, #43).

v1.0.0

Release Summary

This is the first production (non-prerelease) release of community.docker.

Minor Changes

  • Add collection-side support of the docker action group / module defaults group (#17).
  • docker_image - return docker build output (ansible-collections/community.general#805).
  • docker_secret - add a warning when the secret does not have an ansible_key label but the force parameter is not set (#30, #31).

v0.1.0

Release Summary

The community.docker continues the work on the Ansible docker modules and plugins from their state in community.general 1.2.0. The changes listed here are thus relative to the modules and plugins community.general.docker*.

All deprecation removals planned for community.general 2.0.0 have been applied. All deprecation removals scheduled for community.general 3.0.0 have been re-scheduled for community.docker 2.0.0.

Minor Changes

Removed Features (previously deprecated)

  • docker_container - no longer returns ansible_facts (#1).
  • docker_container - the default of networks_cli_compatible changed to true (#1).
  • docker_container - the unused option trust_image_content has been removed (#1).
  • docker_image - state=build has been removed. Use present instead (#1).
  • docker_image - the container_limits, dockerfile, http_timeout, nocache, rm, path, buildargs, pull have been removed. Use the corresponding suboptions of build instead (#1).
  • docker_image - the force option has been removed. Use the more specific force_* options instead (#1).
  • docker_image - the source option is now mandatory (#1).
  • docker_image - the use_tls option has been removed. Use tls and validate_certs instead (#1).
  • docker_image - the default of the build.pull option changed to false (#1).
  • docker_image_facts - this alias is on longer available, use docker_image_info instead (#1).
  • docker_network - no longer returns ansible_facts (#1).
  • docker_network - the ipam_options option has been removed. Use ipam_config instead (#1).
  • docker_service - no longer returns ansible_facts (#1).
  • docker_swarm - state=inspect has been removed. Use docker_swarm_info instead (#1).
  • docker_swarm_service - the constraints option has been removed. Use placement.constraints instead (#1).
  • docker_swarm_service - the limit_cpu and limit_memory options has been removed. Use the corresponding suboptions in limits instead (#1).
  • docker_swarm_service - the log_driver and log_driver_options options has been removed. Use the corresponding suboptions in logging instead (#1).
  • docker_swarm_service - the reserve_cpu and reserve_memory options has been removed. Use the corresponding suboptions in reservations instead (#1).
  • docker_swarm_service - the restart_policy, restart_policy_attempts, restart_policy_delay and restart_policy_window options has been removed. Use the corresponding suboptions in restart_config instead (#1).
  • docker_swarm_service - the update_delay, update_parallelism, update_failure_action, update_monitor, update_max_failure_ratio and update_order options has been removed. Use the corresponding suboptions in update_config instead (#1).
  • docker_volume - no longer returns ansible_facts (#1).
  • docker_volume - the force option has been removed. Use recreate instead (#1).

Bugfixes