community.docker/pr/540/docker_compose_v2_module.html
2023-01-15 18:14:02 +00:00

555 lines
47 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>community.docker.docker_compose_v2 module Manage multi-container Docker applications with Docker Compose v2. &mdash; Community.Docker Collection documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/ansible.css" type="text/css" />
<link rel="stylesheet" href="_static/antsibull-minimal.css" type="text/css" />
<link rel="stylesheet" href="_static/css/rtd-ethical-ads.css" type="text/css" />
<link rel="shortcut icon" href="_static/images/Ansible-Mark-RGB_Black.png"/>
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="community.docker.docker_config module Manage docker configs." href="docker_config_module.html" />
<link rel="prev" title="community.docker.docker_compose module Manage multi-container Docker applications with Docker Compose." href="docker_compose_module.html" /><!-- extra head elements for Ansible beyond RTD Sphinx Theme -->
</head>
<body class="wy-body-for-nav"><!-- extra body elements for Ansible beyond RTD Sphinx Theme -->
<div class="DocSite-globalNav ansibleNav">
<ul>
<li><a href="https://www.ansible.com/ansiblefest" target="_blank">AnsibleFest</a></li>
<li><a href="https://www.ansible.com/tower" target="_blank">Products</a></li>
<li><a href="https://www.ansible.com/community" target="_blank">Community</a></li>
<li><a href="https://www.ansible.com/webinars-training" target="_blank">Webinars & Training</a></li>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li>
</ul>
</div>
<a class="DocSite-nav" href="https://ansible-collections.github.io/community.docker/branch/main/" style="padding-bottom: 30px;">
<img class="DocSiteNav-logo"
src="_static/images/Ansible-Mark-RGB_White.png"
alt="Ansible Logo">
<div class="DocSiteNav-title">Community.Docker Collection Docs</div>
</a>
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> Community.Docker Collection
</a><!--- Based on https://github.com/rtfd/sphinx_rtd_theme/pull/438/files -->
<div class="version">
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<label class="sr-only" for="q">Search docs:</label>
<input type="text" class="st-default-search-input" id="q" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="docsite/scenario_guide.html">Docker Guide</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="current_container_facts_module.html">community.docker.current_container_facts module Return facts about whether the module runs in a Docker container</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_compose_module.html">community.docker.docker_compose module Manage multi-container Docker applications with Docker Compose.</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">community.docker.docker_compose_v2 module Manage multi-container Docker applications with Docker Compose v2.</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#synopsis">Synopsis</a></li>
<li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="#parameters">Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="#attributes">Attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="#return-values">Return Values</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#authors">Authors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#collection-links">Collection links</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="docker_config_module.html">community.docker.docker_config module Manage docker configs.</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_container_module.html">community.docker.docker_container module manage Docker containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_container_copy_into_module.html">community.docker.docker_container_copy_into module Copy a file into a Docker container</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_container_exec_module.html">community.docker.docker_container_exec module Execute command in a docker container</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_container_info_module.html">community.docker.docker_container_info module Retrieves facts about docker container</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_host_info_module.html">community.docker.docker_host_info module Retrieves facts about docker host and lists of objects of the services.</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_image_module.html">community.docker.docker_image module Manage docker images</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_image_info_module.html">community.docker.docker_image_info module Inspect docker images</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_image_load_module.html">community.docker.docker_image_load module Load docker image(s) from archives</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_login_module.html">community.docker.docker_login module Log into a Docker registry.</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_network_module.html">community.docker.docker_network module Manage Docker networks</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_network_info_module.html">community.docker.docker_network_info module Retrieves facts about docker network</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_node_module.html">community.docker.docker_node module Manage Docker Swarm node</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_node_info_module.html">community.docker.docker_node_info module Retrieves facts about docker swarm node from Swarm Manager</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_plugin_module.html">community.docker.docker_plugin module Manage Docker plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_prune_module.html">community.docker.docker_prune module Allows to prune various docker objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_secret_module.html">community.docker.docker_secret module Manage docker secrets.</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_stack_module.html">community.docker.docker_stack module docker stack module</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_stack_info_module.html">community.docker.docker_stack_info module Return information on a docker stack</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_stack_task_info_module.html">community.docker.docker_stack_task_info module Return information of the tasks on a docker stack</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_swarm_module.html">community.docker.docker_swarm module Manage Swarm cluster</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_swarm_info_module.html">community.docker.docker_swarm_info module Retrieves facts about Docker Swarm cluster.</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_swarm_service_module.html">community.docker.docker_swarm_service module docker swarm service</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_swarm_service_info_module.html">community.docker.docker_swarm_service_info module Retrieves information about docker services from a Swarm Manager</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_volume_module.html">community.docker.docker_volume module Manage Docker volumes</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_volume_info_module.html">community.docker.docker_volume_info module Retrieve facts about Docker volumes</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="docker_connection.html">community.docker.docker connection Run tasks in docker containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_api_connection.html">community.docker.docker_api connection Run tasks in docker containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="nsenter_connection.html">community.docker.nsenter connection execute on host running controller container</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="docker_containers_inventory.html">community.docker.docker_containers inventory Ansible dynamic inventory plugin for Docker containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_machine_inventory.html">community.docker.docker_machine inventory Docker Machine inventory source</a></li>
<li class="toctree-l1"><a class="reference internal" href="docker_swarm_inventory.html">community.docker.docker_swarm inventory Ansible dynamic inventory plugin for Docker swarm nodes.</a></li>
</ul>
<!-- extra nav elements for Ansible beyond RTD Sphinx Theme -->
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Community.Docker Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a></li>
<li class="breadcrumb-item active">community.docker.docker_compose_v2 module Manage multi-container Docker applications with Docker Compose v2.</li>
<li class="wy-breadcrumbs-aside">
<!-- User defined GitHub URL -->
<a href="https://github.com/ansible-collections/community.docker/edit/main/plugins/modules/docker_compose_v2.py?description=%23%23%23%23%23%20SUMMARY%0A%3C!—%20Your%20description%20here%20%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<span class="target" id="ansible-collections-community-docker-docker-compose-v2-module"></span><section id="community-docker-docker-compose-v2-module-manage-multi-container-docker-applications-with-docker-compose-v2">
<h1>community.docker.docker_compose_v2 module Manage multi-container Docker applications with Docker Compose v2.<a class="headerlink" href="#community-docker-docker-compose-v2-module-manage-multi-container-docker-applications-with-docker-compose-v2" title="Permalink to this heading"></a></h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This module is part of the <a class="reference external" href="https://galaxy.ansible.com/community/docker">community.docker collection</a> (version 3.5.0).</p>
<p>To install it, use: <code class="code docutils literal notranslate"><span class="pre">ansible-galaxy</span> <span class="pre">collection</span> <span class="pre">install</span> <span class="pre">community.docker</span></code>.
You need further requirements to be able to use this module,
see <a class="reference internal" href="#ansible-collections-community-docker-docker-compose-v2-module-requirements"><span class="std std-ref">Requirements</span></a> for details.</p>
<p>To use it in a playbook, specify: <code class="code docutils literal notranslate"><span class="pre">community.docker.docker_compose_v2</span></code>.</p>
</div>
<p class="ansible-version-added">New in community.docker 3.5.0</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#synopsis" id="id1">Synopsis</a></p></li>
<li><p><a class="reference internal" href="#requirements" id="id2">Requirements</a></p></li>
<li><p><a class="reference internal" href="#parameters" id="id3">Parameters</a></p></li>
<li><p><a class="reference internal" href="#attributes" id="id4">Attributes</a></p></li>
<li><p><a class="reference internal" href="#examples" id="id5">Examples</a></p></li>
<li><p><a class="reference internal" href="#return-values" id="id6">Return Values</a></p></li>
</ul>
</div>
<section id="synopsis">
<h2><a class="toc-backref" href="#id1">Synopsis</a><a class="headerlink" href="#synopsis" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p>Uses Docker Compose v2 to manage docker services. <strong>This module requires docker-compose &gt;= 2.0.0. and python &gt;= 3.7</strong></p></li>
<li><p>Configuration can be read from a <code class="docutils literal notranslate"><span class="pre">docker-compose.yaml</span></code> file.</p></li>
<li><p>See the examples for more details.</p></li>
<li><p>Supports check mode.</p></li>
</ul>
</section>
<section id="requirements">
<span id="ansible-collections-community-docker-docker-compose-v2-module-requirements"></span><h2><a class="toc-backref" href="#id2">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this heading"></a></h2>
<p>The below requirements are needed on the host that executes this module.</p>
<ul class="simple">
<li><p><a class="reference external" href="https://pypi.org/project/python-on-whales/">Python on Whales</a> &gt;= 0.55.0</p></li>
<li><p>docker-compose &gt;= 2.0.0</p></li>
<li><p>python &gt;= 3.7</p></li>
</ul>
</section>
<section id="parameters">
<h2><a class="toc-backref" href="#id3">Parameters</a><a class="headerlink" href="#parameters" title="Permalink to this heading"></a></h2>
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Comments</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-build"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-build"><strong>build</strong></p>
<a class="ansibleOptionLink" href="#parameter-build" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with <em>state</em> <code class="docutils literal notranslate"><span class="pre">present</span></code> to always build images prior to starting the application.</p>
<p>Same as running <code class="docutils literal notranslate"><span class="pre">docker-compose</span> <span class="pre">build</span></code> with the pull option.</p>
<p>Images will only be rebuilt if Docker detects a change in the Dockerfile or build directory contents.</p>
<p>Use the <em>nocache</em> option to ignore the image cache when performing the build.</p>
<p>If an existing image is replaced, services using the image will be recreated unless <em>recreate</em> is <code class="docutils literal notranslate"><span class="pre">never</span></code>.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-nocache"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-nocache"><strong>nocache</strong></p>
<a class="ansibleOptionLink" href="#parameter-nocache" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with the <em>build</em> option to ignore the cache during the image build process.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-project_src"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-project-src"><strong>project_src</strong></p>
<a class="ansibleOptionLink" href="#parameter-project_src" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">path</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Path to a directory containing a <code class="docutils literal notranslate"><span class="pre">docker-compose.yaml</span></code> file.</p>
<p>Required.</p>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-pull"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-pull"><strong>pull</strong></p>
<a class="ansibleOptionLink" href="#parameter-pull" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with <em>state</em> <code class="docutils literal notranslate"><span class="pre">present</span></code> to always pull images prior to starting the application.</p>
<p>Same as running <code class="docutils literal notranslate"><span class="pre">docker-compose</span> <span class="pre">pull</span></code>.</p>
<p>When a new image is pulled, services using the image will be recreated unless <em>recreate</em> is <code class="docutils literal notranslate"><span class="pre">never</span></code>.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-recreate"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-recreate"><strong>recreate</strong></p>
<a class="ansibleOptionLink" href="#parameter-recreate" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>By default containers will be recreated when their configuration differs from the service definition.</p>
<p>Setting to <code class="docutils literal notranslate"><span class="pre">never</span></code> ignores configuration differences and leaves existing containers unchanged.</p>
<p>Setting to <code class="docutils literal notranslate"><span class="pre">always</span></code> forces recreation of all existing containers.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;always&quot;</span></code></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;never&quot;</span></code></p></li>
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">&quot;smart&quot;</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
</ul>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-remove_images"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-remove-images"><strong>remove_images</strong></p>
<a class="ansibleOptionLink" href="#parameter-remove_images" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with <em>state</em> <code class="docutils literal notranslate"><span class="pre">absent</span></code> to remove all images or only local images.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;all&quot;</span></code></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;local&quot;</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-remove_orphans"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-remove-orphans"><strong>remove_orphans</strong></p>
<a class="ansibleOptionLink" href="#parameter-remove_orphans" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Remove containers for services not defined in the Compose file when not <code class="docutils literal notranslate"><span class="pre">restarted</span></code> or <code class="docutils literal notranslate"><span class="pre">stopped</span></code>.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-remove_volumes"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-remove-volumes"><strong>remove_volumes</strong></p>
<a class="ansibleOptionLink" href="#parameter-remove_volumes" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with <em>state</em> <code class="docutils literal notranslate"><span class="pre">absent</span></code> to remove data volumes.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-restarted"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-restarted"><strong>restarted</strong></p>
<a class="ansibleOptionLink" href="#parameter-restarted" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with <em>state</em> <code class="docutils literal notranslate"><span class="pre">present</span></code> to restart all containers defined in the Compose file.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-state"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-state"><strong>state</strong></p>
<a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Desired state of the project.</p>
<p>Specifying <code class="docutils literal notranslate"><span class="pre">present</span></code> is the same as running <code class="docutils literal notranslate"><span class="pre">docker-compose</span> <span class="pre">up</span></code> resp. <code class="docutils literal notranslate"><span class="pre">docker-compose</span> <span class="pre">stop</span></code> (with <em>stopped</em>) resp. <code class="docutils literal notranslate"><span class="pre">docker-compose</span> <span class="pre">restart</span></code> (with <em>restarted</em>).</p>
<p>Specifying <code class="docutils literal notranslate"><span class="pre">absent</span></code> is the same as running <code class="docutils literal notranslate"><span class="pre">docker-compose</span> <span class="pre">down</span></code>.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;absent&quot;</span></code></p></li>
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">&quot;present&quot;</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
</ul>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="parameter-stopped"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-parameter-stopped"><strong>stopped</strong></p>
<a class="ansibleOptionLink" href="#parameter-stopped" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Use with <em>state</em> <code class="docutils literal notranslate"><span class="pre">present</span></code> to stop all containers defined in the Compose file.</p>
<p class="ansible-option-line"><span class="ansible-option-choices">Choices:</span></p>
<ul class="simple">
<li><p><code class="ansible-option-default-bold docutils literal notranslate"><span class="pre">false</span></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">true</span></code></p></li>
</ul>
</div></td>
</tr>
</tbody>
</table>
</section>
<section id="attributes">
<h2><a class="toc-backref" href="#id4">Attributes</a><a class="headerlink" href="#attributes" title="Permalink to this heading"></a></h2>
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd"><th class="head"><p>Attribute</p></th>
<th class="head"><p>Support</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="attribute-check_mode"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-attribute-check-mode"><strong>check_mode</strong></p>
<a class="ansibleOptionLink" href="#attribute-check_mode" title="Permalink to this attribute"></a></div></td>
<td><div class="ansible-option-cell"><p><span class="ansible-attribute-support-label">Support: </span><span class="ansible-attribute-support-full">full</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Can run in <code class="docutils literal notranslate"><span class="pre">check_mode</span></code> and return changed status prediction without modifying target.</p>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="attribute-diff_mode"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-attribute-diff-mode"><strong>diff_mode</strong></p>
<a class="ansibleOptionLink" href="#attribute-diff_mode" title="Permalink to this attribute"></a></div></td>
<td><div class="ansible-option-cell"><p><span class="ansible-attribute-support-label">Support: </span><span class="ansible-attribute-support-none">none</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Will return details on what has changed (or possibly needs changing in <code class="docutils literal notranslate"><span class="pre">check_mode</span></code>), when in diff mode.</p>
</div></td>
</tr>
</tbody>
</table>
</section>
<section id="examples">
<h2><a class="toc-backref" href="#id5">Examples</a><a class="headerlink" href="#examples" title="Permalink to this heading"></a></h2>
<div class="highlight-yaml+jinja notranslate"><div class="highlight"><pre><span></span><span class="c1"># Set up a virtual environment for the module and install python on whales</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Set up virtual env for compose v2</span>
<span class="w"> </span><span class="nt">ansible.builtin.pip</span><span class="p">:</span>
<span class="w"> </span><span class="nt">name</span><span class="p">:</span>
<span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">python-on-whales</span>
<span class="w"> </span><span class="nt">virtualenv</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">~/ansible-compose-v2</span>
<span class="c1"># Ensure project directory is present</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Create directory if it does not exist</span>
<span class="w"> </span><span class="nt">ansible.builtin.file</span><span class="p">:</span>
<span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uptime-kuma</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">directory</span>
<span class="c1"># Create the docker compose file</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Create compose file with content</span>
<span class="w"> </span><span class="nt">ansible.builtin.copy</span><span class="p">:</span>
<span class="w"> </span><span class="nt">dest</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;uptime-kuma/docker-compose.yaml&quot;</span>
<span class="w"> </span><span class="nt">content</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
<span class="w"> </span><span class="no">version: &#39;3.3&#39;</span>
<span class="w"> </span><span class="no">services:</span>
<span class="w"> </span><span class="no">uptime-kuma:</span>
<span class="w"> </span><span class="no">image: louislam/uptime-kuma:1</span>
<span class="w"> </span><span class="no">container_name: uptime-kuma</span>
<span class="w"> </span><span class="no">volumes:</span>
<span class="w"> </span><span class="no">- ./uptime-kuma-data:/app/data</span>
<span class="w"> </span><span class="no">ports:</span>
<span class="w"> </span><span class="no">- 3001:3001</span>
<span class="w"> </span><span class="no">restart: always</span>
<span class="c1"># Tear down any containers, remove images and volumes</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Tear down all existing containers</span>
<span class="w"> </span><span class="nt">vars</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ansible_python_interpreter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ansible-compose-v2/bin/python</span>
<span class="w"> </span><span class="nt">community.docker.docker_compose_v2</span><span class="p">:</span>
<span class="w"> </span><span class="nt">project_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uptime-kuma/docker-compose.yaml</span>
<span class="w"> </span><span class="nt">remove_volumes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">remove_orphans</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">remove_images</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">all</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">absent</span>
<span class="c1"># Pull the latest image and then start services</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Pull image and start service</span>
<span class="w"> </span><span class="nt">vars</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ansible_python_interpreter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ansible-compose-v2/bin/python</span>
<span class="w"> </span><span class="nt">community.docker.docker_compose_v2</span><span class="p">:</span>
<span class="w"> </span><span class="nt">project_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uptime-kuma/docker-compose.yaml</span>
<span class="w"> </span><span class="nt">pull</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">present</span>
<span class="c1"># Restart services</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Restart service</span>
<span class="w"> </span><span class="nt">vars</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ansible_python_interpreter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ansible-compose-v2/bin/python</span>
<span class="w"> </span><span class="nt">community.docker.docker_compose_v2</span><span class="p">:</span>
<span class="w"> </span><span class="nt">project_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uptime-kuma/docker-compose.yaml</span>
<span class="w"> </span><span class="nt">restarted</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">present</span>
<span class="c1"># Stop services</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Stop service</span>
<span class="w"> </span><span class="nt">vars</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ansible_python_interpreter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ansible-compose-v2/bin/python</span>
<span class="w"> </span><span class="nt">community.docker.docker_compose_v2</span><span class="p">:</span>
<span class="w"> </span><span class="nt">project_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uptime-kuma/docker-compose.yaml</span>
<span class="w"> </span><span class="nt">stopped</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">present</span>
<span class="c1"># Start services, recreating all containers</span>
<span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Recreate service</span>
<span class="w"> </span><span class="nt">vars</span><span class="p">:</span>
<span class="w"> </span><span class="nt">ansible_python_interpreter</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ansible-compose-v2/bin/python</span>
<span class="w"> </span><span class="nt">community.docker.docker_compose_v2</span><span class="p">:</span>
<span class="w"> </span><span class="nt">project_src</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uptime-kuma/docker-compose.yaml</span>
<span class="w"> </span><span class="nt">recreate</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">always</span>
<span class="w"> </span><span class="nt">state</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">present</span>
</pre></div>
</div>
</section>
<section id="return-values">
<h2><a class="toc-backref" href="#id6">Return Values</a><a class="headerlink" href="#return-values" title="Permalink to this heading"></a></h2>
<p>Common return values are documented <a class="reference external" href="https://docs.ansible.com/ansible/devel/reference_appendices/common_return_values.html#common-return-values" title="(in Ansible vdevel)"><span class="xref std std-ref">here</span></a>, the following are the fields unique to this module:</p>
<table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
<thead>
<tr class="row-odd"><th class="head"><p>Key</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-actions"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-return-actions"><strong>actions</strong></p>
<a class="ansibleOptionLink" href="#return-actions" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">list</span> / <span class="ansible-option-elements">elements=string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>List stating which compose commands were run (not the entire command itself).</p>
<p class="ansible-option-line"><span class="ansible-option-returned-bold">Returned:</span> success</p>
<p class="ansible-option-line ansible-option-sample"><span class="ansible-option-sample-bold">Sample:</span> <code class="ansible-option-sample docutils literal notranslate"><span class="pre">[&quot;pull&quot;,</span> <span class="pre">&quot;up&quot;]</span></code></p>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-changed"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-return-changed"><strong>changed</strong></p>
<a class="ansibleOptionLink" href="#return-changed" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>If something was changed (currently, changed is (almost) always true as there is no check of current state).</p>
<p class="ansible-option-line"><span class="ansible-option-returned-bold">Returned:</span> always</p>
<p class="ansible-option-line ansible-option-sample"><span class="ansible-option-sample-bold">Sample:</span> <code class="ansible-option-sample docutils literal notranslate"><span class="pre">true</span></code></p>
</div></td>
</tr>
<tr class="row-even"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-msg"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-return-msg"><strong>msg</strong></p>
<a class="ansibleOptionLink" href="#return-msg" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>In docker failures, has docker command + some description. In other failures, stringified exception is returned. In success, descriptive message of what happened.</p>
<p class="ansible-option-line"><span class="ansible-option-returned-bold">Returned:</span> always</p>
<p class="ansible-option-line ansible-option-sample"><span class="ansible-option-sample-bold">Sample:</span> <code class="ansible-option-sample docutils literal notranslate"><span class="pre">true</span></code></p>
</div></td>
</tr>
<tr class="row-odd"><td><div class="ansible-option-cell">
<div class="ansibleOptionAnchor" id="return-rc"></div><p class="ansible-option-title" id="ansible-collections-community-docker-docker-compose-v2-module-return-rc"><strong>rc</strong></p>
<a class="ansibleOptionLink" href="#return-rc" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
</div></td>
<td><div class="ansible-option-cell"><p>Return code of executed docker command.</p>
<p class="ansible-option-line"><span class="ansible-option-returned-bold">Returned:</span> failure from docker</p>
<p class="ansible-option-line ansible-option-sample"><span class="ansible-option-sample-bold">Sample:</span> <code class="ansible-option-sample docutils literal notranslate"><span class="pre">&quot;12&quot;</span></code></p>
</div></td>
</tr>
</tbody>
</table>
<section id="authors">
<h3>Authors<a class="headerlink" href="#authors" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>Sid Sun (&#64;SidSun)</p></li>
</ul>
</section>
<section id="collection-links">
<h3>Collection links<a class="headerlink" href="#collection-links" title="Permalink to this heading"></a></h3>
<p class="ansible-links">
<a href="https://github.com/ansible-collections/community.docker/issues" aria-role="button" target="_blank" rel="noopener external">Issue Tracker</a>
<a href="https://github.com/ansible-collections/community.docker" aria-role="button" target="_blank" rel="noopener external">Repository (Sources)</a>
<a href="https://github.com/ansible-collections/community.docker/issues/new?assignees=&amp;labels=&amp;template=bug_report.md" aria-role="button" target="_blank" rel="noopener external">Submit a bug report</a>
<a href="https://github.com/ansible-collections/community.docker/issues/new?assignees=&amp;labels=&amp;template=feature_request.md" aria-role="button" target="_blank" rel="noopener external">Request a feature</a>
<a href="./#communication-for-community-docker" aria-role="button" target="_blank">Communication</a>
</p></section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="docker_compose_module.html" class="btn btn-neutral float-left" title="community.docker.docker_compose module Manage multi-container Docker applications with Docker Compose." accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="docker_config_module.html" class="btn btn-neutral float-right" title="community.docker.docker_config module Manage docker configs." accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright Community.Docker Contributors.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script><!-- extra footer elements for Ansible beyond RTD Sphinx Theme -->
</body>
</html>