ansible / ansible.builtin / v2.8.15 / module / _docker_service Manage multi-container Docker applications with Docker Compose. | "added in version" 2.1 of ansible.builtin" Authors: Chris Houseknecht (@chouseknecht) preview | supported by communityansible.builtin._docker_service (v2.8.15) — module
pip
Install with pip install ansible==2.8.15
Uses Docker Compose to start, shutdown and scale services.
Works with compose versions 1 and 2.
Configuration can be read from a C(docker-compose.yml) or C(docker-compose.yaml) file or inline using the I(definition) option.
See the examples for more details.
Supports check mode.
This module was called C(docker_service) before Ansible 2.8. The usage did not change.
# Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the # flask directory - name: Run using a project directory hosts: localhost gather_facts: no tasks: - name: Tear down existing services docker_compose: project_src: flask state: absent - name: Create and start services docker_compose: project_src: flask register: output - debug: var: output - name: Run `docker-compose up` again docker_compose: project_src: flask build: no register: output - debug: var: output - assert: that: "not output.changed " - name: Stop all services docker_compose: project_src: flask build: no stopped: yes register: output - debug: var: output - assert: that: - "not web.flask_web_1.state.running" - "not db.flask_db_1.state.running" - name: Restart services docker_compose: project_src: flask build: no restarted: yes 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 gather_facts: no tasks: - docker_compose: project_src: flask scale: web: 2 register: output - debug: var: output
- name: Run with inline v2 compose hosts: localhost gather_facts: no tasks: - docker_compose: project_src: flask state: absent - docker_compose: 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 gather_facts: no tasks: - docker_compose: project_src: flask state: absent - docker_compose: 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: false description: - Use with I(state) C(present) to always pull images prior to starting the application. - Same as running C(docker-compose pull). - When a new image is pulled, services using the image will be recreated unless I(recreate) is C(never). type: bool version_added: '2.2' version_added_collection: ansible.builtin build: default: false description: - Use with I(state) C(present) to always build images prior to starting the application. - Same as running C(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 I(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 I(recreate) is C(never). type: bool debug: default: false description: - Debug mode type: bool files: description: - List of Compose file names relative to I(project_src). Overrides C(docker-compose.yml) or C(docker-compose.yaml). - Files are loaded and merged in the order given. type: list scale: description: - When I(state) is C(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. type: dict state: choices: - absent - present default: present description: - Desired state of the project. - Specifying C(present) is the same as running C(docker-compose up) resp. C(docker-compose stop) (with I(stopped)) resp. C(docker-compose restart) (with I(restarted)). - Specifying C(absent) is the same as running C(docker-compose down). type: str 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: false description: - Use with the I(build) option to ignore the cache during the image build process. type: bool version_added: '2.2' version_added_collection: ansible.builtin stopped: default: false description: - Use with I(state) C(present) to stop all containers defined in the Compose file. - If I(services) is defined, only the containers listed there will be stopped. 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 C(never) ignores configuration differences and leaves existing containers unchanged. - Setting to C(always) forces recreation of all existing containers. type: str services: description: - When I(state) is C(present) run C(docker-compose up) resp. C(docker-compose stop) (with I(stopped)) resp. C(docker-compose restart) (with I(restarted)) on a subset of services. - If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline I(definition)). type: list restarted: default: false description: - Use with I(state) C(present) to restart all containers defined in the Compose file. - If I(services) is defined, only the containers listed there will be restarted. 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: - Compose file describing one or more services, networks and volumes. - Mutually exclusive with I(project_src) and I(files). type: dict 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 C(docker-compose.yml) or C(docker-compose.yaml) file. - Mutually exclusive with I(definition). - Required when no I(definition) is provided. type: path 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: true description: - When I(state) is C(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 I(project_src). - Required when I(definition) is provided. type: str tls_hostname: default: localhost 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. type: str remove_images: choices: - all - local description: - Use with I(state) C(absent) to remove all images or only local images. type: str hostname_check: default: false 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: false description: - Use with I(state) C(absent) to remove data volumes. type: bool 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: str name: description: the container's name returned: always type: str short_id: description: the container's short ID returned: always type: str 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: str name: description: name of the image returned: always type: str 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: str name: description: name of the image returned: always type: str 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) is C(yes) type: complex services: 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: str 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 C(project_service_#). returned: success type: complex description: - A dictionary mapping the service's name to a dictionary of containers. - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts are also accessible directly. The service's name is the variable with which the container dictionary can be accessed. Note that the returned facts will be removed in Ansible 2.12. returned: success type: complex