community / community.docker / 3.8.1 / module / docker_compose_v2 Manage multi-container Docker applications with Docker Compose CLI plugin | "added in version" 3.6.0 of community.docker" Authors: Felix Fontein (@felixfontein)community.docker.docker_compose_v2 (3.8.1) — module
Install with ansible-galaxy collection install community.docker:==3.8.1
collections: - name: community.docker version: 3.8.1
Uses Docker Compose to start or shutdown services.
# 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: false tasks: - name: Tear down existing services community.docker.docker_compose_v2: project_src: flask state: absent - name: Create and start services community.docker.docker_compose_v2: project_src: flask register: output - name: Show results ansible.builtin.debug: var: output - name: Run `docker-compose up` again community.docker.docker_compose_v2: project_src: flask register: output - name: Show results ansible.builtin.debug: var: output - ansible.builtin.assert: that: not output.changed - name: Stop all services community.docker.docker_compose_v2: project_src: flask state: stopped register: output - name: Show results ansible.builtin.debug: var: output - name: Verify that web and db services are not running ansible.builtin.assert: that: - "not output.services.web.flask_web_1.state.running" - "not output.services.db.flask_db_1.state.running" - name: Restart services community.docker.docker_compose_v2: project_src: flask state: restarted register: output - name: Show results ansible.builtin.debug: var: output - name: Verify that web and db services are running ansible.builtin.assert: that: - "output.services.web.flask_web_1.state.running" - "output.services.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 O(validate_certs) is set to V(true) as well, it will take precedence. - If the value is not specified in the task, the value of environment variable E(DOCKER_TLS) will be used instead. If the environment variable is not set, the default value will be used. type: bool pull: choices: - always - missing - never - policy default: policy description: - Whether to pull images before running. This is used when C(docker compose up) is run. - V(always) ensures that the images are always pulled, even when already present on the Docker daemon. - V(missing) only pulls them when they are not present on the Docker daemon. - V(never) never pulls images. If they are not present, the module will fail when trying to create the containers that need them. - V(policy) use the Compose file's C(pull_policy) defined for the service to figure out what to do. type: str wait: default: false description: - When running C(docker compose up), pass C(--wait) to wait for services to be running/healthy. - A timeout can be set with the O(wait_timeout) option. type: bool version_added: 3.8.0 version_added_collection: community.docker build: choices: - always - never - policy default: policy description: - Whether to build images before starting containers. This is used when C(docker compose up) is run. - V(always) always builds before starting containers. This is equivalent to the C(--build) option of C(docker compose up). - V(never) never builds before starting containers. This is equivalent to the C(--no-build) option of C(docker compose up). - V(policy) uses the policy as defined in the Compose file. type: str files: description: - List of Compose file names relative to O(project_src) to be used instead of the main Compose file (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)). - Files are loaded and merged in the order given. elements: path type: list version_added: 3.7.0 version_added_collection: community.docker scale: description: - Define how to scale services when running C(docker compose up). - 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 version_added: 3.7.0 version_added_collection: community.docker state: choices: - absent - stopped - restarted - present default: present description: - Desired state of the project. - V(present) is equivalent to running C(docker compose up). - V(stopped) is equivalent to running C(docker compose stop). - V(absent) is equivalent to running C(docker compose down). - V(restarted) is equivalent to running C(docker compose restart). type: str ca_path: aliases: - ca_cert - 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 E(DOCKER_CERT_PATH) is set, the file C(ca.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. type: path timeout: description: - Timeout in seconds for container shutdown when attached or when containers are already running. type: int profiles: description: - List of profiles to enable when starting services. - Equivalent to C(docker compose --profile). elements: str type: list recreate: choices: - always - never - auto default: auto description: - By default containers will be recreated when their configuration differs from the service definition. - Setting to V(never) ignores configuration differences and leaves existing containers unchanged. - Setting to V(always) forces recreation of all existing containers. type: str services: description: - Specifies a subset of services to be targeted. elements: str type: list env_files: description: - By default environment files are loaded from a C(.env) file located directly under the O(project_src) directory. - O(env_files) can be used to specify the path of one or multiple custom environment files instead. - The path is relative to the O(project_src) directory. elements: path type: list 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 E(DOCKER_CERT_PATH) is set, the file C(key.pem) from the directory specified in the environment variable E(DOCKER_CERT_PATH) will be used. type: path docker_cli: description: - Path to the Docker CLI. If not provided, will search for Docker CLI on the E(PATH). type: path 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 this collection and the docker daemon. - If the value is not specified in the task, the value of environment variable E(DOCKER_API_VERSION) will be used instead. If the environment variable is not set, the default value will be used. type: str cli_context: description: - The Docker CLI context to use. 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 E(DOCKER_CERT_PATH) is set, the file C(cert.pem) from the directory specified in the environment variable E(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, V(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 E(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 Compose file (C(compose.yml), C(compose.yaml), C(docker-compose.yml), or C(docker-compose.yaml)). - If O(files) is provided, will look for these files in this directory instead. required: true type: path dependencies: default: true description: - When O(state) is V(present) or V(restarted), 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 O(project_src). type: str 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 E(DOCKER_TLS_HOSTNAME) will be used instead. If the environment variable is not set, the default value will be used. type: str wait_timeout: description: - When O(wait=true), wait at most this amount of seconds. type: int version_added: 3.8.0 version_added_collection: community.docker remove_images: choices: - all - local description: - Use with O(state=absent) to remove all images or only local images. type: str remove_orphans: default: false description: - Remove containers for services not defined in the Compose file. type: bool remove_volumes: default: false description: - Use with O(state=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 E(DOCKER_TLS_VERIFY) will be used instead. If the environment variable is not set, the default value will be used. type: bool
actions: contains: id: description: - The ID of the resource that was changed. sample: container type: str status: choices: - Starting - Exiting - Restarting - Creating - Stopping - Killing - Removing - Recreating - Pulling - Building description: - The status change that happened. sample: Creating type: str what: choices: - container - image - network - service - unknown - volume description: - What kind of resource was changed. sample: container type: str description: - A list of actions that have been applied. elements: dict returned: success type: list containers: contains: Command: description: - The container's command. type: raw CreatedAt: description: - The timestamp when the container was created. sample: 2024-01-02 12:20:41 +0100 CET type: str ExitCode: description: - The container's exit code. type: int Health: description: - The container's health check. type: raw ID: description: - The container's ID. sample: 44a7d607219a60b7db0a4817fb3205dce46e91df2cb4b78a6100b6e27b0d3135 type: str Image: description: - The container's image. type: str Labels: description: - Labels for this container. type: dict LocalVolumes: description: - The local volumes count. type: str Mounts: description: - Mounts. type: str Name: description: - The container's primary name. type: str Names: description: - List of names of the container. elements: str type: list Networks: description: - List of networks attached to this container. elements: str type: list Ports: description: - List of port assignments as a string. type: str Publishers: contains: Protocol: choices: - tcp - udp description: - The protocol. type: str PublishedPort: description: - The port that is published. type: int TargetPort: description: - The container's port the published port maps to. type: int URL: description: - Interface the port is bound to. type: str description: - List of port assigments. elements: dict type: list RunningFor: description: - Amount of time the container runs. type: str Service: description: - The name of the service. type: str Size: description: - The container's size. sample: 0B type: str State: description: - The container's state. sample: running type: str Status: description: - The container's status. sample: Up About a minute type: str description: - A list of containers associated to the service. elements: dict returned: success type: list images: contains: ContainerName: description: - Name of the conainer this image is used by. type: str ID: description: - The image's ID. sample: sha256:c8bccc0af9571ec0d006a43acb5a8d08c4ce42b6cc7194dd6eb167976f501ef1 type: str Repository: description: - The repository where this image belongs to. type: str Size: description: - The image's size in bytes. type: int Tag: description: - The tag of the image. type: str description: - A list of images associated to the service. elements: dict returned: success type: list