-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Add docker_compose module #354
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,319 @@ | ||
#!/usr/bin/python | ||
|
||
# (c) 2015, Sam Yaple <sam@yaple.net> | ||
# | ||
# This file is part of Ansible | ||
# | ||
# Ansible is free software: you can redistribute it and/or modify | ||
# it under the terms of the GNU General Public License as published by | ||
# the Free Software Foundation, either version 3 of the License, or | ||
# (at your option) any later version. | ||
# | ||
# Ansible is distributed in the hope that it will be useful, | ||
# but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
# GNU General Public License for more details. | ||
# | ||
# You should have received a copy of the GNU General Public License | ||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. | ||
|
||
DOCUMENTATION = ''' | ||
--- | ||
module: docker_compose | ||
version_added: 1.8.4 | ||
short_description: Manage docker containers with docker-compose | ||
description: | ||
- Manage the lifecycle of groups of docker containers with docker-compose | ||
options: | ||
command: | ||
description: | ||
- Select the compose action to perform | ||
required: true | ||
choices: ['build', 'kill', 'pull', 'rm', 'scale', 'start', 'stop', 'restart', 'up'] | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. command is not a pattern we like to follow, we prefer a more imperative 'state', in this case some I would need to know more about some of the options which don't seem to fit There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You mean s/imperative/declarative/ right? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ^ what he said. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In this case though, 'state' isn't really accurate. state=scale doesn't make much sense to me. state=up and state=start are two different commands and I think it would lead to confusion. |
||
compose_file: | ||
description: | ||
- Specify the compose file to build from | ||
required: true | ||
type: bool | ||
insecure_registry: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. validate_certs is the parameter that we use for other modules and we like keeping that consitent There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. insecure_registry follows the parameter from the docker module. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. it can still be an alias, I would prefer to keep ansible consistent and allow people to use the same option name for the same thing There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't think it is the same thing... The docker module actually has several other parameters that would come into play if insecure_registry==False to actually validate certs. In the docker module, those are named tls_*... we might want to alias one of them to validate_certs if the functionality is actually equivalent there. insecure_registry really just controls whether docker requires tls or not. It doesn't do anything about verifying whether the client or server certificates are valid. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ok, then we need a better description, as not knowing the actual docker equivalent it mislead me to equate them. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I can use the docker modules description of "Use insecure private registry by HTTP instead of HTTPS", would that suffice? The current description is taken from docker-compose itself. |
||
description: | ||
- Allow access to insecure registry (HTTP or TLS with a CA not known by the Docker daemon) | ||
type: bool | ||
kill_signal: | ||
description: | ||
- The SIG to send to the docker container process when killing it | ||
default: SIGKILL | ||
no_build: | ||
description: | ||
- Do not build an image, even if it's missing | ||
type: bool | ||
no_deps: | ||
description: | ||
- Don't start linked services | ||
type: bool | ||
no_recreate: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. if using a state=present this should just be the default, unless the other parameters do not match, in which case a force=yes/no seems more appropriate There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. By default, docker-compose recreates containers when rerun (stops/destroys/starts). This isn't really the desired behavior for ansible modules as I understand since it actually forces a change each time. Thoughts? |
||
description: | ||
- If containers already exist, don't recreate them | ||
type: bool | ||
project_name: | ||
description: | ||
- Specify project name (defaults to directory name of the compose file) | ||
type: str | ||
service_names: | ||
description: | ||
- Only modify services in this list (can be used in conjunction with no_deps) | ||
type: list | ||
stop_timeout: | ||
description: | ||
- The amount of time in seconds to wait for an instance to cleanly terminate before killing it (can be used in conjunction with stop_timeout) | ||
default: 10 | ||
type: int | ||
|
||
author: Sam Yaple | ||
requirements: [ "docker-compose", "docker >= 1.3" ] | ||
''' | ||
|
||
EXAMPLES = ''' | ||
Compose web application: | ||
|
||
- hosts: web | ||
tasks: | ||
- name: compose super important weblog | ||
docker_compose: command="up" compose_file="/opt/compose/weblog.yml" | ||
|
||
Compose only mysql server from previous example: | ||
|
||
- hosts: web | ||
tasks: | ||
- name: compose mysql | ||
docker_compose: command="up" compose_file="/opt/compose/weblog.yml" service_names=['mysql'] | ||
|
||
Compose project with specified prefix: | ||
|
||
- hosts: web | ||
tasks: | ||
- name: compose weblog named "myproject_weblog_1" | ||
docker_compose: command="up" compose_file="/opt/compose/weblog.yml" project_name="myproject" | ||
|
||
Compose project only if already built (or no build instructions). Explicitly refuse to build the container image(s): | ||
|
||
- hosts: web | ||
tasks: | ||
- name: compose weblog | ||
docker_compose: command="up" compose_file="/opt/compose/weblog.yml" no_build=True | ||
|
||
Allow the container image to be pulled from an insecure registry (this requires the docker daemon to allow the insecure registry as well): | ||
|
||
- hosts: web | ||
tasks: | ||
- name: compose weblog from local registry | ||
docker_compose: command="up" compose_file="/opt/compose/weblog.yml" insecure_registry=True | ||
|
||
Start the containers in the compose project, but do not create any: | ||
|
||
- hosts: web | ||
tasks: | ||
- name: compose weblog | ||
docker_compose: command="start" compose_file="/opt/compose/weblog.yml" | ||
|
||
Removed all the containers associated with a project; only wait 5 seconds for the container to respond to a SIGTERM: | ||
|
||
- hosts: web | ||
tasks: | ||
- name: Destroy ALL containers for project "devweblog" | ||
docker_compose: command="rm" stop_timeout=5 compose_file="/opt/compose/weblog.yml" project_name="devweblog" | ||
''' | ||
|
||
HAS_DOCKER_COMPOSE = True | ||
|
||
import re | ||
|
||
try: | ||
from compose import config | ||
from compose.cli.command import Command as compose_command | ||
from compose.cli.docker_client import docker_client | ||
except ImportError, e: | ||
HAS_DOCKER_COMPOSE = False | ||
|
||
TIMEMAP = { | ||
'second': 0, | ||
'seconds': 0, | ||
'minute': 1, | ||
'minutes': 1, | ||
'hour': 2, | ||
'hours': 2, | ||
'weeks': 3, | ||
'months': 4, | ||
'years': 5, | ||
} | ||
|
||
class DockerComposer: | ||
def __init__(self, module): | ||
self.module = module | ||
|
||
self.compose_file = self.module.params.get('compose_file') | ||
self.insecure_registry = self.module.params.get('insecure_registry') | ||
self.no_build = self.module.params.get('no_build') | ||
self.no_cache = self.module.params.get('no_cache') | ||
self.no_deps = self.module.params.get('no_deps') | ||
self.no_recreate = self.module.params.get('no_recreate') | ||
self.project_name = self.module.params.get('project_name') | ||
self.stop_timeout = self.module.params.get('stop_timeout') | ||
self.scale = self.module.params.get('scale') | ||
self.service_names = self.module.params.get('service_names') | ||
|
||
|
||
self.project = compose_command.get_project(compose_command(), | ||
self.compose_file, | ||
self.project_name, | ||
) | ||
self.containers = self.project.client.containers(all=True) | ||
|
||
|
||
def build(self): | ||
self.project.build(no_cache = self.no_cache, | ||
service_names = self.service_names, | ||
) | ||
|
||
def kill(self): | ||
self.project.kill(signal = self.kill_signal, | ||
service_names = self.service_names, | ||
) | ||
|
||
def pull(self): | ||
self.project.pull(insecure_registry = self.insecure_registry, | ||
service_names = self.service_names, | ||
) | ||
|
||
def rm(self): | ||
self.stop() | ||
self.project.remove_stopped(service_names = self.service_names) | ||
|
||
def scale(self): | ||
for s in self.service_names: | ||
try: | ||
num = int(self.scale[s]) | ||
except ValueError: | ||
msg = ('Value for scaling service "%s" should be an int, but ' | ||
'value "%s" was recieved' % (s, self.scale[s])) | ||
module.fail_json(msg=msg, failed=True) | ||
|
||
try: | ||
project.get_service(s).scale(num) | ||
except CannotBeScaledError: | ||
msg = ('Service "%s" cannot be scaled because it specifies a ' | ||
'port on the host.' % s) | ||
module.fail_json(msg=msg, failed=True) | ||
|
||
def start(self): | ||
self.project.start(service_names = self.service_names) | ||
|
||
def stop(self): | ||
self.project.stop(service_names = self.service_names, | ||
timeout = self.stop_timeout, | ||
) | ||
|
||
def restart(self): | ||
self.project.restart(service_names = self.service_names) | ||
|
||
def up(self): | ||
self.project_contains = self.project.up( | ||
detach = True, | ||
do_build = not self.no_build, | ||
insecure_registry = self.insecure_registry, | ||
recreate = not self.no_recreate, | ||
service_names = self.service_names, | ||
start_deps = not self.no_deps, | ||
) | ||
|
||
def check_if_changed(self): | ||
new_containers = self.project.client.containers(all=True) | ||
|
||
for pc in self.project_contains: | ||
old_container = None | ||
new_container = None | ||
name = '/' + re.split(' |>',str(pc))[1] | ||
|
||
for c in self.containers: | ||
if c['Names'][0] == name: | ||
old_container = c | ||
|
||
for c in new_containers: | ||
if c['Names'][0] == name: | ||
new_container = c | ||
|
||
if not old_container or not new_container: | ||
return True | ||
|
||
if old_container['Created'] != new_container['Created']: | ||
return True | ||
|
||
old_status = re.split(' ', old_container['Status']) | ||
new_status = re.split(' ', new_container['Status']) | ||
|
||
if old_status[0] != new_status[0]: | ||
return True | ||
|
||
if old_status[0] == 'Up': | ||
if TIMEMAP[old_status[-1]] > TIMEMAP[new_status[-1]]: | ||
return True | ||
else: | ||
if TIMEMAP[old_status[-2]] < TIMEMAP[new_status[-2]]: | ||
return True | ||
|
||
return False | ||
|
||
def check_dependencies(module): | ||
if not HAS_DOCKER_COMPOSE: | ||
msg = ('`docker-compose` does not seem to be installed, but is required ' | ||
'by the Ansible docker-compose module.') | ||
module.fail_json(failed=True, msg=msg) | ||
|
||
def main(): | ||
module = AnsibleModule( | ||
argument_spec = dict( | ||
command = dict(required=True, | ||
choices=['build', 'kill', 'pull', 'rm', | ||
'scale', 'start', 'stop', | ||
'restart', 'up'] | ||
), | ||
compose_file = dict(required=True, type='str'), | ||
insecure_registry = dict(type='bool'), | ||
kill_signal = dict(default='SIGKILL'), | ||
no_build = dict(type='bool'), | ||
no_cache = dict(type='bool'), | ||
no_deps = dict(type='bool'), | ||
no_recreate = dict(type='bool'), | ||
project_name = dict(type='str'), | ||
scale = dict(type='dict'), | ||
service_names = dict(type='list'), | ||
stop_timeout = dict(default=10, type='int') | ||
) | ||
) | ||
|
||
check_dependencies(module) | ||
|
||
|
||
try: | ||
composer = DockerComposer(module) | ||
command = getattr(composer, module.params.get('command')) | ||
|
||
command() | ||
|
||
changed = composer.check_if_changed() | ||
|
||
module.exit_json(changed=changed) | ||
except Exception, e: | ||
try: | ||
changed = composer.check_if_changed() | ||
except Exception: | ||
changed = True | ||
|
||
module.exit_json(failed=True, changed=changed, msg=repr(e)) | ||
|
||
|
||
# import module snippets | ||
from ansible.module_utils.basic import * | ||
|
||
if __name__ == '__main__': | ||
main() |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
in general missing required: false and the default
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Aren't required: false and default=None the defaults here? Or do they need to be explicitly set?
I see no best practice for this and many modules have missing "required" and "default" fields if it is a requirement.