archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve docker_compose module documentation (#60064)

Browse Source 
* Improve docker_compose module documentation

* Swap usage of C() and I()

* Further improvements

* Mentions of files (docker-compose.yml) are now rendered correctly.
* Compose files are now called just that.

* Further clarify options "services", "stopped" and "restarted"

* Update lib/ansible/modules/cloud/docker/docker_compose.py

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Update lib/ansible/modules/cloud/docker/docker_compose.py

Co-Authored-By: Felix Fontein <felix@fontein.de>
pull/60341/head
Sebastian Neuser 5 years ago committed by Felix Fontein
parent 3290b8343c
commit e9fc095123
1 changed files with 52 additions and 42 deletions
Show Stats Download Patch File Download Diff File

94
lib/ansible/modules/cloud/docker/docker_compose.py
Unescape Escape View File

@ -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 compose to start, shutdown and scale services. - Uses Docker Compose to start, shutdown and scale services.
- Works with compose versions 1 and 2. - 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. - 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. - 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 remove the all images or only local images. - Use with I(state) C(absent) to remove 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 compose file. - Remove containers for services not defined in the Compose 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:

Write Preview
Loading…
Cancel
Save