ansible/docs/proposals/docker/docker_container_moduler.md

# Docker_Container Module Proposal

## Purpose and Scope:

The purpose of docker_container is to manage the lifecycle of a container. The module will provide a mechanism for
moving the container between absent, present, stopped and started states. It will focus purely on managing container
state. The intention of the narrow focus is to make understanding and using the module clear and to keep maintenance
and testing as easy as possible.

Docker_container will manage a container using docker-py to communicate with either a local or remote API. It will
support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar to
how other cloud modules operate.

The container world is moving rapidly, so the goal is to create a suite of docker modules that keep pace, with docker_container
leading the way. If this project is successful, it will naturally deprecate the existing docker module.

## Parameters:

Docker_container will accept the parameters listed below. An attempt has been made to represent all the options available to
docker's create, kill, pause, run, rm, start, stop and update commands.

Parameters related to connecting to the API are not listed here.

```
blkio_weight:
  description:
    - Block IO weight
  default: null

blkio_weight_devices:
  description:
    - List of C(DEVICE_NAME:WEIGHT) pairs
  default: null

capabilities:
  description:
    - List of capabilities to add to the container.
  default: null

capabilities_drop:
  description:
    - List of capabilities to remove from the container
  default: null

cgroup_parent:
  description:
    - Optional parent cgroup for the container
  default: null

command:
  description:
    - Command executed in the container when it starts.
  default: null

cpu_period:
  description:
    - Limit CPU CFS (Completely Fair Scheduler) period. Expressed in milliseconds.
  default: 0

cpu_quota:
  description:
    - Limit CPU CFS (Completely Fair Scheduler) quota. Expressed in milliseconds.
  default: 0

cpuset_cpus:
  description:
    - CPUs in which to allow execution C(1,3) or C(1-3).
  default: null

cpuset_mems:
  description:
    - Memory nodes (MEMs) in which to allow execution C(0-3) or C(0,1)
  default: null

cpu_shares:
  description:
    - CPU shares. Integer value.
  default: 0

detach:
  description:
    - Enable detached mode to leave the container running in background. 
      If disabled, fail unless the process exits cleanly.
  default: true

devices:
  description:
    - List of host devices to add to the container
  default: null

device_read_bps
  description:
    - List. Limit read rate (bytes per second) from a device in the format C(/dev/sda:1mb)
  default: null

device_read_iops:
  description:
    - List. Limit read rate (IO per second) from a device in the format C(/dev/sda:1000)
  default: null

device_write_bps:
  description:
    - List. Limit write rate (bytes per second) to a device in the foramt C(/dev/sda:1mb)
  default: null

device_write_iops:
  description:
    - List. Limit write rate (IO per second) to a device C(/dev/sda:1000)
  default: null

dns_servers:
  description:
    - List of custom DNS servers.
  default: null

dns_opts:
  description:
    - List of custom DNS options. Each option is written as an options line
      into the container's /etc/resolv.conf.
  default: null

dns_search_domains:
  description:
    - List of custom DNS search domains.
  default: null

env_vars:
  description:
    - Dictionary of key,value pairs.
  default: null

entrypoint:
  description:
    - Overwrite the default ENTRYPOINT of the image.
  default: null

etc_hosts:
  description:
    - List of custom host-to-IP mappings, with each mapping in the format C(host:ip), to be
      added to the container's /etc/hosts file.
  default: null

exposed_ports:
  description:
    - List of additional container ports to expose for port mappings or links.
      If the port is already exposed using EXPOSE in a Dockerfile, it does not
      need to be exposed again.
  default: null

force_kill:
  description:
    - Use with absent, present, started and stopped states to use the kill command rather
      than the stop command.
  default: false

groups:
  description:
    - List of additional groups to join.
  default: null

hostname:
  description:
    - Container hostname.
  default: null

image:
  description:
    - Container image used to create and match containers.
  required: true

interactive:
  description:
    - Keep stdin open after a container is launched, even if not attached.
  default: false

ip_address:
  description:
    - Container IPv4 address.
  default: null

ipv6_address:
  description:
    - Container IPv6 address.
  default: null

ipc_namespace:
  description:
    - Container IPC namespace.
  default: null

keep_volumes:
  description:
    - Retain volumes associated with a removed container.
  default: false

kill_signal:
  description:
    - Signal used to kill a running container when state is absent.
  default: KILL

kernel_memory:
  description:
    - Kernel memory limit (format: <number>[<unit>]). Number is a positive integer.
      Unit can be one of b, k, m, or g. Minimum is 4M.
  default: 0

labels:
   description:
     - Set meta data on the cotnainer. Dictionary of key value paris:
   default: null

links:
  description:
    - List of name aliases for linked containers in the format C(redis:myredis)
  default: null

log_driver:
  description:
    - Specify the logging driver.
  choices:
    - json-file
    - syslog
    - journald
    - gelf
    - fluentd
    - awslogs
    - splunk
  defult: json-file

log_opt:
  description:
    - Additional options to pass to the logging driver selected above. See Docker `log-driver
      <https://docs.docker.com/reference/logging/overview/>` documentation for more information.
  required: false
  default: null

mac_address:
  description:
    - Container MAC address (e.g. 92:d0:c6:0a:29:33)
default: null

memory:
  description:
    - Memory limit (format: <number>[<unit>]). Number is a positive integer.
      Unit can be one of b, k, m, or g
  default: 0

memory_reservation:
  description:
    - Memory soft limit (format: <number>[<unit>]). Number is a positive integer.
      Unit can be one of b, k, m, or g
  default: 0

memory_swap:
  description:
    - Total memory limit (memory + swap, format:<number>[<unit>]).
      Number is a positive integer. Unit can be one of b, k, m, or g.
  default: 0

memory_swapiness:
    description:
      - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
    default: 0

name:
  description:
    - Assign a name to a new container or match an existing container.
    - When identifying an existing container name may be a name or a long or short container ID.
  required: true

net:
  description:
    - Connect the container to a network.
  choices:
    - bridge
    - container:<name|id>
    - host
  default: null

net_alias:
  description:
    - Add network scoped alias to the container.
  default: null

paused:
  description:
    - Use with the started state to pause running processes inside the container.
  default: false

pid:
  description:
    - Set the PID namespace mode for the container. Currenly only supports 'host'.
  default: null

privileged:
  description:
    - Give extended privileges to the container.
  default: false

published_ports:
  description:
    - List of ports to publish from the container to the host.
    - Use docker CLI 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.
    - Container ports must be exposed either in the Dockerfile or via the C(expose) option.
    - A value of ALL will publish all exposed container ports to random host ports, ignoring
      any other mappings.

read_only:
  description:
    - Mount the container's root file system as read-only.
  default: false

recreate:
  description:
    - Use with present and started states to force the re-creation of an existing container.
  default: false

restart:
  description:
    - Use with started state to force a matching container to be stopped and restarted.
  default: false

restart_policy:
  description:
    - Container restart policy.
  choices:
    - no
    - on-failure
    - always
    - unless-stopped
  default: no

restart_policy_retry:
   description:
     - When C(restart_policy) is on-failure sets the max number of retries.
   default: 0

shm_size:
  description:
    - Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. 
      Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes).
    - Ommitting the unit defaults to bytes. If you omit the size entirely, the system uses `64m`.
  default: null

security_opts:
  description:
    - List of security options in the form of C("label:user:User")
  default: null

state:
  description:
    - "absent" - A container matching the specified name will be stopped and removed. Use force_kill to kill the container
       rather than stopping it. Use keep_volumes to retain volumes associated with the removed container.

    - "present" - Asserts the existence of a container matching the name and any provided configuration parameters. If no
      container matches the name, a container will be created. If a container matches the name but the provided configuration
      does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed and re-created
      with the requested config. Use recreate to force the re-creation of the matching container. Use force_kill to kill the
      container rather than stopping it. Use keep_volumes to retain volumes associated with a removed container.

    - "started" - Asserts there is a running container matching the name and any provided configuration. If no container
      matches the name, a container will be created and started. If a container matching the name is found but the
      configuration does not match, the container will be updated, if it can be. If it cannot be updated, it will be removed
      and a new container will be created with the requested configuration and started. Use recreate to always re-create a 
      matching container, even if it is running. Use restart to force a matching container to be stopped and restarted. Use
      force_kill to kill a container rather than stopping it. Use keep_volumes to retain volumes associated with a removed
      container.

    - "stopped" - a container matching the specified name will be stopped. Use force_kill to kill a container rather than
      stopping it.

  required: false
  default: started
  choices:
    - absent
    - present
    - stopped
    - started

stop_signal:
  description:
    - Signal used to stop the container.
  default: SIGINT

stop_timeout:
  description:
    - Number of seconds to wait for the container to stop before sending SIGKILL.
  required: false

trust_image_content:
  description:
    - If true, skip image verification.
  default: false

tty:
  description:
    - Allocate a psuedo-TTY.
  default: false

ulimit:
  description:
    - List of ulimit options. A ulimit is specified as C(nofile=262144:262144)
  default: null

user:
  description
    - Sets the username or UID used and optionally the groupname or GID for the specified command.
    - Can be [ user | user:group | uid | uid:gid | user:gid | uid:group ]
  default: null

uts:
  description:
    - Set the UTS namespace mode for the container.
  default: null

volumes:
  description:
    - List of volumes to mount within the container.
    - 'Use docker CLI-style syntax: C(/host:/container[:mode])'
    - You can specify a read mode for the mount with either C(ro) or C(rw).
      Starting at version 2.1, SELinux hosts can additionally use C(z) or C(Z)
      mount options to use a shared or private label for the volume.
default: null

volumes_from:
  description:
    - List of container names to mount volumes from.
  default: null
```


## Examples:

```
- name: Create a data container
  docker_container:
    name: mydata
    image: busybox
    volumes:
      - /data

- name: Re-create a redis container
  docker_container:
    name: myredis
    image: redis
    command: redis-server --appendonly yes
    state: present
    recreate: yes
    expose:
      - 6379
    volumes_from:
      - mydata

- name: Restart a container
  docker_container:
    name: myapplication
    image: someuser/appimage
    state: started 
    restart: yes
    links:
     - "myredis:aliasedredis"
    devices:
     - "/dev/sda:/dev/xvda:rwm"
    ports:
     - "8080:9000"
     - "127.0.0.1:8081:9001/udp"
    env:
        SECRET_KEY: ssssh


- name: Container present
  docker_container:
    name: mycontainer
    state: present
    recreate: yes
    forcekill: yes
    image: someplace/image
    command: echo "I'm here!"


- name: Start 4 load-balanced containers
  docker_container:
    name: "container{{ item }}"
    state: started
    recreate: yes
    image: someuser/anotherappimage
    command: sleep 1d
  with_sequence: count=4

-name: remove container
  docker_container:
    name: ohno
    state: absent

- name: Syslogging output 
  docker_container:
    name: myservice
    state: started 
    log_driver: syslog
    log_opt:
      syslog-address: tcp://my-syslog-server:514
      syslog-facility: daemon
      syslog-tag: myservice

```

## Returns:

The JSON object returned by the module will include a *results* object providing `docker inspect` output for the affected container.

```
{
    changed: True,
    results: {
        < the results of `docker inspect` >
    }
}
```

## Contributors

[chouseknecht](http://twitter.com/chouseknecht)

*Last Updated:* 2016-02-24