- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with the docker module
- Reference - Types reference and additional functionalities
- Hiera integration
- Contact
This module implements native types and providers to manage some aspects of Docker. The providers are fully idempotent and they only rely on the docker metadata.
For docker containers, when changing parameters that cannot be updated without restarting the container, there's an optional boolean flag called remove_on_change which allows to you either remove the container or rename it to a random UUID.
Docker 1.12.1 or above is highly recommended.
The docker module allows to automate the configuration and runtime of containers as well as the deployment of images, networks and volumes.
The module requires the docker-api rubygem. It also requires Puppet >= 4.0.0.
Install the rubygem as follows:
/opt/puppetlabs/puppet/bin/gem install docker-api
The include the main class as follows:
include docker
docker
include docker
Docker images in the form of {'image_name' => { .. }}
Docker containers in the form of {'container_name' => { .. }}
Docker networks in the form of {'network_name' => { .. }}
Docker volumes in the form of {'volume_name' => { .. }}
Docker daemon options in the form of {'option' => 'value'}.
Defaults to:
docker::opts:
'host':
- 'unix://$unix_socket'
'log-driver': journald
Docker UNIX socket. Defaults to /var/run/docker.sock
.
Whether to store the data on a logical volume (default: false)
Path to the docker configuration directory (default: '/etc/docker')
Path to the docker daemon configuration file (default: '$config_dir/daemon.json')
Whether we should manage the docker configuration file or not (default: true)
Installation packge for Docker (default: 'docker')
Docker service name (default: 'docker')
Whether we should manage the service runtime or not (default: true)
Whether the resource is running or not. Valid values are running
, stopped
. (default: running
)
Whether the service is onboot enabled or not. Defaults to true.
docker::lvm
Logical volume name
Logical volume group
File system type. Supported types are xfs
, ext4
.
File system options
Mount options
docker::gc
Images to exclude from garbage collection
Containers to exclude from garbage collection
Docker garbage collection options in the form of {'option' => 'value'}.
Defaults to:
docker::gc::opts:
grace_period_seconds: 3600
force_container_removal: false
force_image_removal: false
State directory. Defaults to /var/lib/docker-gc
.
Log file. Defaults to /var/log/docker-gc.log
.
Configuration directory. Defaults to /etc/docker-gc
.
Docker image name. Defaults to spotify/docker-gc:latest
Cron definition
Whether docker-gc is enabled or not. Defaults to false
.
docker_image
manages Docker images
docker_image {"centos:latest": }
Docker image
Docker image name, defaults to name
Docker image tag, defaults to name
Whether the resource is present or not. Valid values are present
, absent
. Defaults to present
.
Force image removal. Must be a Boolean, defaults to false
.
docker_container
manages Docker containers
docker_container {"helloworld":
image => "centos:latest",
cmd => ["/usr/bin/sleep", "100"],
ensure => "running"
Note that only the following parameters can be changed without re-creating the container:
- blkio_weight
- cpu_shares
- cpu_period
- cpu_quota
- cpuset_cpus
- cpuset_mems
- memory
- memory_swap
- memory_reservation
- kernel_memory
- restart_policy
Docker container name
When set to true, log, remove and re-create the container when changing non-runtime parameters. When false, the container will be renamed to a random UUID before re-creating it. Valid values are true or false. Defaults to false.
A string specifying the image name to use for the container.
Whether the resource is present or not. Valid values are present
, running
, stopped
, absent
. Defaults to present
.
A string value containing the hostname to use for the container. This must be a valid RFC 1123 hostname.
A string value containing the domain name to use for the container
A string value specifying the user inside the container
Boolean value, attaches to stdin.
Boolean value, attaches to stdout.
Boolean value, attaches to stderr.
Boolean value, Attach standard streams to a tty, including stdin if it is not closed.
Boolean value, opens stdin.
Boolean value, close stdin after the 1 attached client disconnects.
A list of environment variables in the form of ["VAR=value", "VAR2=value2" ..]
Command to run specified as a string or an array of strings
Set the entry point for the container as a string or an array of strings.
Adds a map of labels to a container. To specify a map: {"key":"value"[,"key2":"value2"]}.
An object mapping mount point paths (strings) inside the container to empty objects.
A string specifying the working directory for commands to run in.
Boolean value, when true disables networking for the container
Signal to stop a container as a string or unsigned integer. SIGTERM by default.
A list of volume bindings for this container. Each volume binding is a string in one of these forms:
- host_path:container_path to bind-mount a host path into the container
- host_path:container_path:ro to make the bind-mount read-only inside the container.
- volume_name:container_path to bind-mount a volume managed by a volume plugin into the container.
- volume_name:container_path:ro to make the bind mount read-only inside the container.
A list of links for the container. Each link entry should be in the form of container_name:alias.
Memory limit in bytes.
Total memory limit (memory + swap); set -1 to enable unlimited swap. You must use this with memory and make the swap value larger than memory.
Memory soft limit in bytes.
Kernel memory limit in bytes.
An integer value containing the usable percentage of the available CPUs. (Windows daemon only)
An integer value containing the container’s CPU Shares (ie. the relative weight vs other containers).
The length of a CPU period in microseconds.
Microseconds of CPU time that the container can get in a CPU period.
String value containing the cgroups CpusetCpus to use.
Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
Maximum IO absolute rate in terms of IOps.
Maximum IO absolute rate in terms of bytes per second.
Block IO weight (relative weight) accepts a weight value between 10 and 1000.
Block IO weight (relative device weight) in the form of: [{"Path": "device_path", "Weight": weight}]
Limit read rate (bytes per second) from a device in the form of: [{"Path": "device_path", "Rate": rate}], for example: [{"Path": "/dev/sda", "Rate": "1024"}]"
Limit write rate (bytes per second) to a device in the form of: [{"Path": "device_path", "Rate": rate}], [{"Path": "/dev/sda", "Rate": "1024"}]"
Tune a container’s memory swappiness behavior. Accepts an integer between 0 and 100.
Boolean value, whether to disable OOM Killer for the container or not.
An integer value containing the score given to the container in order to tune OOM killer preferences.
Set the PID (Process) Namespace mode for the container; "container:<name|id>": joins another container’s PID namespace, "host": use the host’s PID namespace inside the container.
Tune a container’s pids limit. Set -1 for unlimited.
A map of exposed container ports and the host port they should map to, in the form of {"/" => [{ "HostPort" => ""}]}. Take note that port is specified as a string and not an integer value.
Allocates a random host port for all of a container’s exposed ports. Specified as a boolean value.
Gives the container full access to the host. Specified as a boolean value.
Mount the container’s root filesystem as read only. Specified as a boolean value.
A list of DNS servers for the container to use.
A list of DNS options
A list of DNS search domains
A list of hostnames/IP mappings to add to the container’s /etc/hosts file. Specified in the form ["hostname:IP"].
A list of volumes to inherit from another container. Specified in the form [:<ro|rw>].
A list of kernel capabilities to add to the container.
A list of kernel capabilities to drop from the container.
A list of additional groups that the container process will run as
The behavior to apply when the container exits. The value is one of: on-failure:<maximum_number_of_retries>, always, unless-stopped.
Sets the usernamespace mode for the container when usernamespace remapping option is enabled. supported values are: host.
Sets the networking mode for the container. Supported standard values are: bridge, host, none, and container:<name|id>. Any other value is taken as a custom network’s name to which this container should connect to.
A list of devices to add to the container specified in the form {"PathOnHost" => "/dev/deviceName", "PathInContainer" => "/dev/deviceName", "CgroupPermissions": "mrw"}.
A list of ulimits to set in the container, specified as {"Name" => , "Soft" => , "Hard" => }, for example: {"Name" => "nofile", "Soft" => 1024, "Hard" => 2048}.
A list of kernel parameters (sysctls) to set in the container, specified as { => }, for example: {"net.ipv4.ip_forward" => "1" }.
A list of string values to customize labels for MLS systems, such as SELinux.
Storage driver options per container. Options can be passed in the form {"size" => "120G"}.
Logging driver. Available types are: json-file, syslog, journald, gelf, fluentd, awslogs, splunk, etwlogs, none, json-file
Logging driver options, specified as {"key1" => "value1"}
Path to cgroups under which the container’s cgroup is created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups are created if they do not already exist.
Driver that this container users to mount volumes.
Size of /dev/shm in bytes. The size must be greater than 0. If omitted the system uses 64MB.
docker_volume
manages Docker volumes
docker_volume {"data":
ensure => "present"
}
Docker volume name
Whether the resource is present or not. Valid values are present
, absent
. Defaults to present
.
Name of the volume driver to use
A mapping og driver options and values.
Labels to set on the volume, specified as a map: {"key" => "value","key2" => "value2"}
docker_network
manages Docker networks
docker_network {"fast":
ensure => "present"
}
Docker network name
Whether the resource is present or not. Valid values are present
, absent
. Defaults to present
.
Requests daemon to check for networks with same name
Name of the network driver plugin to use
Restrict external access to the network
Optional custom IP scheme for the network
Enable IPv6 on the network
Network specific options to be used by the drivers
Labels to set on the network, specified as a map: {"key" => "value","key2" => "value2"}
You can optionally define your images, containers, volumes and networks in Hiera.
---
docker::images:
"centos:latest":
ensure: "present"
docker::containers:
"mycontainer":
image: "centos:latest"
cmd: ["/usr/bin/sleep", "60"]
ensure: "running"
docker::networks:
"prod":
ensure: "present"
docker::volumes:
"data":
ensure: "present"
Matteo Cerutti - [email protected]