cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Another documentation commit.

Browse source
This commit is contained in:
Ash Wilson 2014-12-12 11:01:08 -05:00 committed by Matt Clay
parent 43ef3a2bd9
commit 6505ce3940
1 changed files with 166 additions and 201 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

365
lib/ansible/modules/cloud/docker/docker.py
View file

@ -31,331 +31,296 @@ description:
options: options:
count: count:
description: description:
- Set number of containers to run - Number of matching containers that should be in the desired state.
required: False
default: 1 default: 1
aliases: []
image: image:
description: description:
- Set container image to use - Container image used to match and launch containers.
required: true 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: command:
description: description:
- Set command to run in a container on startup - Command used to match and launch containers.
required: false
default: null default: null
aliases: []
name: name:
description: 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 default: null
aliases: []
version_added: "1.5" version_added: "1.5"
ports: ports:
description: 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 default: null
aliases: []
version_added: "1.5" version_added: "1.5"
expose: expose:
description: 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 default: null
aliases: []
version_added: "1.5" version_added: "1.5"
publish_all_ports: publish_all_ports:
description: description:
- Publish all exposed ports to the host interfaces - Publish all exposed ports to the host interfaces.
required: false
default: false default: false
aliases: []
version_added: "1.5" version_added: "1.5"
volumes: volumes:
description: 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 required: false
default: null default: null
aliases: []
volumes_from: volumes_from:
description: description:
- Set shared volume(s) from another container - List of names of containers to mount volumes from.
required: false
default: null default: null
aliases: []
links: links:
description: 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 default: null
aliases: []
version_added: "1.5" version_added: "1.5"
memory_limit: memory_limit:
description: 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 required: false
default: null default: null
aliases: [] aliases: []
default: 256MB default: 256MB
docker_url: docker_url:
description: 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: docker_api_version:
description: 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 default: docker-py default remote API version
aliases: []
version_added: "1.8" version_added: "1.8"
username: username:
description: description:
- Set remote API username - Remote API username.
required: false
default: null default: null
aliases: []
password: password:
description: description:
- Set remote API password - Remote API password.
required: false
default: null default: null
aliases: []
email: email:
description: description:
- Set remote API email - Remote API email.
required: false
default: null default: null
aliases: []
hostname: hostname:
description: description:
- Set container hostname - Container hostname.
required: false
default: null default: null
aliases: []
domainname: domainname:
description: description:
- Set container domain name - Container domain name.
required: false
default: null default: null
aliases: []
env: env:
description: description:
- Set environment variables (e.g. env="PASSWORD=sEcRe7,WORKERS=4") - Pass a dict of environment variables to the container.
required: false
default: null default: null
aliases: []
dns: dns:
description: description:
- Set custom DNS servers for the container - List of custom DNS servers for the container.
required: false required: false
default: null default: null
aliases: []
detach: detach:
description: 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 default: true
aliases: []
state: state:
description: 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 required: false
default: present default: present
choices: [ "present", "running", "stopped", "absent", "killed", "restarted" ] choices:
aliases: [] - present
- started
- reloaded
- restarted
- killed
- absent
privileged: privileged:
description: description:
- Set whether the container should run in privileged mode - Whether the container should run in privileged mode or not.
required: false
default: false default: false
aliases: []
lxc_conf: lxc_conf:
description: 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 default: null
aliases: []
version_added: "1.5"
stdin_open: stdin_open:
description: description:
- Keep stdin open - Keep stdin open after a container is launched.
required: false
default: false default: false
aliases: []
version_added: "1.6" version_added: "1.6"
tty: tty:
description: description:
- Allocate a pseudo-tty - Allocate a pseudo-tty within the container.
required: false
default: false default: false
aliases: []
version_added: "1.6" version_added: "1.6"
net: net:
description: 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 default: false
aliases: []
version_added: "1.8" version_added: "1.8"
registry: registry:
description: description:
- The remote registry URL to use for pulling images. - Remote registry URL to pull images from.
required: false default: DockerHub
default: ''
aliases: [] aliases: []
version_added: "1.8" version_added: "1.8"
restart_policy: restart_policy:
description: 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" version_added: "1.9"
restart_policy_retry: restart_policy_retry:
description: 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" version_added: "1.9"
insecure_registry: insecure_registry:
description: 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 default: false
aliases: []
version_added: "1.9" 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" ] requirements: [ "docker-py >= 0.3.0", "docker >= 0.10.0" ]
''' '''
EXAMPLES = ''' 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:
- hosts: web name: myapplication
sudo: yes image: someuser/appimage
tasks: state: reloaded
- name: stop tomcat servers pull: always
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:
- hosts: web
sudo: yes
tasks:
- name: run tomcat server
docker: image=centos name=tomcat command="service tomcat6 start" ports=8080
Create multiple named containers:
- 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
Create containers named in a sequence:
- 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: links:
- postgresql:db - "myredis:aliasedredis"
- redis:redis ports:
- "8080:9000"
- "127.0.0.1:8081:9001/udp"
env:
SECRET_KEY: ssssh
# 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 containers with options specified as strings and lists as comma-separated strings: - 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:
docker: image=namespace/image_name links=postgresql:db,redis:redis
Create a container with no networking: - name: application service
docker:
name: myservice
image: someuser/serviceimage
state: restarted
- hosts: web # Stop all containers running the specified image.
sudo: yes
tasks:
docker: image=namespace/image_name net=none
- name: obsolete container
docker:
image: someuser/oldandbusted
state: stopped
# Stop and remove a container with the specified name.
- name: obsolete container
docker:
name: ohno
image: someuser/oldandbusted
state: absent
''' '''
HAS_DOCKER_PY = True HAS_DOCKER_PY = True