community.docker.docker connection – Run tasks in docker containers

Note

This connection plugin is part of the community.docker collection (version 4.7.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.docker.

To use it in a playbook, specify: community.docker.docker.

Synopsis

  • Run commands or put/fetch files to an existing docker container.

  • Uses the Docker CLI to execute commands in the container. If you prefer to directly connect to the Docker daemon, use the community.docker.docker_api connection plugin.

Parameters

Parameter

Comments

container_timeout

integer

Controls how long we can wait to access reading output from the container once execution started.

Default: 10

Configuration:

  • INI entries:

    [defaults]
timeout = 10

    [docker_connection]
timeout = 10

    added in community.docker 2.2.0

  • Environment variable: ANSIBLE_TIMEOUT

  • Environment variable: ANSIBLE_DOCKER_TIMEOUT

    added in community.docker 2.2.0

  • CLI argument: –timeout

  • Variable: ansible_docker_timeout

    added in community.docker 2.2.0

docker_extra_args

string

Extra arguments to pass to the docker command line.

Default: ""

Configuration:

  • INI entry:

    [docker_connection]
extra_cli_args = ""

  • Variable: ansible_docker_extra_args

extra_env

dictionary

added in community.docker 3.12.0

Provide extra environment variables to set when running commands in the Docker container.

This option can currently only be provided as Ansible variables due to limitations of ansible-core’s configuration manager.

Configuration:

  • Variable: ansible_docker_extra_env

privileged

boolean

added in community.docker 3.12.0

Whether commands should be run with extended privileges.

Note that this allows command to potentially break out of the container. Use with care!

Choices:

  • false ← (default)

  • true

Configuration:

  • INI entry:

    [docker_connection]
privileged = false

  • Environment variable: ANSIBLE_DOCKER_PRIVILEGED

  • Variable: ansible_docker_privileged

remote_addr

string

The name of the container you want to access.

Default: "inventory_hostname"

Configuration:

  • Variable: inventory_hostname

  • Variable: ansible_host

  • Variable: ansible_docker_host

remote_user

string

The user to execute as inside the container.

If Docker is too old to allow this (< 1.7), the one set by Docker itself will be used.

Configuration:

  • INI entry:

    [defaults]
remote_user = VALUE

  • Environment variable: ANSIBLE_REMOTE_USER

  • CLI argument: –user

  • Keyword: remote_user

  • Variable: ansible_user

  • Variable: ansible_docker_user

working_dir

string

added in community.docker 3.12.0

The directory inside the container to run commands in.

Requires Docker CLI version 18.06 or later.

Configuration:

  • INI entry:

    [docker_connection]
working_dir = VALUE

  • Environment variable: ANSIBLE_DOCKER_WORKING_DIR

  • Variable: ansible_docker_working_dir

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Authors

  • Lorin Hochestein

  • Leendert Brouwer