Another documentation commit.

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
+    - Number of matching containers that should be in the desired state.
-    required: False
     default: 1
-    aliases: []
   image:
     description:
-       - Set container image to use
+    - Container image used to match and launch containers.
     required: true
-    default: null
+  pull:
-    aliases: []
+    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
+    - Command used to match and launch containers.
-    required: false
     default: null
-    aliases: []
   name:
     description:
-       - Set name for container (used to find single container or to provide links)
+    - Name used to match and uniquely name launched containers. Explicit names
-    required: false
+    - 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_interface>:[host_port]])|(<host_port>):]<container_port>[/udp]
+     - List containing private to public port mapping specification. Use docker
-    required: false
+     - '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.)
+    - List of additional container ports to expose for port mappings or links.
-    required: false
+    - 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
+    - Publish all exposed ports to the host interfaces.
-    required: false
     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
+    - List of names of containers to mount volumes from.
-    required: false
     default: null
-    aliases: []
   links:
     description:
-      - Link container(s) to other container(s) (e.g. links=redis,postgresql:db)
+    - List of other containers to link within this container with an optional
-    required: false
+    - '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
+    - URL of the host running the docker daemon. This will default to the env
-    required: false
+    - var DOCKER_HOST if unspecified.
-    default: unix://var/run/docker.sock
+    default: ${DOCKER_HOST} or unix://var/run/docker.sock
-    aliases: []
+  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.
+    - Remote API version to use. This defaults to the current default as
-    required: false
+    - specified by docker-py.
     default: docker-py default remote API version
-    aliases: []
     version_added: "1.8"
   username:
     description:
-      - Set remote API username
+    - Remote API username.
-    required: false
     default: null
-    aliases: []
   password:
     description:
-      - Set remote API password
+    - Remote API password.
-    required: false
     default: null
-    aliases: []
   email:
     description:
-      - Set remote API email
+    - Remote API email.
-    required: false
     default: null
-    aliases: []
   hostname:
     description:
-      - Set container hostname
+    - Container hostname.
-    required: false
     default: null
-    aliases: []
   domainname:
     description:
-      - Set container domain name
+    - Container domain name.
-    required: false
     default: null
-    aliases: []
   env:
     description:
-      - Set environment variables (e.g. env="PASSWORD=sEcRe7,WORKERS=4")
+    - Pass a dict of environment variables to the container.
-    required: false
     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
+    - Enable detached mode to leave the container running in background.
-    required: false
     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" ]
+    choices:
-    aliases: []
+    - present
+    - started
+    - reloaded
+    - restarted
+    - killed
+    - absent
   privileged:
     description:
-      - Set whether the container should run in privileged mode
+    - Whether the container should run in privileged mode or not.
-    required: false
     default: false
-    aliases: []
   lxc_conf:
     description:
-      - LXC config parameters,  e.g. lxc.aa_profile:unconfined
+    - LXC configuration parameters, such as C(lxc.aa_profile:unconfined).
-    required: false
-    default:
-    aliases: []
-  name:
-    description:
-      - Set the name of the container (cannot use with count)
-    required: false
     default: null
-    aliases: []
-    version_added: "1.5"
   stdin_open:
     description:
-      - Keep stdin open
+    - Keep stdin open after a container is launched.
-    required: false
     default: false
-    aliases: []
     version_added: "1.6"
   tty:
     description:
-      - Allocate a pseudo-tty
+    - Allocate a pseudo-tty within the container.
-    required: false
     default: false
-    aliases: []
     version_added: "1.6"
   net:
     description:
-      - Set Network mode for the container (bridge, none, container:<name|id>, host). Requires docker >= 0.11.
+    - 'Network mode for the launched container: bridge, none, container:<name|id>'
-    required: false
+    - or host. Requires docker >= 0.11.
     default: false
-    aliases: []
     version_added: "1.8"
   registry:
     description:
-      - The remote registry URL to use for pulling images.
+    - Remote registry URL to pull images from.
-    required: false
+    default: DockerHub
-    default: ''
     aliases: []
     version_added: "1.8"
   restart_policy:
     description:
-      - Set the container restart policy
+    - Container restart policy.
-    required: false
+    choices: ["no", "on-failure", "always"]
-    default: false
+    default: null
-    aliases: []
     version_added: "1.9"
   restart_policy_retry:
     description:
-      - Set the retry limit for container restart policy
+    - Maximum number of times to restart a container. Leave as "0" for unlimited
-    required: false
+    - retries.
-    default: false
+    default: 0
-    aliases: []
     version_added: "1.9"
   insecure_registry:
     description:
-      - Use insecure private registry by HTTP instead of HTTPS (needed for docker-py >= 0.5.0).
+    - Use insecure private registry by HTTP instead of HTTPS. Needed for
-    required: false
+    - 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
+# Containers are matched either by name (if provided) or by an exact match of
-on the host:
+# 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
+# Ensure that a data container with the name "mydata" exists. If no container
-  sudo: yes
+# by this name exists, it will be created, but not started.
-  tasks:
-  - name: run tomcat servers
-    docker: image=centos command="service tomcat6 start" ports=8080
 
-The tomcat server's port is NAT'ed to a dynamic port on the host, but you can determine which port the server was
+- name: data container
-mapped to using docker_containers:
+  docker:
+    name: mydata
+    image: busybox
+    state: present
+    volumes:
+    - /data
 
-- hosts: web
+# Ensure that a Redis server is running, using the volume from the data
-  sudo: yes
+# container. Expose the default Redis port.
-  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
 
-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
+# Ensure that a container of your application server is running. This will:
-  sudo: yes
+# - pull the latest version of your application image from DockerHub.
-  vars:
+# - ensure that a container is running with the specified name and exact image.
-    start_containers_count: 5
+#   If any configuration options have changed, the existing container will be
-  tasks:
+#   stopped and removed, and a new one will be launched in its place.
-  - name: run tomcat servers
+# - link this container to the existing redis container launched above with
-    docker: image=centos command="service tomcat6 start" ports=8080 count={{start_containers_count}}
+#   an alias.
-  - name: Display IP address and port mappings for containers
+# - bind TCP port 9000 within the container to port 8080 on all interfaces
-    debug: msg="{{inventory_hostname}}:{{docker_containers[{{item}}]['HostConfig']['PortBindings']['8080/tcp'][0]['HostPort']}}"
+#   on the host.
-    with_sequence: start=0 end={{start_containers_count - 1}}
+# - 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
+# Ensure that exactly five containers of another server are running with this
-  sudo: yes
+# exact image and command. If fewer than five are running, more will be launched;
-  tasks:
+# if more are running, the excess will be stopped.
-  - 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
 
-Create a named container:
+- name: load-balanced containers
+  docker:
+    state: reloaded
+    count: 5
+    image: someuser/anotherappimage
+    command: sleep 1d
 
-- hosts: web
+# Unconditionally restart a service container. This may be useful within a
-  sudo: yes
+# handler, for example.
-  tasks:
-  - name: run tomcat server
-    docker: image=centos name=tomcat command="service tomcat6 start" ports=8080
 
-Create multiple named containers:
+- name: application service
+  docker:
+    name: myservice
+    image: someuser/serviceimage
+    state: restarted
 
-- hosts: web
+# Stop all containers running the specified image.
-  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
 
-Create containers named in a sequence:
+- name: obsolete container
+  docker:
+    image: someuser/oldandbusted
+    state: stopped
 
-- hosts: web
+# Stop and remove a container with the specified name.
-  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
 
+- name: obsolete container
+  docker:
+    name: ohno
+    image: someuser/oldandbusted
+    state: absent
 '''
 
 HAS_DOCKER_PY = True