AnsibleByExample

community.docker 5.3.0 Released - Whats New and How to Test

Beginner
2024-01-013By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

community.docker 5.3.0 Released - Whats New and How to Test

Introduction

community.docker is the Ansible collection that provides modules and plugins for managing Docker containers, images, networks, volumes, and Docker Swarm resources. It is one of the most widely used community collections and is included by default in the ansible community package. Version 5.3.0 has just been published on Ansible Galaxy and is available for installation.

This is a feature release. The changelog lists a single minor change affecting the docker_swarm_service module, described below, together with the practical steps to install and verify the new version.

Whats New

docker_swarm_service - new command_as_args option

The docker_swarm_service module gains a new boolean option, command_as_args. When set to true, the module concatenates command and args and maps the result to ContainerSpec.Args, mirroring the behavior of docker service create IMAGE [COMMAND] [ARG...] and preserving the image's ENTRYPOINT.

The default value remains false, which keeps the historical, and arguably surprising, mapping in place: command is mapped to ContainerSpec.Command and args to ContainerSpec.Args. This default is kept for backward compatibility, so existing playbooks are not affected unless the new option is explicitly enabled.

This change closes two long-standing issues:

  • Addresses the mismatch between Ansible's command/args handling and the native docker service create CLI behavior, reported in issue #1044 and issue #212.
  • Implemented via PR #1307.

Users who need docker_swarm_service to behave like the Docker CLI when both command and image ENTRYPOINT are involved should set command_as_args: true in their task definition.

Summary Table

ComponentChangeReference
docker_swarm_serviceNew command_as_args option, default falseissue #1044, issue #212, PR #1307

How to Test

Install the collection from Ansible Galaxy and confirm the version, then exercise the new option against a Swarm service.

# Install or upgrade community.docker to 5.3.0
ansible-galaxy collection install community.docker:5.3.0

# Verify the installed version
ansible-galaxy collection list community.docker

# Check the module documentation for the new option
ansible-doc community.docker.docker_swarm_service | grep -A 5 command_as_args

Example task exercising the new option:

- name: Create a swarm service preserving image ENTRYPOINT
  community.docker.docker_swarm_service:
    name: myservice
    image: myimage:latest
    command: myscript.sh
    args:
      - --flag
    command_as_args: true

Run the playbook in check mode first to confirm the resulting service spec matches expectations before applying it to a production Swarm cluster.

ansible-playbook test-swarm-service.yml --check --diff

Conclusion

community.docker 5.3.0 is a small but useful release for anyone managing Docker Swarm services through Ansible. The new command_as_args option gives users an explicit, opt-in way to match native docker service create semantics without breaking existing automation that relies on the historical mapping.

All Tutorials