ansible / ansible.builtin / v2.6.17 / module / docker_service Manage docker services and containers. | "added in version" 2.1 of ansible.builtin" Authors: Chris Houseknecht (@chouseknecht) preview | supported by communityansible.builtin.docker_service (v2.6.17) — module
pip
Install with pip install ansible==2.6.17
Consumes docker compose to start, shutdown and scale services.
Works with compose versions 1 and 2.
Compose can be read from a docker-compose.yml (or .yaml) file or inline using the C(definition) option.
See the examples for more details.
Supports check mode.
# Examples use the django example at U(https://docs.docker.com/compose/django/). Follow it to create the flask # directory - name: Run using a project directory hosts: localhost connection: local gather_facts: no tasks: - docker_service: project_src: flask state: absent - docker_service: project_src: flask register: output - debug: var: output - docker_service: project_src: flask build: no register: output - debug: var: output - assert: that: "not output.changed " - docker_service: project_src: flask build: no stopped: true register: output - debug: var: output - assert: that: - "not web.flask_web_1.state.running" - "not db.flask_db_1.state.running" - docker_service: project_src: flask build: no restarted: true register: output - debug: var: output - assert: that: - "web.flask_web_1.state.running" - "db.flask_db_1.state.running"
- name: Scale the web service to 2 hosts: localhost connection: local gather_facts: no tasks: - docker_service: project_src: flask scale: web: 2 register: output - debug: var: output
- name: Run with inline v2 compose hosts: localhost connection: local gather_facts: no tasks: - docker_service: project_src: flask state: absent - docker_service: project_name: flask definition: version: '2' services: db: image: postgres web: build: "{{ playbook_dir }}/flask" command: "python manage.py runserver 0.0.0.0:8000" volumes: - "{{ playbook_dir }}/flask:/code" ports: - "8000:8000" depends_on: - db register: output - debug: var: output - assert: that: - "web.flask_web_1.state.running" - "db.flask_db_1.state.running"
- name: Run with inline v1 compose hosts: localhost connection: local gather_facts: no tasks: - docker_service: project_src: flask state: absent - docker_service: project_name: flask definition: db: image: postgres web: build: "{{ playbook_dir }}/flask" command: "python manage.py runserver 0.0.0.0:8000" volumes: - "{{ playbook_dir }}/flask:/code" ports: - "8000:8000" links: - db register: output - debug: var: output - assert: that: - "web.flask_web_1.state.running" - "db.flask_db_1.state.running"
tls: default: false description: - Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. Note that if I(validate_certs) is set to C(yes) as well, it will take precedence. - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS) will be used instead. If the environment variable is not set, the default value will be used. type: bool pull: default: 'no' description: - Use with state I(present) to always pull images prior to starting the application. - Same as running docker-compose pull. - When a new image is pulled, services using the image will be recreated unless C(recreate) is I(never). type: bool version_added: '2.2' version_added_collection: ansible.builtin build: default: 'no' description: - Use with state I(present) to always build images prior to starting the application. - Same as running docker-compose build with the pull option. - Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents. - Use the C(nocache) option to ignore the image cache when performing the build. - If an existing image is replaced, services using the image will be recreated unless C(recreate) is I(never). type: bool debug: default: false description: - Debug mode type: bool files: description: - List of file names relative to C(project_src). Overrides docker-compose.yml or docker-compose.yaml. - Files are loaded and merged in the order given. scale: description: - When C(state) is I(present) scale services. Provide a dictionary of key/value pairs where the key is the name of the service and the value is an integer count for the number of containers. state: choices: - absent - present default: present description: - Desired state of the project. - Specifying I(present) is the same as running I(docker-compose up). - Specifying I(absent) is the same as running I(docker-compose down). ca_cert: aliases: - tls_ca_cert - cacert_path description: - Use a CA certificate when performing server verification by providing the path to a CA certificate file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(ca.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path nocache: default: 'no' description: - Use with the build option to ignore the cache during the image build process. type: bool version_added: '2.2' version_added_collection: ansible.builtin stopped: default: 'no' description: - Use with state I(present) to leave the containers in an exited or non-running state. type: bool timeout: default: 10 description: - timeout in seconds for container shutdown when attached or when containers are already running. type: int recreate: choices: - always - never - smart default: smart description: - By default containers will be recreated when their configuration differs from the service definition. - Setting to I(never) ignores configuration differences and leaves existing containers unchanged. - Setting to I(always) forces recreation of all existing containers. required: false services: description: - When C(state) is I(present) run I(docker-compose up) on a subset of services. restarted: default: 'no' description: - Use with state I(present) to restart all containers. type: bool client_key: aliases: - tls_client_key - key_path description: - Path to the client's TLS key file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(key.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path definition: description: - Provide docker-compose yaml describing one or more services, networks and volumes. - Mutually exclusive with C(project_src) and C(files). api_version: aliases: - docker_api_version default: auto description: - The version of the Docker API running on the Docker Host. - Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon. - If the value is not specified in the task, the value of environment variable C(DOCKER_API_VERSION) will be used instead. If the environment variable is not set, the default value will be used. type: str client_cert: aliases: - tls_client_cert - cert_path description: - Path to the client's TLS certificate file. - If the value is not specified in the task and the environment variable C(DOCKER_CERT_PATH) is set, the file C(cert.pem) from the directory specified in the environment variable C(DOCKER_CERT_PATH) will be used. type: path docker_host: aliases: - docker_url default: unix://var/run/docker.sock description: - The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, C(tcp://192.0.2.23:2376). If TLS is used to encrypt the connection, the module will automatically replace C(tcp) in the connection URL with C(https). - If the value is not specified in the task, the value of environment variable C(DOCKER_HOST) will be used instead. If the environment variable is not set, the default value will be used. type: str project_src: description: - Path to a directory containing a docker-compose.yml or docker-compose.yaml file. - Mutually exclusive with C(definition). - Required when no C(definition) is provided. ssl_version: description: - Provide a valid SSL version number. Default value determined by ssl.py module. - If the value is not specified in the task, the value of environment variable C(DOCKER_SSL_VERSION) will be used instead. type: str dependencies: default: 'yes' description: - When C(state) is I(present) specify whether or not to include linked services. type: bool project_name: description: - Provide a project name. If not provided, the project name is taken from the basename of C(project_src). - Required when C(definition) is provided. tls_hostname: description: - 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 C(DOCKER_TLS_HOSTNAME) will be used instead. If the environment variable is not set, the default value will be used. - The current default value is C(localhost). This default is deprecated and will change in community.docker 2.0.0 to be a value computed from I(docker_host). Explicitly specify C(localhost) to make sure this value will still be used, and to disable the deprecation message which will be shown otherwise. type: str remove_images: choices: - all - local description: - Use with state I(absent) to remove the all images or only local images. hostname_check: default: 'no' description: - Whether or not to check the Docker daemon's hostname against the name provided in the client certificate. type: bool remove_orphans: default: false description: - Remove containers for services not defined in the compose file. type: bool remove_volumes: default: 'no' description: - Use with state I(absent) to remove data volumes. type: bool use_ssh_client: default: false description: - For SSH transports, use the C(ssh) CLI tool instead of paramiko. - Requires Docker SDK for Python 4.4.0 or newer. type: bool version_added: 1.5.0 version_added_collection: community.docker validate_certs: aliases: - tls_verify default: false description: - Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. - If the value is not specified in the task, the value of environment variable C(DOCKER_TLS_VERIFY) will be used instead. If the environment variable is not set, the default value will be used. type: bool
actions: contains: service_name: contains: action: contains: id: description: the container's long ID returned: always type: string name: description: the container's name returned: always type: string short_id: description: the container's short ID returned: always type: string description: A descriptive name of the action to be performed on the service's containers. returned: always type: list built_image: contains: id: description: image hash returned: always type: string name: description: name of the image returned: always type: string description: Provides image details when a new image is built for the service. returned: on image build type: complex pulled_image: contains: id: description: image hash returned: always type: string name: description: name of the image returned: always type: string description: Provides image details when a new image is pulled for the service. returned: on image pull type: complex description: Name of the service. returned: always type: complex description: Provides the actions to be taken on each service as determined by compose. returned: when in check mode or I(debug) true type: complex service: contains: container_name: contains: cmd: description: One or more commands to be executed in the container. example: - postgres returned: success type: list image: description: Name of the image from which the container was built. example: postgres returned: success type: str labels: description: Meta data assigned to the container. example: '...': null returned: success type: complex networks: contains: IPAddress: description: The IP address assigned to the container. example: 172.17.0.2 returned: success type: string IPPrefixLen: description: Number of bits used by the subnet. example: 16 returned: success type: int aliases: description: Aliases assigned to the container by the network. example: - db returned: success type: list globalIPv6: description: IPv6 address assigned to the container. example: '' returned: success type: str globalIPv6PrefixLen: description: IPv6 subnet length. example: 0 returned: success type: int links: description: List of container names to which this container is linked. example: null returned: success type: list macAddress: description: Mac Address assigned to the virtual NIC. example: 02:42:ac:11:00:02 returned: success type: str description: Contains a dictionary for each network to which the container is a member. returned: success type: complex state: contains: running: description: Whether or not the container is up with a running process. example: true returned: success type: bool status: description: Description of the running state. example: running returned: success type: str description: Information regarding the current disposition of the container. returned: success type: complex description: Name of the container. Format is I(project_service_#). returned: success type: complex description: Name of the service. returned: success type: complex