@ -16,16 +16,16 @@ DOCUMENTATION = '''
module : docker_compose
module : docker_compose
short_description : Manage docker services and containers .
short_description : Manage multi- container Docker applications with Docker Compose .
version_added : " 2.1 "
version_added : " 2.1 "
author : " Chris Houseknecht (@chouseknecht) "
author : " Chris Houseknecht (@chouseknecht) "
description :
description :
- Consumes docker c ompose to start , shutdown and scale services .
- Uses Docker C ompose to start , shutdown and scale services .
- Works with compose versions 1 and 2.
- Works with compose versions 1 and 2.
- Co mpose can be read from a docker - compose . yml ( or . yaml ) file or inline using the C ( definition ) option .
- Co nfiguration 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 .
- See the examples for more details .
- Supports check mode .
- Supports check mode .
- This module was called C ( docker_service ) before Ansible 2.8 . The usage did not change .
- This module was called C ( docker_service ) before Ansible 2.8 . The usage did not change .
@ -33,25 +33,26 @@ description:
options :
options :
project_src :
project_src :
description :
description :
- Path to a directory containing a docker- compose . yml or docker- compose . yaml file .
- Path to a directory containing a C( docker- compose . yml ) or C( docker- compose . yaml ) file .
- Mutually exclusive with C ( definition ) .
- Mutually exclusive with I ( definition ) .
- Required when no C ( definition ) is provided .
- Required when no I ( definition ) is provided .
type : path
type : path
project_name :
project_name :
description :
description :
- Provide a project name . If not provided , the project name is taken from the basename of C ( project_src ) .
- Provide a project name . If not provided , the project name is taken from the basename of I ( project_src ) .
- Required when C ( definition ) is provided .
- Required when I ( definition ) is provided .
type : str
type : str
files :
files :
description :
description :
- List of file names relative to C ( project_src ) . Overrides docker- compose . yml or docker- compose . yaml .
- 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 .
- Files are loaded and merged in the order given .
type : list
type : list
state :
state :
description :
description :
- Desired state of the project .
- Desired state of the project .
- Specifying I ( present ) is the same as running I ( docker - compose up ) .
- 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 )
- Specifying I ( absent ) is the same as running I ( docker - compose down ) .
( with I ( restarted ) ) .
- Specifying C ( absent ) is the same as running C ( docker - compose down ) .
type : str
type : str
default : present
default : present
choices :
choices :
@ -59,22 +60,24 @@ options:
- present
- present
services :
services :
description :
description :
- When C ( state ) is I ( present ) run I ( docker - compose up ) on a subset of services .
- 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
type : list
scale :
scale :
description :
description :
- When C( state ) is I ( present ) scale services . Provide a dictionary of key / value pairs where the key
- 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 .
is the name of the service and the value is an integer count for the number of containers .
type : dict
type : dict
dependencies :
dependencies :
description :
description :
- When C( state ) is I ( present ) specify whether or not to include linked services .
- When I( state ) is C ( present ) specify whether or not to include linked services .
type : bool
type : bool
default : yes
default : yes
definition :
definition :
description :
description :
- Provide docker - compose yaml describing one or more services , networks and volumes .
- Compose file describing one or more services , networks and volumes .
- Mutually exclusive with C( project_src ) and C ( files ) .
- Mutually exclusive with I( project_src ) and I ( files ) .
type : dict
type : dict
hostname_check :
hostname_check :
description :
description :
@ -84,8 +87,8 @@ options:
recreate :
recreate :
description :
description :
- By default containers will be recreated when their configuration differs from the service definition .
- 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 C ( never ) ignores configuration differences and leaves existing containers unchanged .
- Setting to I ( always ) forces recreation of all existing containers .
- Setting to C ( always ) forces recreation of all existing containers .
type : str
type : str
default : smart
default : smart
choices :
choices :
@ -94,52 +97,54 @@ options:
- smart
- smart
build :
build :
description :
description :
- Use with state I ( present ) to always build images prior to starting the application .
- Use with I( state ) C ( present ) to always build images prior to starting the application .
- Same as running docker- compose build with the pull option .
- 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 .
- 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 .
- 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 C( recreate ) is I ( never ) .
- If an existing image is replaced , services using the image will be recreated unless I( recreate ) is C ( never ) .
type : bool
type : bool
default : no
default : no
pull :
pull :
description :
description :
- Use with state I ( present ) to always pull images prior to starting the application .
- Use with I( state ) C ( present ) to always pull images prior to starting the application .
- Same as running docker- compose pull .
- Same as running C( docker- compose pull ) .
- When a new image is pulled , services using the image will be recreated unless C( recreate ) is I ( never ) .
- When a new image is pulled , services using the image will be recreated unless I( recreate ) is C ( never ) .
type : bool
type : bool
default : no
default : no
version_added : " 2.2 "
version_added : " 2.2 "
nocache :
nocache :
description :
description :
- Use with the build option to ignore the cache during the image build process .
- Use with the I( build) option to ignore the cache during the image build process .
type : bool
type : bool
default : no
default : no
version_added : " 2.2 "
version_added : " 2.2 "
remove_images :
remove_images :
description :
description :
- Use with state I ( absent ) to remov e th e all images or only local images .
- Use with I( state ) C ( absent ) to remov e all images or only local images .
type : str
type : str
choices :
choices :
- ' all '
- ' all '
- ' local '
- ' local '
remove_volumes :
remove_volumes :
description :
description :
- Use with state I ( absent ) to remove data volumes .
- Use with I( state ) C ( absent ) to remove data volumes .
type : bool
type : bool
default : no
default : no
stopped :
stopped :
description :
description :
- Use with state I ( present ) to leave the containers in an exited or non - running state .
- 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
type : bool
default : no
default : no
restarted :
restarted :
description :
description :
- Use with state I ( present ) to restart all containers .
- 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
type : bool
default : no
default : no
remove_orphans :
remove_orphans :
description :
description :
- Remove containers for services not defined in the c ompose file .
- Remove containers for services not defined in the C ompose file .
type : bool
type : bool
default : no
default : no
timeout :
timeout :
@ -160,25 +165,28 @@ requirements:
'''
'''
EXAMPLES = '''
EXAMPLES = '''
# Examples use the django example at U( https://docs.docker.com/compose/django/) . Follow it to create the flask
# Examples use the django example at https://docs.docker.com/compose/django. Follow it to create the
# directory
# flask directory
- name : Run using a project directory
- name : Run using a project directory
hosts : localhost
hosts : localhost
gather_facts : no
gather_facts : no
tasks :
tasks :
- docker_compose :
- name : Tear down existing services
docker_compose :
project_src : flask
project_src : flask
state : absent
state : absent
- docker_compose :
- name : Create and start services
docker_compose :
project_src : flask
project_src : flask
register : output
register : output
- debug :
- debug :
var : output
var : output
- docker_compose :
- name : Run ` docker - compose up ` again
docker_compose :
project_src : flask
project_src : flask
build : no
build : no
register : output
register : output
@ -189,10 +197,11 @@ EXAMPLES = '''
- assert :
- assert :
that : " not output.changed "
that : " not output.changed "
- docker_compose :
- name : Stop all services
docker_compose :
project_src : flask
project_src : flask
build : no
build : no
stopped : true
stopped : yes
register : output
register : output
- debug :
- debug :
@ -203,10 +212,11 @@ EXAMPLES = '''
- " not web.flask_web_1.state.running "
- " not web.flask_web_1.state.running "
- " not db.flask_db_1.state.running "
- " not db.flask_db_1.state.running "
- docker_compose :
- name : Restart services
docker_compose :
project_src : flask
project_src : flask
build : no
build : no
restarted : true
restarted : yes
register : output
register : output
- debug :
- debug :
@ -308,7 +318,7 @@ services:
type : complex
type : complex
contains :
contains :
container_name :
container_name :
description : Name of the container . Format is I ( project_service_ #).
description : Name of the container . Format is C ( project_service_ #).
returned : success
returned : success
type : complex
type : complex
contains :
contains :
@ -385,7 +395,7 @@ services:
actions :
actions :
description : Provides the actions to be taken on each service as determined by compose .
description : Provides the actions to be taken on each service as determined by compose .
returned : when in check mode or I ( debug ) true
returned : when in check mode or I ( debug ) is C ( yes )
type : complex
type : complex
contains :
contains :
service_name :
service_name :