From 6505ce3940ecf339c4782bcad365cfdc5a53edbb Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Fri, 12 Dec 2014 11:01:08 -0500 Subject: [PATCH] Another documentation commit. --- lib/ansible/modules/cloud/docker/docker.py | 367 ++++++++++----------- 1 file changed, 166 insertions(+), 201 deletions(-) diff --git a/lib/ansible/modules/cloud/docker/docker.py b/lib/ansible/modules/cloud/docker/docker.py index 3b54c2d6639..645f466f26d 100644 --- a/lib/ansible/modules/cloud/docker/docker.py +++ b/lib/ansible/modules/cloud/docker/docker.py @@ -27,335 +27,300 @@ module: docker version_added: "1.4" short_description: manage docker containers description: - - Manage the life cycle of docker containers. +- Manage the life cycle of docker containers. options: count: description: - - Set number of containers to run - required: False + - Number of matching containers that should be in the desired state. default: 1 - aliases: [] image: description: - - Set container image to use + - Container image used to match and launch containers. required: true - default: null - aliases: [] + pull: + description: + - Control when container images are updated from the C(docker_url) registry. + - If "missing," images will be pulled only when missing from the host; if + - '"always," the registry will be checked for a newer version of the image' + - each time the task executes. + default: missing + choices: [ "missing", "always" ] + version_added: "1.9" command: description: - - Set command to run in a container on startup - required: false + - Command used to match and launch containers. default: null - aliases: [] name: description: - - Set name for container (used to find single container or to provide links) - required: false + - Name used to match and uniquely name launched containers. Explicit names + - are used to uniquely identify a single container or to link among + - containers. Mutually exclusive with a "count" other than "1". default: null - aliases: [] version_added: "1.5" ports: description: - - Set private to public port mapping specification using docker CLI-style syntax [([:[host_port]])|():][/udp] - required: false + - List containing private to public port mapping specification. Use docker + - 'CLI-style syntax: C(8000), C(9000:8000), or C(0.0.0.0:9000:8000) where' + - 8000 is a container port, 9000 is a host port, and 0.0.0.0 is a host + - interface. default: null - aliases: [] version_added: "1.5" expose: description: - - Set container ports to expose for port mappings or links. (If the port is already exposed using EXPOSE in a Dockerfile, you don't need to expose it again.) - required: false + - List of additional container ports to expose for port mappings or links. + - If the port is already exposed using EXPOSE in a Dockerfile, you don't + - need to expose it again. default: null - aliases: [] version_added: "1.5" publish_all_ports: description: - - Publish all exposed ports to the host interfaces - required: false + - Publish all exposed ports to the host interfaces. default: false - aliases: [] version_added: "1.5" volumes: description: - - Set volume(s) to mount on the container + - List of volumes to mount within the container using docker CLI-style + - 'syntax: C(/host:/container[:mode]) where "mode" may be "rw" or "ro".' required: false default: null - aliases: [] volumes_from: description: - - Set shared volume(s) from another container - required: false + - List of names of containers to mount volumes from. default: null - aliases: [] links: description: - - Link container(s) to other container(s) (e.g. links=redis,postgresql:db) - required: false + - List of other containers to link within this container with an optional + - 'alias. Use docker CLI-style syntax: C(redis:myredis).' default: null - aliases: [] version_added: "1.5" memory_limit: description: - - Set RAM allocated to container. It will be passed as a number of bytes. For example 1048576 = 1Gb + - RAM allocated to the container as a number of bytes or as a human-readable + - string like "512MB". Leave as "0" to specify no limit. required: false default: null aliases: [] default: 256MB docker_url: description: - - URL of docker host to issue commands to - required: false - default: unix://var/run/docker.sock - aliases: [] + - URL of the host running the docker daemon. This will default to the env + - var DOCKER_HOST if unspecified. + default: ${DOCKER_HOST} or unix://var/run/docker.sock + docker_tls_cert: + description: + - Path to a PEM-encoded client certificate to secure the Docker connection. + default: ${DOCKER_CERT_PATH}/cert.pem + docker_tls_key: + description: + - Path to a PEM-encoded client key to secure the Docker connection. + default: ${DOCKER_CERT_PATH}/key.pem + docker_tls_cacert: + description: + - Path to a PEM-encoded certificate authority to secure the Docker connection. + default: ${DOCKER_CERT_PATH}/ca.pem docker_api_version: description: - - Remote API version to use. This defaults to the current default as specified by docker-py. - required: false + - Remote API version to use. This defaults to the current default as + - specified by docker-py. default: docker-py default remote API version - aliases: [] version_added: "1.8" username: description: - - Set remote API username - required: false + - Remote API username. default: null - aliases: [] password: description: - - Set remote API password - required: false + - Remote API password. default: null - aliases: [] email: description: - - Set remote API email - required: false + - Remote API email. default: null - aliases: [] hostname: description: - - Set container hostname - required: false + - Container hostname. default: null - aliases: [] domainname: description: - - Set container domain name - required: false + - Container domain name. default: null - aliases: [] env: description: - - Set environment variables (e.g. env="PASSWORD=sEcRe7,WORKERS=4") - required: false + - Pass a dict of environment variables to the container. default: null - aliases: [] dns: description: - - Set custom DNS servers for the container + - List of custom DNS servers for the container. required: false default: null - aliases: [] detach: description: - - Enable detached mode on start up, leaves container running in background - required: false + - Enable detached mode to leave the container running in background. default: true - aliases: [] state: description: - - Set the state of the container + - Assert the container's desired state. "present" only asserts that the + - matching containers exist. "started" asserts that the matching containers + - both exist and are running, but takes no action if any configuration has + - changed. "reloaded" asserts that all matching containers are running and + - restarts any that have any images or configuration out of date. "restarted" + - unconditionally restarts (or starts) the matching containers. "stopped" and + - '"killed" stop and kill all matching containers. "absent" stops and then' + - removes any matching containers. required: false default: present - choices: [ "present", "running", "stopped", "absent", "killed", "restarted" ] - aliases: [] + choices: + - present + - started + - reloaded + - restarted + - killed + - absent privileged: description: - - Set whether the container should run in privileged mode - required: false + - Whether the container should run in privileged mode or not. default: false - aliases: [] lxc_conf: description: - - LXC config parameters, e.g. lxc.aa_profile:unconfined - required: false - default: - aliases: [] - name: - description: - - Set the name of the container (cannot use with count) - required: false + - LXC configuration parameters, such as C(lxc.aa_profile:unconfined). default: null - aliases: [] - version_added: "1.5" stdin_open: description: - - Keep stdin open - required: false + - Keep stdin open after a container is launched. default: false - aliases: [] version_added: "1.6" tty: description: - - Allocate a pseudo-tty - required: false + - Allocate a pseudo-tty within the container. default: false - aliases: [] version_added: "1.6" net: description: - - Set Network mode for the container (bridge, none, container:, host). Requires docker >= 0.11. - required: false + - 'Network mode for the launched container: bridge, none, container:' + - or host. Requires docker >= 0.11. default: false - aliases: [] version_added: "1.8" registry: description: - - The remote registry URL to use for pulling images. - required: false - default: '' + - Remote registry URL to pull images from. + default: DockerHub aliases: [] version_added: "1.8" restart_policy: description: - - Set the container restart policy - required: false - default: false - aliases: [] + - Container restart policy. + choices: ["no", "on-failure", "always"] + default: null version_added: "1.9" restart_policy_retry: description: - - Set the retry limit for container restart policy - required: false - default: false - aliases: [] + - Maximum number of times to restart a container. Leave as "0" for unlimited + - retries. + default: 0 version_added: "1.9" insecure_registry: description: - - Use insecure private registry by HTTP instead of HTTPS (needed for docker-py >= 0.5.0). - required: false + - Use insecure private registry by HTTP instead of HTTPS. Needed for + - docker-py >= 0.5.0. default: false - aliases: [] version_added: "1.9" -author: Cove Schneider, Joshua Conner, Pavel Antonov +author: Cove Schneider, Joshua Conner, Pavel Antonov, Ash Wilson requirements: [ "docker-py >= 0.3.0", "docker >= 0.10.0" ] ''' EXAMPLES = ''' -Start one docker container running tomcat in each host of the web group and bind tomcat's listening port to 8080 -on the host: +# Containers are matched either by name (if provided) or by an exact match of +# the image they were launched with and the command they're running. The module +# can accept either a name to target a container uniquely, or a count to operate +# on multiple containers at once when it makes sense to do so. -- hosts: web - sudo: yes - tasks: - - name: run tomcat servers - docker: image=centos command="service tomcat6 start" ports=8080 +# Ensure that a data container with the name "mydata" exists. If no container +# by this name exists, it will be created, but not started. -The tomcat server's port is NAT'ed to a dynamic port on the host, but you can determine which port the server was -mapped to using docker_containers: +- name: data container + docker: + name: mydata + image: busybox + state: present + volumes: + - /data -- hosts: web - sudo: yes - tasks: - - name: run tomcat servers - docker: image=centos command="service tomcat6 start" ports=8080 count=5 - - name: Display IP address and port mappings for containers - debug: msg={{inventory_hostname}}:{{item['HostConfig']['PortBindings']['8080/tcp'][0]['HostPort']}} - with_items: docker_containers +# Ensure that a Redis server is running, using the volume from the data +# container. Expose the default Redis port. -Just as in the previous example, but iterates over the list of docker containers with a sequence: +- name: redis container + docker: + name: myredis + image: redis + command: redis-server --appendonly yes + state: started + expose: + - 6379 + volumes_from: + - mydata -- hosts: web - sudo: yes - vars: - start_containers_count: 5 - tasks: - - name: run tomcat servers - docker: image=centos command="service tomcat6 start" ports=8080 count={{start_containers_count}} - - name: Display IP address and port mappings for containers - debug: msg="{{inventory_hostname}}:{{docker_containers[{{item}}]['HostConfig']['PortBindings']['8080/tcp'][0]['HostPort']}}" - with_sequence: start=0 end={{start_containers_count - 1}} +# Ensure that a container of your application server is running. This will: +# - pull the latest version of your application image from DockerHub. +# - ensure that a container is running with the specified name and exact image. +# If any configuration options have changed, the existing container will be +# stopped and removed, and a new one will be launched in its place. +# - link this container to the existing redis container launched above with +# an alias. +# - bind TCP port 9000 within the container to port 8080 on all interfaces +# on the host. +# - bind UDP port 9001 within the container to port 8081 on the host, only +# listening on localhost. +# - set the environment variable SECRET_KEY to "ssssh". -Stop, remove all of the running tomcat containers and list the exit code from the stopped containers: +- name: application container + docker: + name: myapplication + image: someuser/appimage + state: reloaded + pull: always + links: + - "myredis:aliasedredis" + ports: + - "8080:9000" + - "127.0.0.1:8081:9001/udp" + env: + SECRET_KEY: ssssh -- hosts: web - sudo: yes - tasks: - - name: stop tomcat servers - docker: image=centos command="service tomcat6 start" state=absent - - name: Display return codes from stopped containers - debug: msg="Returned {{inventory_hostname}}:{{item}}" - with_items: docker_containers +# Ensure that exactly five containers of another server are running with this +# exact image and command. If fewer than five are running, more will be launched; +# if more are running, the excess will be stopped. -Create a named container: +- name: load-balanced containers + docker: + state: reloaded + count: 5 + image: someuser/anotherappimage + command: sleep 1d -- hosts: web - sudo: yes - tasks: - - name: run tomcat server - docker: image=centos name=tomcat command="service tomcat6 start" ports=8080 +# Unconditionally restart a service container. This may be useful within a +# handler, for example. -Create multiple named containers: +- name: application service + docker: + name: myservice + image: someuser/serviceimage + state: restarted -- hosts: web - sudo: yes - tasks: - - name: run tomcat servers - docker: image=centos name={{item}} command="service tomcat6 start" ports=8080 - with_items: - - crookshank - - snowbell - - heathcliff - - felix - - sylvester +# Stop all containers running the specified image. -Create containers named in a sequence: +- name: obsolete container + docker: + image: someuser/oldandbusted + state: stopped -- hosts: web - sudo: yes - tasks: - - name: run tomcat servers - docker: image=centos name={{item}} command="service tomcat6 start" ports=8080 - with_sequence: start=1 end=5 format=tomcat_%d.example.com - -Create two linked containers: - -- hosts: web - sudo: yes - tasks: - - name: ensure redis container is running - docker: image=crosbymichael/redis name=redis - - - name: ensure redis_ambassador container is running - docker: image=svendowideit/ambassador ports=6379:6379 links=redis:redis name=redis_ambassador_ansible - -Create containers with options specified as key-value pairs and lists: - -- hosts: web - sudo: yes - tasks: - - docker: - image: namespace/image_name - links: - - postgresql:db - - redis:redis - - -Create containers with options specified as strings and lists as comma-separated strings: - -- hosts: web - sudo: yes - tasks: - docker: image=namespace/image_name links=postgresql:db,redis:redis - -Create a container with no networking: - -- hosts: web - sudo: yes - tasks: - docker: image=namespace/image_name net=none +# Stop and remove a container with the specified name. +- name: obsolete container + docker: + name: ohno + image: someuser/oldandbusted + state: absent ''' HAS_DOCKER_PY = True @@ -494,7 +459,7 @@ class DockerManager(object): if len(parts) == 2: self.volumes[parts[1]] = {} self.binds[parts[0]] = parts[1] - # with bind mode + # with bind mode elif len(parts) == 3: if parts[2] not in ['ro', 'rw']: self.module.fail_json(msg='bind mode needs to either be "ro" or "rw"')