Version information
This version is compatible with:
- Puppet Enterprise 2025.2.x, 2025.1.x, 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
- Puppet >= 7.0.0 < 9.0.0
- , , ,
Tasks:
- node_rm
- node_ls
- node_update
- service_create
Start using this module
Add this module to your Puppetfile:
mod 'puppetlabs-docker', '10.3.0'Learn more about managing modules with a PuppetfileDocumentation
Docker
Table of Contents
- Description
- Setup
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- License
- Development - Guide for contributing to the module
- Acceptance
Description
The Puppet docker module installs, configures, and manages Docker from the Docker repository. It supports the latest Docker CE (Community Edition) for Linux based distributions and Docker EE(Enterprise Edition) for Windows and Linux as well as legacy releases.
Due to the new naming convention for Docker packages, this module prefaces any params that refer to the release with _ce or _engine. Examples of these are documented in this README.
Setup
To create the Docker hosted repository and install the Docker package, add a single class to the manifest file:
include 'docker'
To configure package sources independently and disable automatically including sources, add the following code to the manifest file:
class { 'docker':
use_upstream_package_source => false,
}
The latest Docker repositories are now the default repositories for version 17.06 and above. If you are using an older version, the repositories are still configured based on the version number passed into the module.
To ensure the module configures the latest repositories, add the following code to the manifest file:
class { 'docker':
version => '17.09.0~ce-0~debian',
}
Using a version prior to 17.06, configures and installs from the old repositories:
class { 'docker':
version => '1.12.0-0~wheezy',
}
Docker provides a enterprise addition of the Docker Engine, called Docker EE. To install Docker EE on Debian systems, add the following code to the manifest file:
class { 'docker':
docker_ee => true,
docker_ee_source_location => 'https://<docker_ee_repo_url>',
docker_ee_key_source => 'https://<docker_ee_key_source_url>',
docker_ee_key_id => '<key id>',
}
To install Docker EE on RHEL/CentOS:
class { 'docker':
docker_ee => true,
docker_ee_source_location => 'https://<docker_ee_repo_url>',
docker_ee_key_source => 'https://<docker_ee_key_source_url>',
}
For CentOS distributions, the docker module requires packages from the extras repository, which is enabled by default on CentOS. For more information, see the official CentOS documentation and the official Docker documentation.
For Red Hat Enterprise Linux (RHEL) based distributions, the docker module uses the upstream repositories. To continue using the legacy distribution packages in the CentOS extras repository, add the following code to the manifest file:
class { 'docker':
use_upstream_package_source => false,
service_overrides_template => false,
docker_ce_package_name => 'docker',
}
To use the CE packages, add the following code to the manifest file:
class { 'docker':
use_upstream_package_source => false,
repo_opt => '',
}
By default, the Docker daemon binds to a unix socket at /var/run/docker.sock. To change this parameter and update the binding parameter to a tcp socket, add the following code to the manifest file:
class { 'docker':
tcp_bind => ['tcp://127.0.0.1:2375'],
socket_bind => 'unix:///var/run/docker.sock',
ip_forward => true,
iptables => true,
ip_masq => true,
bip => '192.168.1.1/24',
fixed_cidr => '192.168.1.144/28',
}
For more information about the configuration options for the default docker bridge, see the Docker documentation.
The default group ownership of the Unix control socket differs based on OS. For example, on RHEL using docker-ce packages >=18.09.1, the socket file used by /usr/lib/systemd/system/docker.socket is owned by the docker group. To override this value in /etc/sysconfig/docker and docker.socket (e.g. to use the 'root' group):
class {'docker':
socket_group => 'root',
socket_override => true,
}
The socket_group parameter also takes a boolean for legacy cases where setting -G in /etc/sysconfig/docker is not desired:
docker::socket_group: false
To add another service to the After= line in the [Unit] section of the systemd /etc/systemd/system/service-overrides.conf file, use the service_after_override parameter:
docker::service_after_override: containerd.service
When setting up TLS, upload the related files (CA certificate, server certificate, and key) and include their paths in the manifest file:
class { 'docker':
tcp_bind => ['tcp://0.0.0.0:2376'],
tls_enable => true,
tls_cacert => '/etc/docker/tls/ca.pem',
tls_cert => '/etc/docker/tls/cert.pem',
tls_key => '/etc/docker/tls/key.pem',
}
To specify which Docker rpm package to install, add the following code to the manifest file:
class { 'docker':
manage_package => true,
use_upstream_package_source => false,
package_engine_name => 'docker-engine'
package_source_location => 'https://get.docker.com/rpm/1.7.0/centos-6/RPMS/x86_64/docker-engine-1.7.0-1.el6.x86_64.rpm',
prerequired_packages => [ 'glibc.i686', 'glibc.x86_64', 'sqlite.i686', 'sqlite.x86_64', 'device-mapper', 'device-mapper-libs', 'device-mapper-event-libs', 'device-mapper-event' ]
}
To track the latest version of Docker, add the following code to the manifest file:
class { 'docker':
version => latest,
}
To install docker from a test or edge channel, add the following code to the manifest file:
class { 'docker':
docker_ce_channel => 'test'
}
To allocate a DNS server to the Docker daemon, add the following code to the manifest file:
class { 'docker':
dns => '8.8.8.8',
}
To add users to the Docker group, add the following array to the manifest file:
class { 'docker':
docker_users => ['user1', 'user2'],
}
To add daemon labels, add the following array to the manifest file:
class { 'docker':
labels => ['storage=ssd','stage=production'],
}
To pass additional parameters to the daemon, add extra_parameters to the manifest file:
class { 'docker':
extra_parameters => ['--experimental=true', '--metrics-addr=localhost:9323'],
To uninstall docker, add the following to the manifest file:
class { 'docker':
ensure => absent
}
Only Docker EE is supported on Windows. To install docker on Windows 2016 and above, the docker_ee parameter must be specified:
class { 'docker':
docker_ee => true
}
If the curl package is being managed elsewhere and the curl ensure in this module is conflicting, it can be disabled by setting the following parameter globally or in compose / machine resources:
class { 'docker':
curl_ensure => false
}
Proxy on Windows
To use docker through a proxy on Windows, a System Environment Variable HTTP_PROXY/HTTPS_PROXY must be set. See Docker Engine on Windows This can be done using a different puppet module, such as the puppet-windows_env module. After setting the variable, the docker service must be restarted.
windows_env { 'HTTP_PROXY'
value => 'http://1.2.3.4:80',
notify => Service['docker'],
}
windows_env { 'HTTPS_PROXY'
value => 'http://1.2.3.4:80',
notify => Service['docker'],
}
service { 'docker'
ensure => 'running',
}
Validating and unit testing the module
This module is compliant with the Puppet Development Kit (PDK), which provides tools to help run unit tests on the module and validate the modules' metadata, syntax, and style.
To run all validations against this module, run the following command:
pdk validate
To change validation behavior, add options flags to the command. For a complete list of command options and usage information, see the PDK command reference.
To unit test the module, run the following command:
pdk test unit
To change unit test behavior, add option flags to the command. For a complete list of command options and usage information, see the PDK command reference.
Usage
Images
Each image requires a unique name; otherwise, the installation fails when a duplicate name is detected.
To install a Docker image, add the docker::image defined type to the manifest file:
docker::image { 'base': }
The code above is equivalent to running the docker pull base command. However, it removes the default five-minute execution timeout.
To include an optional parameter for installing image tags that is the equivalent to running docker pull -t="precise" ubuntu, add the following code to the manifest file:
docker::image { 'ubuntu':
image_tag => 'precise'
}
Including the docker_file parameter is equivalent to running the docker build -t ubuntu - < /tmp/Dockerfile command. To add or build an image from a dockerfile that includes the docker_file parameter, add the following code to the manifest file:
docker::image { 'ubuntu':
docker_file => '/tmp/Dockerfile'
}
Including the docker_dir parameter is equivalent to running the docker build -t ubuntu /tmp/ubuntu_image command. To add or build an image from a dockerfile that includes the docker_dir parameter, add the following code to the manifest file:
docker::image { 'ubuntu':
docker_dir => '/tmp/ubuntu_image'
}
To rebuild an image, subscribe to external events such as Dockerfile changes by adding the following code to the manifest file:
docker::image { 'ubuntu':
docker_file => '/tmp/Dockerfile',
subscribe => File['/tmp/Dockerfile'],
}
file { '/tmp/Dockerfile':
ensure => file,
source => 'puppet:///modules/someModule/Dockerfile',
}
To remove an image, add the following code to the manifest file:
docker::image { 'base':
ensure => 'absent'
}
docker::image { 'ubuntu':
ensure => 'absent',
image_tag => 'precise'
}
To configure the docker::images class when using Hiera, add the following code to the manifest file:
---
classes:
- docker::images
docker::images::images:
ubuntu:
image_tag: 'precise'
Containers
To launch containers, add the following code to the manifest file:
docker::run { 'helloworld':
image => 'base',
command => '/bin/sh -c "while true; do echo hello world; sleep 1; done"',
}
This is equivalent to running the docker run -d base /bin/sh -c "while true; do echo hello world; sleep 1; done" command to launch a Docker container managed by the local init system.
run includes a number of optional parameters:
docker::run { 'helloworld':
image => 'base',
detach => true,
service_prefix => 'docker-',
command => '/bin/sh -c "while true; do echo hello world; sleep 1; done"',
ports => ['4444', '4555'],
expose => ['4666', '4777'],
links => ['mysql:db'],
net => ['my-user-def-net','my-user-def-net-2'],
disable_network => false,
volumes => ['/var/lib/couchdb', '/var/log'],
volumes_from => '6446ea52fbc9',
memory_limit => '10m', # (format: '<number><unit>', where unit = b, k, m or g)
cpuset => ['0', '3'],
username => 'example',
hostname => 'example.com',
env => ['FOO=BAR', 'FOO2=BAR2'],
env_file => ['/etc/foo', '/etc/bar'],
labels => ['com.example.foo="true"', 'com.example.bar="false"'],
dns => ['8.8.8.8', '8.8.4.4'],
restart_service => true,
privileged => false,
pull_on_start => false,
before_stop => 'echo "So Long, and Thanks for All the Fish"',
before_start => 'echo "Run this on the host before starting the Docker container"',
after_stop => 'echo "container has stopped"',
after_start => 'echo "container has started"',
after => [ 'container_b', 'mysql' ],
depends => [ 'container_a', 'postgres' ],
stop_wait_time => 10,
read_only => false,
extra_parameters => [ '--restart=always' ],
}
You can specify the ports, expose, env, dns, and volumes values with a single string or an array.
To pull the image before it starts, specify the pull_on_start parameter.
Use the detach param to run a container without the -a flag. This is only required on systems without systemd. This default is set in the params.pp based on the OS. Only override if you understand the consequences and have a specific use case.
To execute a command before the container starts or stops, specify the before_start or before_stop parameters, respectively. Similarly, you can set the after_start or after_stop parameters to run a command after the container starts or stops.
Adding the container name to the after parameter to specify which containers start first affects the generation of the init.d/systemd script.
Add container dependencies to the depends parameter. The container starts before this container and stops before the dependent container. This affects the generation of the init.d/systemd script. Use the depend_services parameter to specify dependencies for general services, which are not Docker related, that start before this container.
The extra_parameters parameter, which contains an array of command line arguments to pass to the docker run command, is useful for adding additional or experimental options that the docker module currently does not support.
By default, automatic restarting of the service on failure is enabled by the service file for systemd based systems.
It's recommended that an image tag is used at all times with the docker::run define type. If not, the latest image is used whether it's in a remote registry or installed on the server already by the docker::image define type.
NOTE: As of v3.0.0, if the latest tag is used the image will be the latest at the time the of the initial puppet run. Any subsequent puppet runs will always reference the latest local image. Therefore, it's recommended that an alternative tag be used, or the image be removed before pulling latest again.
To use an image tag, add the following code to the manifest file:
docker::run { 'helloworld':
image => 'ubuntu:precise',
command => '/bin/sh -c "while true; do echo hello world; sleep 1; done"',
}
By default, when the service stops or starts, the generated init scripts remove the container, but not the associated volumes. To change this behaviour, add the following code to the manifest file:
docker::run { 'helloworld':
remove_container_on_start => true,
remove_volume_on_start => false,
remove_container_on_stop => true,
remove_volume_on_stop => false,
}
If using Hiera, you can configure the docker::run_instance class:
---
classes:
- docker::run_instance
docker::run_instance::instance:
helloworld:
image: 'ubuntu:precise'
command: '/bin/sh -c "while true; do echo hello world; sleep 1; done"'
To remove a running container, add the following code to the manifest file. This also removes the systemd service file associated with the container.
docker::run { 'helloworld':
ensure => absent,
}
To enable the restart of an unhealthy container, add the following code to the manifest file. To set the health check interval time, set the optional health_check_interval parameter. The default health check interval is 30 seconds.
docker::run { 'helloworld':
image => 'base',
command => 'command',
health_check_cmd => '<command_to_execute_to_check_your_containers_health>',
restart_on_unhealthy => true,
health_check_interval => '<time between running docker healthcheck>',
To run command on Windows 2016 requires the restart parameter to be set:
docker::run { 'helloworld':
image => 'microsoft/nanoserver',
command => 'ping 127.0.0.1 -t',
restart => 'always'
Networks
Docker 1.9.x supports networks. To expose the docker_network type that is used to manage networks, add the following code to the manifest file:
docker_network { 'my-net':
ensure => present,
driver => 'overlay',
subnet => '192.168.1.0/24',
gateway => '192.168.1.1',
ip_range => '192.168.1.4/32',
}
The name value and the ensure parameter are required. If you do not include the driver value, the default bridge is used. The Docker daemon must be configured for some networks, and configuring the cluster store for the overlay network would be an example.
To configure the cluster store, update the docker class in the manifest file:
extra_parameters => '--cluster-store=<backend>://172.17.8.101:<port> --cluster-advertise=<interface>:2376'
If using Hiera, configure the docker::networks class in the manifest file:
---
classes:
- docker::networks
docker::networks::networks:
local-docker:
ensure: 'present'
subnet: '192.168.1.0/24'
gateway: '192.168.1.1'
A defined network can be used on a docker::run resource with the net parameter.
Windows
On Windows, only one NAT network is supported. To support multiple networks, Windows Server 2016 with KB4015217 is required. See Windows Container Network Drivers and Windows Container Networking.
The Docker daemon will create a default NAT network on the first start unless specified otherwise. To disable the network creation, use the parameter bridge => 'none' when installing docker.
Volumes
Docker 1.9.x added support for volumes. These are NOT to be confused with the legacy volumes, now known as bind mounts. To expose the docker_volume type, which is used to manage volumes, add the following code to the manifest file:
docker_volume { 'my-volume':
ensure => present,
}
You can pass additional mount options to the local driver. For mounting an NFS export, use:
docker_volume { 'nfs-volume':
ensure => present,
driver => 'local',
options => ['type=nfs','o=addr=%{custom_manager},rw','device=:/srv/blueocean']
}
The name value and the ensure parameter are required. If you do not include the driver value, the default local is used.
If using Hiera, configure the docker::volumes class in the manifest file:
---
classes:
- docker::volumes
docker::volumes::volumes:
blueocean:
ensure: present
driver: local
options:
- ['type=nfs','o=addr=%{custom_manager},rw','device=:/srv/blueocean']
Available parameters for options depend on the used volume driver. For details, see
Using volumes from the Docker manual.
Some of the key advantages for using volumes over bind mounts are:
- Easier to back up or migrate rather than
bind mounts(legacy volumes). - Managed with Docker CLI or API (Puppet type uses the CLI commands).
- Works on Windows and Linux.
- Easily shared between containers.
- Allows for store volumes on remote hosts or cloud providers.
- Encrypt contents of volumes.
- Add other functionality
- New volume's contents can be pre-populated by a container.
When using the volumes array with docker::run, the command on the backend will know if it needs to use bind mounts or volumes based on the data passed to the -v option.
Running docker::run with native volumes:
docker::run { 'helloworld':
image => 'ubuntu:precise',
command => '/bin/sh -c "while true; do echo hello world; sleep 1; done"',
volumes => ['my-volume:/var/log'],
}
Compose
Docker Compose describes a set of containers in YAML format and runs a command to build and run those containers. Included in the docker module is the docker_compose type. This enables Puppet to run Compose and remediate any issues to ensure reality matches the model in your Compose file.
Before you use the docker_compose type, you must install the Docker Compose utility.
To install Docker Compose, add the following code to the manifest file:
class {'docker::compose':
ensure => present,
version => '1.9.0',
}
Set the version parameter to any version you need to install.
This is an example of a Compose file:
compose_test:
image: ubuntu:14.04
command: /bin/sh -c "while true; do echo hello world; sleep 1; done"
Specify the file resource to add a Compose file to the machine you have Puppet running on. To define a docker_compose resource pointing to the Compose file, add the following code to the manifest file:
docker_compose { 'test':
compose_files => ['/tmp/docker-compose.yml'],
ensure => present,
}
Puppet automatically runs Compose because the relevant Compose services aren't running. If required, include additional options such as enabling experimental features and scaling rules.
Additionally, the TMPDIR environment variable can optionally be set when docker_compose runs if you want Puppet to manage the environment variable within the scope of the resource. This is effective when noexec is set on the default /tmp dir, however you must ensure that the target directory exists as the resource will not create it.
In the example below, Puppet runs Compose when the number of containers specified for a service doesn't match the scale values. The optional tmpdir parameter is also specified.
docker_compose { 'test':
compose_files => ['/tmp/docker-compose.yml'],
ensure => present,
scale => {
'compose_test' => 2,
},
tmpdir => '/usr/local/share/tmp_docker',
options => ['--x-networking']
}
Give options to the docker-compose up command, such as --remove-orphans, by using the up_args option.
To supply multiple overide compose files add the following to the manifest file:
docker_compose {'test':
compose_files => ['server-docker-compose.yml', 'override-compose.yml'],
}
Please note you should supply your server docker-compose file as the first element in the array. As per docker, multi compose file support compose files are merged in the order they are specified in the array.
If you are using a v3.2 compose file or above on a Docker Swarm cluster, use the docker::stack class. Include the file resource before you run the stack command.
NOTE: this define will be deprecated in a future release in favor of the docker stack type
To deploy the stack, add the following code to the manifest file:
docker::stack { 'yourapp':
ensure => present,
stack_name => 'yourapp',
compose_files => ['/tmp/docker-compose.yaml'],
require => [Class['docker'], File['/tmp/docker-compose.yaml']],
}
To remove the stack, set ensure => absent.
If you are using a v3.2 compose file or above on a Docker Swarm cluster, include the docker::stack class. Similar to using older versions of Docker, compose the file resource before running the stack command.
To deploy the stack, add the following code to the manifest file.
docker::stack { 'yourapp':
ensure => present,
stack_name => 'yourapp',
compose_files => ['/tmp/docker-compose.yaml'],
with_registry_auth => true,
require => [Class['docker'], File['/tmp/docker-compose.yaml']],
}
To use the equivalent type and provider, use the following in your manifest file. For more information on specific parameters see the docker_stack type documentation.
docker_stack { 'test':
compose_files => ['/tmp/docker-compose.yml'],
ensure => present,
up_args => '--with-registry-auth',
}
To remove the stack, set ensure => absent.
Machine
You can use Docker Machine to install Docker Engine on virtual hosts and manage the hosts with docker-machine commands. You can also use Machine to create Docker hosts on your local Mac or Windows box, on your company network, in your data center, or on cloud providers like Azure, AWS, or Digital Ocean.
For more information on machines, see the Docker Machines documentation.
This module only installs the Docker Machine utility.
To install Docker Machine, add the following code to the manifest file:
class {'docker::machine':
ensure => present,
version => '1.16.1',
}
Set the version parameter to any version you need to install.
Swarm mode
To natively manage a cluster of Docker Engines known as a swarm, Docker Engine 1.12 includes a swarm mode.
To cluster your Docker engines, use one of the following Puppet resources:
Windows
To configure swarm, Windows Server 2016 requires KB4015217 and the following firewall ports to be open on all nodes:
- TCP port 2377 for cluster management communications
- TCP and UDP port 7946 for communication among nodes
- UDP port 4789 for overlay network traffic
Swarm manager
To configure the swarm manager, add the following code to the manifest file:
docker::swarm {'cluster_manager':
init => true,
advertise_addr => '192.168.1.1',
listen_addr => '192.168.1.1',
}
For a multihomed server and to enable cluster communications between the node, include the advertise_addr and listen_addr parameters.
Swarm worker
To configure the swarm worker, add the following code to the manifest file:
docker::swarm {'cluster_worker':
join => true,
advertise_addr => '192.168.1.2',
listen_addr => '192.168.1.2',
manager_ip => '192.168.1.1',
token => 'your_join_token'
}
To configure a worker node or a second manager, include the swarm manager IP address in the manager_ip parameter. To define the role of the node in the cluster, provide the token parameter. When creating an additional swarm manager and a worker node, separate tokens are required. These tokens (i.e. docker_worker_join_token and docker_manager_join_token) can be retrieved from Facter.
To remove a node from a cluster, add the following code to the manifest file:
docker::swarm {'cluster_worker':
ensure => absent
}
Tasks
The docker module has an example task that allows a user to initialize, join and leave a swarm.
bolt task run docker::swarm_init listen_addr=172.17.10.101 adverstise_addr=172.17.10.101 ---nodes swarm-master --user <user> --password <password> --modulepath <module_path>
docker swarm init --advertise-addr=172.17.10.101 --listen-addr=172.17.10.101
Swarm initialized: current node (w8syk0g286vd7d9kwzt7jl44z) is now a manager.
To add a worker to this swarm, run the following command:
docker swarm join --token SWMTKN-1-317gw63odq6w1foaw0xkibzqy34lga55aa5nbjlqekcrhg8utl-08vrg0913zken8h9vfo4t6k0t 172.17.10.101:2377
To add a manager to this swarm, run docker swarm join-token manager and follow the instructions.
Ran on 1 node in 4.04 seconds
bolt task run docker::swarm_token node_role=worker ---nodes swarm-master --user <user> --password <password> --modulepath <module_path>
SWMTKN-1-317gw63odq6w1foaw0xkibzqy34lga55aa5nbjlqekcrhg8utl-08vrg0913zken8h9vfo4t6k0t
Ran on 1 node in 4.02 seconds
bolt task run docker::swarm_join listen_addr=172.17.10.102 adverstise_addr=172.17.10.102 token=<swarm_token> manager_ip=172.17.10.101:2377 --nodes swarm-02 --user root --password puppet --modulepath /tmp/modules
This node joined a swarm as a worker.
Ran on 1 node in 4.68 seconds
bolt task run docker::swarm_leave --nodes swarm-02 --user root --password puppet --modulepath --modulepath <module_path>
Node left the swarm.
Ran on 1 node in 6.16 seconds
Docker services
Docker services create distributed applications across multiple swarm nodes. Each Docker service replicates a set of containers across the swarm.
To create a Docker service, add the following code to the manifest file:
docker::services {'redis':
create => true,
service_name => 'redis',
image => 'redis:latest',
publish => '6379:639',
replicas => '5',
mounts => ['type=bind,source=/etc/my-redis.conf,target=/etc/redis/redis.conf,readonly'],
extra_params => ['--update-delay 1m', '--restart-window 30s'],
command => ['redis-server', '--appendonly', 'yes'],
}
To base the service off an image, include the image parameter and set the publish parameter to expose the service port (use an array to specify multiple published ports). To set the number of containers running in the service, include the replicas parameter. To attach one or multiple filesystems to the service, use the mounts parameter. For information regarding the extra_params parameter, see docker service create --help. The command parameter can either be specified as an array or a string.
To update the service, add the following code to the manifest file:
docker::services {'redis_update':
create => false,
update => true,
service_name => 'redis',
replicas => '3',
}
To update a service without creating a new one, include the the update => true and create => false parameters.
To scale a service, add the following code to the manifest file:
docker::services {'redis_scale':
create => false,
scale => true,
service_name => 'redis',
replicas => '10',
}
To scale the service without creating a new one, provide the scale => true parameter and the create => false parameters. In the example above, the service is scaled to 10.
To remove a service, add the following code to the manifest file:
docker::services {'redis':
create => false,
ensure => 'absent',
service_name => 'redis',
}
To remove the service from a swarm, include the ensure => absent parameter and the service_name parameter.
Private registries
When a server is not specified, images are pushed and pulled from index.docker.io. To qualify your image name, create a private repository without authentication.
To configure authentication for a private registry, add the following code to the manifest file, depending on what version of Docker you are running. If you are using Docker V1.10 or earlier, specify the docker version in the manifest file:
docker::registry { 'example.docker.io:5000':
username => 'user',
password => 'secret',
email => 'user@example.com',
version => '<docker_version>'
}
To pull images from the docker store, use the following as the registry definition with your docker hub credentials.
docker::registry {'https://index.docker.io/v1/':
username => 'username',
password => 'password',
}
If using hiera, configure the docker::registry_auth class:
docker::registry_auth::registries:
'example.docker.io:5000':
username: 'user1'
password: 'secret'
email: 'user1@example.io'
version: '<docker_version>'
If using Docker V1.11 or later, the docker login email flag has been deprecated. See the docker_change_log.
Add the following code to the manifest file:
docker::registry { 'example.docker.io:5000':
username => 'user',
password => 'secret',
}
If using hiera, configure the 'docker::registry_auth' class:
docker::registry_auth::registries:
'example.docker.io:5000':
username: 'user1'
password: 'secret'
To log out of a registry, add the following code to the manifest file:
docker::registry { 'example.docker.io:5000':
ensure => 'absent',
}
To set a preferred registry mirror, add the following code to the manifest file:
class { 'docker':
registry_mirror => 'http://testmirror.io'
}
Exec
Within the context of a running container, the docker module supports arbitrary commands:
docker::exec { 'cron_allow_root':
detach => true,
container => 'mycontainer',
command => '/bin/echo root >> /usr/lib/cron/cron.allow',
onlyif => 'running',
tty => true,
env => ['FOO=BAR', 'FOO2=BAR2'],
unless => 'grep root /usr/lib/cron/cron.allow 2>/dev/null',
refreshonly => true,
}
Plugin
The module supports the installation of Docker plugins:
docker::plugin {'foo/fooplugin:latest':
settings => ['VAR1=test','VAR2=value']
}
To disable an active plugin:
docker::plugin {'foo/fooplugin:latest':
enabled => false,
}
To remove an active plugin:
docker::plugin {'foo/fooplugin:latest'
ensure => 'absent',
force_remove => true,
}
Reference
For information on classes, types, and functions, see the REFERENCE.md.
Limitations
This module supports:
- EL 7 - limited support available, see note below.
- EL 8
- EL 9
- Debian 8.0
- Debian 9.0
- Debian 10
- Debian 11
- Ubuntu 18.04
- Ubuntu 20.04
- Ubuntu 22.04
- Windows Server 2016 (Docker Enterprise Edition only)
- Windows Server 2019 (Docker Enterprise Edition only)
- Windows Server 2022 (Docker Enterprise Edition only)
On RedHat 7 the default docker package installs docker server version 1.13.1. The default docker.service uses the docker-storage-service in this version and creates /etc/sysconfig/docker-storage based on the container-storage-setup configuration and /etc/sysconfig/docker-storage-setup file. As the puppetlabs-docker module manages both the docker-storage and docker-storage-setup files it causes a conflict with the container-storage-setup forcing a docker service restart, therefore a workaround was included in the service manifest that disables the service restart on storage configuration changes for this version of docker on RedHat 7. As a side effect of these changes, storage configuration changes with this docker version on RedHat 7 are not picked up by default by the docker.service.
License
This codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of AGPL, BSD-2, BSD-3, GPL2.0, LGPL, MIT and MPL Licensing.
Development
If you would like to contribute to this module, see the guidelines in CONTRIBUTING.MD.
Acceptance
Acceptance tests for this module leverage puppet_litmus. To run the acceptance tests follow the instructions here.
Reference
Table of Contents
Classes
Public Classes
docker: Module to install an up-to-date version of Docker from package.docker::compose: install Docker Compose using the recommended curl command.docker::imagesdocker::install: Module to install an up-to-date version of Docker from a package repository. Only for Debian, Red Hat and Windowsdocker::machine: install Docker Machine using the recommended curl command.docker::networksdocker::params: Default parameter values for the docker moduledocker::pluginsdocker::registry_authdocker::reposdocker::run_instancedocker::service: manage the docker service daemondocker::swarmsdocker::systemd_reload: For systems that have systemddocker::volumes
Private Classes
docker::config: Configuration for docker
Defined types
docker::exec: A define which executes a command inside a container.docker::image: Module to install an up-to-date version of a Docker image from the registrydocker::plugin: A define that manages a docker plugindocker::registry: Module to configure private docker registries from which to pull Docker imagesdocker::run: A define which manages a running docker container.docker::secretsdocker::services: define that managers a Docker servicesdocker::stack: deploys Docker stacks or compose v3docker::swarm: managers a Docker Swarm Mode clusterdocker::system_user: manage docker group usersdocker::windows_account: Windows account that owns the docker services
Resource types
docker_compose: A type representing a Docker Compose filedocker_network: Type representing a Docker networkdocker_stack: A type representing a Docker Stackdocker_volume: A type representing a Docker volume
Functions
docker::envdocker::escapedocker::sanitised_name: == Function: docker::sanitised_name Function to sanitise container name. === Parameters [name] Name to sanitisedocker_exec_flags: Transforms a hash into a string of docker exec flagsdocker_params_changeddocker_plugin_enable_flags: Transforms a hash into a string of docker plugin remove flagsdocker_plugin_install_flags: Transforms a hash into a string of docker plugin install flagsdocker_plugin_remove_flags: Transforms a hash into a string of docker plugin remove flagsdocker_run_flags: Transforms a hash into a string of docker flagsdocker_secrets_flags: Transforms a hash into a string of docker swarm init flagsdocker_service_flags: Transforms a hash into a string of docker swarm init flagsdocker_stack_flags: Transforms a hash into a string of docker stack flagsdocker_swarm_init_flags: Transforms a hash into a string of docker swarm init flagsdocker_swarm_join_flags: Transforms a hash into a string of docker swarm init flags
Tasks
node_ls: List nodes in the swarmnode_rm: Update a nodenode_update: Update a nodeservice_create: Create a new Docker serviceservice_rm: Remove one replicated serviceservice_scale: Scale one replicated serviceservice_update: Updates an existing service.swarm_init: Initializes a swarmswarm_join: Join a swarmswarm_leave: Leave a swarmswarm_token: Gets the swarm token from the serverswarm_update: Updates an existing service.
Classes
docker
Module to install an up-to-date version of Docker from package.
Parameters
The following parameters are available in the docker class:
versionensureprerequired_packagesdependent_packagestcp_bindtls_enabletls_verifytls_cacerttls_certtls_keyip_forwardiptablesip_masqiccbipmtubridgefixed_cidrdefault_gatewayipv6ipv6_cidrdefault_gateway_ipv6socket_bindlog_levellog_driverlog_optselinux_enableduse_upstream_package_sourcepin_upstream_package_sourceapt_source_pin_levelservice_stateservice_enablemanage_serviceroot_dirdnsdns_searchsocket_groupextra_parametersshell_valuesproxyno_proxystorage_driverdm_basesizedm_fsdm_mkfsargdm_mountoptdm_blocksizedm_loopdatasizedm_loopmetadatasizedm_datadevdm_metadatadevdm_thinpooldevdm_use_deferred_removaldm_use_deferred_deletiondm_blkdiscarddm_override_udev_sync_checkoverlay2_override_kernel_checkmanage_packageservice_namedocker_userscreate_userdocker_groupdaemon_environment_filesrepo_optstorage_devsstorage_vgstorage_root_sizestorage_data_sizestorage_min_data_sizestorage_chunk_sizestorage_growpartstorage_auto_extend_poolstorage_pool_autoextend_thresholdstorage_pool_autoextend_percenttmp_dir_configtmp_dirregistry_mirrornuget_package_provider_versiondocker_msft_provider_versiondocker_ce_start_commanddocker_ce_package_namedocker_ce_cli_package_namedocker_ce_source_locationdocker_ce_key_sourcedocker_ce_key_iddocker_ce_releasedocker_package_locationdocker_package_key_sourcedocker_package_key_check_sourcedocker_package_key_iddocker_package_releasedocker_engine_start_commanddocker_engine_package_namedocker_ce_channeldocker_eedocker_ee_package_namedocker_ee_source_locationdocker_ee_key_sourcedocker_ee_key_iddocker_ee_reposdocker_ee_releasepackage_releaselabelsexecdriverpackage_sourceos_lcstorage_configstorage_config_templatestorage_setup_fileservice_providerservice_configservice_config_templateservice_overrides_templatesocket_overrides_templatesocket_overrideservice_after_overrideservice_hasstatusservice_hasrestartacknowledge_unsupported_oshave_systemd_v230
version
Data type: Optional[String]
The package version to install, used to set the package name.
Default value: $docker::params::version
ensure
Data type: String
Passed to the docker package.
Default value: $docker::params::ensure
prerequired_packages
Data type: Variant[Array[String], Hash]
An array of additional packages that need to be installed to support docker.
Default value: $docker::params::prerequired_packages
dependent_packages
Data type: Array
An array of packages installed by the docker-ce package v 18.09 and later. Used when uninstalling to ensure containers cannot be run on the system.
Default value: $docker::params::dependent_packages
tcp_bind
Data type: Optional[Variant[String,Array[String]]]
The tcp socket to bind to in the format tcp://127.0.0.1:4243
Default value: $docker::params::tcp_bind
tls_enable
Data type: Boolean
Enable TLS.
Default value: $docker::params::tls_enable
tls_verify
Data type: Boolean
Use TLS and verify the remote
Default value: $docker::params::tls_verify
tls_cacert
Data type: Optional[String]
Path to TLS CA certificate
Default value: $docker::params::tls_cacert
tls_cert
Data type: Optional[String]
Path to TLS certificate file
Default value: $docker::params::tls_cert
tls_key
Data type: Optional[String]
Path to TLS key file
Default value: $docker::params::tls_key
ip_forward
Data type: Boolean
Enables IP forwarding on the Docker host.
Default value: $docker::params::ip_forward
iptables
Data type: Boolean
Enable Docker's addition of iptables rules.
Default value: $docker::params::iptables
ip_masq
Data type: Boolean
Enable IP masquerading for bridge's IP range.
Default value: $docker::params::ip_masq
icc
Data type: Optional[Boolean]
Enable or disable Docker's unrestricted inter-container and Docker daemon host communication. (Requires iptables=true to disable)
Default value: $docker::params::icc
bip
Data type: Optional[String]
Specify docker's network bridge IP, in CIDR notation.
Default value: $docker::params::bip
mtu
Data type: Optional[String]
Docker network MTU.
Default value: $docker::params::mtu
bridge
Data type: Optional[String]
Attach containers to a pre-existing network bridge use 'none' to disable container networking
Default value: $docker::params::bridge
fixed_cidr
Data type: Optional[String]
IPv4 subnet for fixed IPs 10.20.0.0/16
Default value: $docker::params::fixed_cidr
default_gateway
Data type: Optional[String]
IPv4 address of the container default gateway; this address must be part of the bridge subnet (which is defined by bridge)
Default value: $docker::params::default_gateway
ipv6
Data type: Optional[Boolean]
Enables ipv6 support for the docker daemon
Default value: $docker::params::ipv6
ipv6_cidr
Data type: Optional[String]
IPv6 subnet for fixed IPs
Default value: $docker::params::ipv6_cidr
default_gateway_ipv6
Data type: Optional[String]
IPv6 address of the container default gateway:
Default value: $docker::params::default_gateway_ipv6
socket_bind
Data type: String
The unix socket to bind to.
Default value: $docker::params::socket_bind
log_level
Data type: Optional[String]
Set the logging level Valid values: debug, info, warn, error, fatal
Default value: $docker::params::log_level
log_driver
Data type: Optional[String]
Set the log driver. Docker default is json-file. Please verify the value by yourself, before setting it. Valid shipped log drivers can be found here: https://docs.docker.com/config/containers/logging/configure/#supported-logging-drivers Since custom log driver plugins are and must be possible, the value can not be verified through code here.
Default value: $docker::params::log_driver
log_opt
Data type: Array
Set the log driver specific options Valid values per log driver: none : undef local : max-size=[0-9+][k|m|g] max-file=[0-9+] json-file: max-size=[0-9+][k|m|g] max-file=[0-9+] syslog : syslog-address=[tcp|udp]://host:port syslog-address=unix://path syslog-facility=daemon|kern|user|mail|auth| syslog|lpr|news|uucp|cron| authpriv|ftp| local0|local1|local2|local3| local4|local5|local6|local7 syslog-tag="some_tag" journald : undef gelf : gelf-address=udp://host:port gelf-tag="some_tag" fluentd : fluentd-address=host:port fluentd-tag={{.ID}} - short container id (12 characters)| {{.FullID}} - full container id {{.Name}} - container name splunk : splunk-token=<splunk_http_event_collector_token> splunk-url=https://your_splunk_instance:8088 awslogs : awslogs-group= awslogs-stream= awslogs-create-group=true|false awslogs-datetime-format= - strftime expression awslogs-multiline-pattern=multiline start pattern using a regular expression tag={{.ID}} - short container id (12 characters)| {{.FullID}} - full container id {{.Name}} - container name
Default value: $docker::params::log_opt
selinux_enabled
Data type: Optional[Boolean]
Enable selinux support. Default is false. SELinux does not presently support the BTRFS storage driver.
Default value: $docker::params::selinux_enabled
use_upstream_package_source
Data type: Optional[Boolean]
Whether or not to use the upstream package source. If you run your own package mirror, you may set this to false.
Default value: $docker::params::use_upstream_package_source
pin_upstream_package_source
Data type: Optional[Boolean]
Pin upstream package source; this option currently only has any effect on apt-based distributions. Set to false to remove pinning on the upstream package repository. See also "apt_source_pin_level".
Default value: $docker::params::pin_upstream_package_source
apt_source_pin_level
Data type: Optional[Integer]
What level to pin our source package repository to; this only is relevent if you're on an apt-based system (Debian, Ubuntu, etc) and $use_upstream_package_source is set to true. Set this to false to disable pinning, and undef to ensure the apt preferences file apt::source uses to define pins is removed.
Default value: $docker::params::apt_source_pin_level
service_state
Data type: String
Whether you want to docker daemon to start up
Default value: $docker::params::service_state
service_enable
Data type: Boolean
Whether you want to docker daemon to start up at boot
Default value: $docker::params::service_enable
manage_service
Data type: Boolean
Specify whether the service should be managed.
Default value: $docker::params::manage_service
root_dir
Data type: Optional[String]
Custom root directory for containers
Default value: $docker::params::root_dir
dns
Data type: Optional[Variant[String,Array]]
Custom dns server address
Default value: $docker::params::dns
dns_search
Data type: Optional[Variant[String,Array]]
Custom dns search domains
Default value: $docker::params::dns_search
socket_group
Data type: Optional[Variant[String,Boolean]]
Group ownership of the unix control socket.
Default value: $docker::params::socket_group
extra_parameters
Data type: Optional[Variant[String,Array]]
Any extra parameters that should be passed to the docker daemon.
Default value: undef
shell_values
Data type: Optional[Variant[String,Array]]
Array of shell values to pass into init script config files
Default value: undef
proxy
Data type: Optional[String]
Will set the http_proxy and https_proxy env variables in /etc/sysconfig/docker (redhat/centos) or /etc/default/docker (debian)
Default value: $docker::params::proxy
no_proxy
Data type: Optional[String]
Will set the no_proxy variable in /etc/sysconfig/docker (redhat/centos) or /etc/default/docker (debian)
Default value: $docker::params::no_proxy
storage_driver
Data type: Optional[String]
Specify a storage driver to use Valid values: aufs, devicemapper, btrfs, overlay, overlay2, vfs, zfs
Default value: $docker::params::storage_driver
dm_basesize
Data type: Optional[String]
The size to use when creating the base device, which limits the size of images and containers.
Default value: $docker::params::dm_basesize
dm_fs
Data type: Optional[String]
The filesystem to use for the base image (xfs or ext4)
Default value: $docker::params::dm_fs
dm_mkfsarg
Data type: Optional[String]
Specifies extra mkfs arguments to be used when creating the base device.
Default value: $docker::params::dm_mkfsarg
dm_mountopt
Data type: Optional[String]
Specifies extra mount options used when mounting the thin devices.
Default value: $docker::params::dm_mountopt
dm_blocksize
Data type: Optional[String]
A custom blocksize to use for the thin pool. Default blocksize is 64K. Warning: DO NOT change this parameter after the lvm devices have been initialized.
Default value: $docker::params::dm_blocksize
dm_loopdatasize
Data type: Optional[String]
Specifies the size to use when creating the loopback file for the "data" device which is used for the thin pool
Default value: $docker::params::dm_loopdatasize
dm_loopmetadatasize
Data type: Optional[String]
Specifies the size to use when creating the loopback file for the "metadata" device which is used for the thin pool
Default value: $docker::params::dm_loopmetadatasize
dm_datadev
Data type: Optional[String]
(deprecated - dm_thinpooldev should be used going forward) A custom blockdevice to use for data for the thin pool.
Default value: $docker::params::dm_datadev
dm_metadatadev
Data type: Optional[String]
(deprecated - dm_thinpooldev should be used going forward) A custom blockdevice to use for metadata for the thin pool.
Default value: $docker::params::dm_metadatadev
dm_thinpooldev
Data type: Optional[String]
Specifies a custom block storage device to use for the thin pool.
Default value: $docker::params::dm_thinpooldev
dm_use_deferred_removal
Data type: Optional[Boolean]
Enables use of deferred device removal if libdm and the kernel driver support the mechanism.
Default value: $docker::params::dm_use_deferred_removal
dm_use_deferred_deletion
Data type: Optional[Boolean]
Enables use of deferred device deletion if libdm and the kernel driver support the mechanism.
Default value: $docker::params::dm_use_deferred_deletion
dm_blkdiscard
Data type: Optional[Boolean]
Enables or disables the use of blkdiscard when removing devicemapper devices.
Default value: $docker::params::dm_blkdiscard
dm_override_udev_sync_check
Data type: Optional[Boolean]
By default, the devicemapper backend attempts to synchronize with the udev device manager for the Linux kernel. This option allows disabling that synchronization, to continue even though the configuration may be buggy.
Default value: $docker::params::dm_override_udev_sync_check
overlay2_override_kernel_check
Data type: Boolean
Overrides the Linux kernel version check allowing using overlay2 with kernel < 4.0.
Default value: $docker::params::overlay2_override_kernel_check
manage_package
Data type: Boolean
Won't install or define the docker package, useful if you want to use your own package
Default value: $docker::params::manage_package
service_name
Data type: Optional[String]
Specify custom service name
Default value: $docker::params::service_name
docker_users
Data type: Array
Specify an array of users to add to the docker group
Default value: []
create_user
Data type: Boolean
If true the list of docker_users will be created as well as added to the docker group
Default value: true
docker_group
Data type: String
Specify a string for the docker group
Default value: $docker::params::docker_group
daemon_environment_files
Data type: Array
Specify additional environment files to add to the service-overrides.conf
Default value: []
repo_opt
Data type: Optional[Variant[String,Hash]]
Specify a string to pass as repository options (RedHat only)
Default value: $docker::params::repo_opt
storage_devs
Data type: Optional[String]
A quoted, space-separated list of devices to be used.
Default value: $docker::params::storage_devs
storage_vg
Data type: Optional[String]
The volume group to use for docker storage.
Default value: $docker::params::storage_vg
storage_root_size
Data type: Optional[String]
The size to which the root filesystem should be grown.
Default value: $docker::params::storage_root_size
storage_data_size
Data type: Optional[String]
The desired size for the docker data LV
Default value: $docker::params::storage_data_size
storage_min_data_size
Data type: Optional[String]
The minimum size of data volume otherwise pool creation fails
Default value: $docker::params::storage_min_data_size
storage_chunk_size
Data type: Optional[String]
Controls the chunk size/block size of thin pool.
Default value: $docker::params::storage_chunk_size
storage_growpart
Data type: Optional[Boolean]
Enable resizing partition table backing root volume group.
Default value: $docker::params::storage_growpart
storage_auto_extend_pool
Data type: Optional[String]
Enable/disable automatic pool extension using lvm
Default value: $docker::params::storage_auto_extend_pool
storage_pool_autoextend_threshold
Data type: Optional[String]
Auto pool extension threshold (in % of pool size)
Default value: $docker::params::storage_pool_autoextend_threshold
storage_pool_autoextend_percent
Data type: Optional[String]
Extend the pool by specified percentage when threshold is hit.
Default value: $docker::params::storage_pool_autoextend_percent
tmp_dir_config
Data type: Optional[Boolean]
Whether to set the TMPDIR value in the systemd config file Default: true (set the value); false will comment out the line. Note: false is backwards compatible prior to PR #58
Default value: $docker::params::tmp_dir_config
tmp_dir
Data type: Optional[String]
Sets the tmp dir for Docker (path)
Default value: $docker::params::tmp_dir
registry_mirror
Data type: Optional[Variant[String,Array]]
Sets the prefered container registry mirror.
Default value: $docker::params::registry_mirror
nuget_package_provider_version
Data type: Optional[String]
The version of the NuGet Package provider
Default value: $docker::params::nuget_package_provider_version
docker_msft_provider_version
Data type: Optional[String]
The version of the Microsoft Docker Provider Module
Default value: $docker::params::docker_msft_provider_version
docker_ce_start_command
Data type: String
Default value: $docker::params::docker_ce_start_command
docker_ce_package_name
Data type: Optional[String]
Default value: $docker::params::docker_ce_package_name
docker_ce_cli_package_name
Data type: String[1]
Default value: $docker::params::docker_ce_cli_package_name
docker_ce_source_location
Data type: Optional[String]
Default value: $docker::params::package_ce_source_location
docker_ce_key_source
Data type: Optional[String]
Default value: $docker::params::package_ce_key_source
docker_ce_key_id
Data type: Optional[String]
Default value: $docker::params::package_ce_key_id
docker_ce_release
Data type: Optional[String]
Default value: $docker::params::package_ce_release
docker_package_location
Data type: Optional[String]
Default value: $docker::params::package_source_location
docker_package_key_source
Data type: Optional[String]
Default value: $docker::params::package_key_source
docker_package_key_check_source
Data type: Optional[Boolean]
Default value: $docker::params::package_key_check_source
docker_package_key_id
Data type: Optional[String]
Default value: $docker::params::package_key_id
docker_package_release
Data type: Optional[String]
Default value: $docker::params::package_release
docker_engine_start_command
Data type: String
Default value: $docker::params::docker_engine_start_command
docker_engine_package_name
Data type: String
Default value: $docker::params::docker_engine_package_name
docker_ce_channel
Data type: String
Default value: $docker::params::docker_ce_channel
docker_ee
Data type: Optional[Boolean]
Default value: $docker::params::docker_ee
docker_ee_package_name
Data type: Optional[String]
Default value: $docker::params::package_ee_package_name
docker_ee_source_location
Data type: Optional[String]
Default value: $docker::params::package_ee_source_location
docker_ee_key_source
Data type: Optional[String]
Default value: $docker::params::package_ee_key_source
docker_ee_key_id
Data type: Optional[String]
Default value: $docker::params::package_ee_key_id
docker_ee_repos
Data type: Optional[String]
Default value: $docker::params::package_ee_repos
docker_ee_release
Data type: Optional[String]
Default value: $docker::params::package_ee_release
package_release
Data type: Optional[String]
Default value: $docker::params::package_release
labels
Data type: Array
Default value: $docker::params::labels
execdriver
Data type: Optional[String]
Default value: $docker::params::execdriver
package_source
Data type: Optional[String]
Default value: $docker::params::package_source
os_lc
Data type: Optional[String]
Default value: $docker::params::os_lc
storage_config
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::params::storage_config
storage_config_template
Data type: Optional[String]
Default value: $docker::params::storage_config_template
storage_setup_file
Data type: Optional[String]
Default value: $docker::params::storage_setup_file
service_provider
Data type: Optional[String]
Default value: $docker::params::service_provider
service_config
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::params::service_config
service_config_template
Data type: Optional[String]
Default value: $docker::params::service_config_template
service_overrides_template
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::params::service_overrides_template
socket_overrides_template
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::params::socket_overrides_template
socket_override
Data type: Optional[Boolean]
Default value: $docker::params::socket_override
service_after_override
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::params::service_after_override
service_hasstatus
Data type: Optional[Boolean]
Default value: $docker::params::service_hasstatus
service_hasrestart
Data type: Optional[Boolean]
Default value: $docker::params::service_hasrestart
acknowledge_unsupported_os
Data type: Boolean
Default value: false
have_systemd_v230
Data type: Boolean
Default value: $docker::params::have_systemd_v230
docker::compose
install Docker Compose using the recommended curl command.
Parameters
The following parameters are available in the docker::compose class:
ensure
Data type: Enum[present,absent]
Whether to install or remove Docker Compose Valid values are absent present
Default value: present
version
Data type: Optional[String]
The version of Docker Compose to install.
Default value: undef
docker::images
The docker::images class.
Parameters
The following parameters are available in the docker::images class:
images
Data type: Hash
docker::install
Module to install an up-to-date version of Docker from a package repository. Only for Debian, Red Hat and Windows
Parameters
The following parameters are available in the docker::install class:
versionnuget_package_provider_versiondocker_msft_provider_versiondocker_ee_package_namedocker_download_urldependent_packages
version
Data type: Optional[String]
The package version to install, used to set the package name.
Default value: $docker::version
nuget_package_provider_version
Data type: Optional[String]
The version of the NuGet Package provider
Default value: $docker::nuget_package_provider_version
docker_msft_provider_version
Data type: Optional[String]
The version of the Microsoft Docker Provider Module
Default value: $docker::docker_msft_provider_version
docker_ee_package_name
Data type: Optional[String]
The name of the Docker Enterprise Edition package
Default value: $docker::docker_ee_package_name
docker_download_url
Data type: Optional[String]
Default value: $docker::package_location
dependent_packages
Data type: Array
Default value: $docker::dependent_packages
docker::machine
install Docker Machine using the recommended curl command.
Parameters
The following parameters are available in the docker::machine class:
ensure
Data type: Enum[present,absent]
Whether to install or remove Docker Machine Valid values are absent present
Default value: 'present'
version
Data type: Optional[String]
The version of Docker Machine to install.
Default value: $docker::params::machine_version
install_path
Data type: Optional[String]
The path where to install Docker Machine.
Default value: $docker::params::machine_install_path
proxy
Data type: Optional[Pattern['^((http[s]?)?:\/\/)?([^:^@]+:[^:^@]+@|)([\da-z\.-]+)\.([\da-z\.]{2,6})(:[\d])?([\/\w \.-]*)*\/?$']]
Proxy to use for downloading Docker Machine.
Default value: undef
url
Data type: Optional[Variant[Stdlib::HTTPUrl, Stdlib::HTTPSUrl]]
The URL from which the docker machine binary should be fetched
Default value: undef
curl_ensure
Data type: Optional[Boolean]
Whether or not the curl package is ensured by this module.
Default value: $docker::params::curl_ensure
docker::networks
The docker::networks class.
Parameters
The following parameters are available in the docker::networks class:
networks
Data type: Optional[Hash[String, Hash]]
Default value: undef
docker::params
Default parameter values for the docker module
docker::plugins
The docker::plugins class.
Parameters
The following parameters are available in the docker::plugins class:
plugins
Data type: Hash
docker::registry_auth
The docker::registry_auth class.
Parameters
The following parameters are available in the docker::registry_auth class:
registries
Data type: Hash
docker::repos
The docker::repos class.
Parameters
The following parameters are available in the docker::repos class:
location
Data type: Optional[String]
Default value: $docker::package_location
key_source
Data type: Optional[String]
Default value: $docker::package_key_source
key_check_source
Data type: Optional[Boolean]
Default value: $docker::package_key_check_source
architecture
Data type: String
Default value: $facts['os']['architecture']
docker::run_instance
The docker::run_instance class.
Parameters
The following parameters are available in the docker::run_instance class:
instance
Data type: Hash
docker::service
manage the docker service daemon
Parameters
The following parameters are available in the docker::service class:
tcp_bindip_forwardiptablesip_masqsocket_bindsocket_grouproot_dirextra_parametersshell_valuesmanage_servicedocker_commanddocker_start_commandservice_nameiccbridgefixed_cidrdefault_gatewayipv6ipv6_cidrdefault_gateway_ipv6log_levellog_driverlog_optselinux_enabledlabelsdnsdns_searchservice_stateservice_enableproxyno_proxyexecdriverbipmtustorage_driverdm_basesizedm_fsdm_mkfsargdm_mountoptdm_blocksizedm_loopdatasizedm_loopmetadatasizedm_datadevdm_metadatadevtmp_dir_configtmp_dirdm_thinpooldevdm_use_deferred_removaldm_use_deferred_deletiondm_blkdiscarddm_override_udev_sync_checkoverlay2_override_kernel_checkstorage_devsstorage_vgstorage_root_sizestorage_data_sizestorage_min_data_sizestorage_chunk_sizestorage_growpartstorage_auto_extend_poolstorage_pool_autoextend_thresholdstorage_pool_autoextend_percentstorage_configstorage_config_templatestorage_setup_fileservice_providerservice_configservice_config_templateservice_overrides_templatesocket_overrides_templatesocket_overrideservice_after_overrideservice_hasstatusservice_hasrestartdaemon_environment_filestls_enabletls_verifytls_cacerttls_certtls_keyregistry_mirrorroot_dir_flag
tcp_bind
Data type: Optional[Variant[String,Array[String]]]
Which tcp port, if any, to bind the docker service to.
Default value: $docker::tcp_bind
ip_forward
Data type: Boolean
This flag interacts with the IP forwarding setting on your host system's kernel
Default value: $docker::ip_forward
iptables
Data type: Boolean
Enable Docker's addition of iptables rules
Default value: $docker::iptables
ip_masq
Data type: Boolean
Enable IP masquerading for bridge's IP range.
Default value: $docker::ip_masq
socket_bind
Data type: String
Which local unix socket to bind the docker service to.
Default value: $docker::socket_bind
socket_group
Data type: Optional[Variant[String,Boolean]]
Which local unix socket to bind the docker service to.
Default value: $docker::socket_group
root_dir
Data type: Optional[String]
Specify a non-standard root directory for docker.
Default value: $docker::root_dir
extra_parameters
Data type: Optional[Variant[String,Array]]
Plain additional parameters to pass to the docker daemon
Default value: $docker::extra_parameters
shell_values
Data type: Optional[Variant[String,Array]]
Array of shell values to pass into init script config files
Default value: $docker::shell_values
manage_service
Data type: Boolean
Specify whether the service should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
Default value: $docker::manage_service
docker_command
Data type: String
Default value: $docker::docker_command
docker_start_command
Data type: String
Default value: $docker::docker_start_command
service_name
Data type: Optional[String]
Default value: $docker::service_name
icc
Data type: Optional[Boolean]
Default value: $docker::icc
bridge
Data type: Optional[String]
Default value: $docker::bridge
fixed_cidr
Data type: Optional[String]
Default value: $docker::fixed_cidr
default_gateway
Data type: Optional[String]
Default value: $docker::default_gateway
ipv6
Data type: Optional[Boolean]
Default value: $docker::ipv6
ipv6_cidr
Data type: Optional[String]
Default value: $docker::ipv6_cidr
default_gateway_ipv6
Data type: Optional[String]
Default value: $docker::default_gateway_ipv6
log_level
Data type: Optional[String]
Default value: $docker::log_level
log_driver
Data type: Optional[String]
Default value: $docker::log_driver
log_opt
Data type: Array
Default value: $docker::log_opt
selinux_enabled
Data type: Optional[Boolean]
Default value: $docker::selinux_enabled
labels
Data type: Array
Default value: $docker::labels
dns
Data type: Optional[Variant[String,Array]]
Default value: $docker::dns
dns_search
Data type: Optional[Variant[String,Array]]
Default value: $docker::dns_search
service_state
Data type: String
Default value: $docker::service_state
service_enable
Data type: Boolean
Default value: $docker::service_enable
proxy
Data type: Optional[String]
Default value: $docker::proxy
no_proxy
Data type: Optional[String]
Default value: $docker::no_proxy
execdriver
Data type: Optional[String]
Default value: $docker::execdriver
bip
Data type: Optional[String]
Default value: $docker::bip
mtu
Data type: Optional[String]
Default value: $docker::mtu
storage_driver
Data type: Optional[String]
Default value: $docker::storage_driver
dm_basesize
Data type: Optional[String]
Default value: $docker::dm_basesize
dm_fs
Data type: Optional[String]
Default value: $docker::dm_fs
dm_mkfsarg
Data type: Optional[String]
Default value: $docker::dm_mkfsarg
dm_mountopt
Data type: Optional[String]
Default value: $docker::dm_mountopt
dm_blocksize
Data type: Optional[String]
Default value: $docker::dm_blocksize
dm_loopdatasize
Data type: Optional[String]
Default value: $docker::dm_loopdatasize
dm_loopmetadatasize
Data type: Optional[String]
Default value: $docker::dm_loopmetadatasize
dm_datadev
Data type: Optional[String]
Default value: $docker::dm_datadev
dm_metadatadev
Data type: Optional[String]
Default value: $docker::dm_metadatadev
tmp_dir_config
Data type: Optional[Boolean]
Default value: $docker::tmp_dir_config
tmp_dir
Data type: Optional[String]
Default value: $docker::tmp_dir
dm_thinpooldev
Data type: Optional[String]
Default value: $docker::dm_thinpooldev
dm_use_deferred_removal
Data type: Optional[Boolean]
Default value: $docker::dm_use_deferred_removal
dm_use_deferred_deletion
Data type: Optional[Boolean]
Default value: $docker::dm_use_deferred_deletion
dm_blkdiscard
Data type: Optional[Boolean]
Default value: $docker::dm_blkdiscard
dm_override_udev_sync_check
Data type: Optional[Boolean]
Default value: $docker::dm_override_udev_sync_check
overlay2_override_kernel_check
Data type: Boolean
Default value: $docker::overlay2_override_kernel_check
storage_devs
Data type: Optional[String]
Default value: $docker::storage_devs
storage_vg
Data type: Optional[String]
Default value: $docker::storage_vg
storage_root_size
Data type: Optional[String]
Default value: $docker::storage_root_size
storage_data_size
Data type: Optional[String]
Default value: $docker::storage_data_size
storage_min_data_size
Data type: Optional[String]
Default value: $docker::storage_min_data_size
storage_chunk_size
Data type: Optional[String]
Default value: $docker::storage_chunk_size
storage_growpart
Data type: Optional[Boolean]
Default value: $docker::storage_growpart
storage_auto_extend_pool
Data type: Optional[String]
Default value: $docker::storage_auto_extend_pool
storage_pool_autoextend_threshold
Data type: Optional[String]
Default value: $docker::storage_pool_autoextend_threshold
storage_pool_autoextend_percent
Data type: Optional[String]
Default value: $docker::storage_pool_autoextend_percent
storage_config
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::storage_config
storage_config_template
Data type: Optional[String]
Default value: $docker::storage_config_template
storage_setup_file
Data type: Optional[String]
Default value: $docker::storage_setup_file
service_provider
Data type: Optional[String]
Default value: $docker::service_provider
service_config
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::service_config
service_config_template
Data type: Optional[String]
Default value: $docker::service_config_template
service_overrides_template
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::service_overrides_template
socket_overrides_template
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::socket_overrides_template
socket_override
Data type: Optional[Boolean]
Default value: $docker::socket_override
service_after_override
Data type: Optional[Variant[String,Boolean]]
Default value: $docker::service_after_override
service_hasstatus
Data type: Optional[Boolean]
Default value: $docker::service_hasstatus
service_hasrestart
Data type: Optional[Boolean]
Default value: $docker::service_hasrestart
daemon_environment_files
Data type: Array
Default value: $docker::daemon_environment_files
tls_enable
Data type: Boolean
Default value: $docker::tls_enable
tls_verify
Data type: Boolean
Default value: $docker::tls_verify
tls_cacert
Data type: Optional[String]
Default value: $docker::tls_cacert
tls_cert
Data type: Optional[String]
Default value: $docker::tls_cert
tls_key
Data type: Optional[String]
Default value: $docker::tls_key
registry_mirror
Data type: Optional[Variant[String,Array]]
Default value: $docker::registry_mirror
root_dir_flag
Data type: String
Default value: $docker::root_dir_flag
docker::swarms
The docker::swarms class.
Parameters
The following parameters are available in the docker::swarms class:
swarms
Data type: Hash
docker::systemd_reload
For systems that have systemd
docker::volumes
The docker::volumes class.
Parameters
The following parameters are available in the docker::volumes class:
volumes
Data type: Hash
Defined types
docker::exec
A define which executes a command inside a container.
Parameters
The following parameters are available in the docker::exec defined type:
detach
Data type: Boolean
Default value: false
interactive
Data type: Boolean
Default value: false
env
Data type: Array
Default value: []
tty
Data type: Boolean
Default value: false
container
Data type: Optional[String]
Default value: undef
command
Data type: Optional[String]
Default value: undef
unless
Data type: Optional[String]
Default value: undef
sanitise_name
Data type: Boolean
Default value: true
refreshonly
Data type: Boolean
Default value: false
onlyif
Data type: Optional[String]
Default value: undef
docker::image
Module to install an up-to-date version of a Docker image from the registry
Parameters
The following parameters are available in the docker::image defined type:
ensure
Data type: Enum[present,absent,latest]
Whether you want the image present or absent.
Default value: 'present'
image
Data type: Optional[Pattern[/^[\S]*$/]]
If you want the name of the image to be different from the name of the puppet resource you can pass a value here.
Default value: $title
image_tag
Data type: Optional[String]
If you want a specific tag of the image to be installed
Default value: undef
image_digest
Data type: Optional[String]
If you want a specific content digest of the image to be installed
Default value: undef
docker_file
Data type: Optional[String]
If you want to add a docker image from specific docker file
Default value: undef
docker_tar
Data type: Optional[String]
If you want to load a docker image from specific docker tar
Default value: undef
force
Data type: Boolean
Default value: false
docker_dir
Data type: Optional[String]
Default value: undef
docker::plugin
A define that manages a docker plugin
Parameters
The following parameters are available in the docker::plugin defined type:
plugin_nameenabledtimeoutplugin_aliasdisable_on_installdisable_content_trustgrant_all_permissionsforce_removesettingsensure
plugin_name
Data type: String
This ensures whether the plugin is installed or not. Note that the default behaviour of docker plugin requires a plugin be disabled before it can be removed
Default value: $title
enabled
Data type: Boolean
A setting to enable or disable an installed plugin.
Default value: true
timeout
Data type: Optional[String]
The number of seconds to wait when enabling a plugin
Default value: undef
plugin_alias
Data type: Optional[String]
An alternative name to use for an installed plugin
Default value: undef
disable_on_install
Data type: Boolean
Alters the default behaviour of enabling a plugin upon install
Default value: false
disable_content_trust
Data type: Boolean
Skip image verification
Default value: true
grant_all_permissions
Data type: Boolean
Grant all permissions necessary to run the plugin
Default value: true
force_remove
Data type: Boolean
Force the removal of an active plugin
Default value: true
settings
Data type: Array
Any additional settings to pass to the plugin during install
Default value: []
ensure
Data type: Enum[present,absent]
Default value: 'present'
docker::registry
Module to configure private docker registries from which to pull Docker images
Parameters
The following parameters are available in the docker::registry defined type:
server
Data type: Optional[String]
The hostname and port of the private Docker registry. Ex: dockerreg:5000
Default value: $title
ensure
Data type: Enum[present,absent]
Whether or not you want to login or logout of a repository
Default value: 'present'
username
Data type: Optional[String]
Username for authentication to private Docker registry. auth is not required.
Default value: undef
password
Data type: Optional[String]
Password for authentication to private Docker registry. Leave undef if auth is not required.
Default value: undef
pass_hash
Data type: Optional[String]
The hash to be used for receipt. If left as undef, a hash will be generated
Default value: undef
email
Data type: Optional[String]
Email for registration to private Docker registry. Leave undef if auth is not required.
Default value: undef
local_user
Data type: String
The local user to log in as. Docker will store credentials in this users home directory
Default value: 'root'
local_user_home
Data type: Optional[String]
The local user home directory.
Default value: undef
receipt
Data type: Boolean
Required to be true for idempotency
Default value: true
version
Data type: Optional[String]
Default value: $docker::version
docker::run
Sets a restart policy on the docker run. Note: If set, puppet will NOT setup an init script to manage, instead it will do a raw docker run command using a CID file to track the container ID.
If you want a normal named container with an init script and a restart policy you must use the extra_parameters feature and pass it in like this:
extra_parameters => ['--restart=always']
However, if your system is using sytemd this restart policy will be ineffective because the ExecStop commands will run which will cause docker to stop restarting it. In this case you should use the systemd_restart option to specify the policy you want.
This will allow the docker container to be restarted if it dies, without puppet help.
(optional) Specifies the command to execute to check that the container is healthy using the docker health check functionality. Default: undef
(optional) Specifies the interval that the health check command will execute in seconds. Default: undef
(optional) Checks the health status of Docker container and if it is unhealthy the service will be restarted. The health_check_cmd parameter must be set to true to use this functionality. Default: undef
The docker network to attach to a container. Can be a String or Array (if using multiple networks) Default: bridge
An array of additional command line arguments to pass to the docker run
command. Useful for adding additional new or experimental options that the
module does not yet support.
(optional) If the container is to be managed by a systemd unit file set the Restart option on the unit file. Can be any valid value for this systemd configuration. Most commonly used are on-failure or always. Default: on-failure
(optional) Specify an additional unless for the Docker run command when using restart. Default: undef
(optional) Specifies the command to execute after container is created but before it is started. Default: undef
(optional) If the container is to be managed by a systemd unit file set the RemainAfterExit option on the unit file. Can be any valid value for this systemd configuration. Default: Not included in unit file
(optional) Prepare the service and enable it as usual but do not run it right away. Useful when building VM images using masterless Puppet and then letting the Docker images to be downloaded when a new VM is created. Default: false
Parameters
The following parameters are available in the docker::run defined type:
restartverify_digestservice_prefixrestart_servicerestart_service_on_docker_refreshmanage_servicedocker_servicehealth_check_cmdhealth_check_intervalrestart_on_unhealthynetextra_parameterssystemd_restartcustom_unlessafter_createremain_after_exitprepare_service_onlyimageensurecommandmemory_limitcpusetportslabelsexposevolumeslinksuse_namerunningvolumes_fromusernamehostnameenvenv_filednsdns_searchlxc_confservice_providerdisable_networkprivilegeddetachextra_systemd_parameterspull_on_startafterafter_servicedependsdepend_servicesttysocket_connecthostentriesbefore_startbefore_stopafter_startafter_stopremove_container_on_startremove_container_on_stopremove_volume_on_startremove_volume_on_stopstop_wait_timesyslog_identifiersyslog_facilityread_only
restart
Data type: Optional[String]
Default value: undef
verify_digest
Data type: Optional[String]
(optional) Make sure, that the image has not modified. Compares the digest checksum before starting the docker image. To get the digest of an image, run the following command: docker image inspect <> --format='{{index .RepoDigests 0}}
Default value: undef
service_prefix
Data type: String
(optional) The name to prefix the startup script with and the Puppet service resource title with. Default: 'docker-'
Default value: 'docker-'
restart_service
Data type: Boolean
(optional) Whether or not to restart the service if the the generated init script changes. Default: true
Default value: true
restart_service_on_docker_refresh
Data type: Boolean
Whether or not to restart the service if the docker service is restarted. Only has effect if the docker_service parameter is set. Default: true
Default value: true
manage_service
Data type: Boolean
(optional) Whether or not to create a puppet Service resource for the init script. Disabling this may be useful if integrating with existing modules. Default: true
Default value: true
docker_service
Data type: Variant[String,Boolean]
(optional) If (and how) the Docker service itself is managed by Puppet true -> Service['docker'] false -> no Service dependency anything else -> Service[docker_service] Default: false
Default value: false
health_check_cmd
Data type: Optional[String]
Default value: undef
health_check_interval
Data type: Optional[Integer]
Default value: undef
restart_on_unhealthy
Data type: Boolean
Default value: false
net
Data type: Variant[String,Array[String[1],1],Undef]
Default value: undef
extra_parameters
Data type: Optional[Variant[String,Array[String]]]
Default value: undef
systemd_restart
Data type: String
Default value: 'on-failure'
custom_unless
Data type: Variant[String,Array]
Default value: []
after_create
Data type: Optional[String]
Default value: undef
remain_after_exit
Data type: Optional[String]
Default value: undef
prepare_service_only
Data type: Boolean
Default value: false
image
Data type: Optional[Pattern[/^[\S]*$/]]
Default value: undef
ensure
Data type: Enum[present,absent]
Default value: 'present'
command
Data type: Optional[String]
Default value: undef
memory_limit
Data type: Pattern[/^[\d]*(b|k|m|g)$/]
Default value: '0b'
cpuset
Data type: Variant[String,Array,Undef]
Default value: []
ports
Data type: Variant[String,Array,Undef]
Default value: []
labels
Data type: Variant[String,Array,Undef]
Default value: []
expose
Data type: Variant[String,Array,Undef]
Default value: []
volumes
Data type: Variant[String,Array,Undef]
Default value: []
links
Data type: Variant[String,Array,Undef]
Default value: []
use_name
Data type: Boolean
Default value: false
running
Data type: Boolean
Default value: true
volumes_from
Data type: Variant[String,Array]
Default value: []
username
Data type: Variant[String,Boolean]
Default value: false
hostname
Data type: Variant[String,Boolean]
Default value: false
env
Data type: Variant[String,Array]
Default value: []
env_file
Data type: Variant[String,Array]
Default value: []
dns
Data type: Variant[String,Array]
Default value: []
dns_search
Data type: Variant[String,Array]
Default value: []
lxc_conf
Data type: Variant[String,Array]
Default value: []
service_provider
Data type: Optional[String]
Default value: undef
disable_network
Data type: Boolean
Default value: false
privileged
Data type: Boolean
Default value: false
detach
Data type: Optional[Boolean]
Default value: undef
extra_systemd_parameters
Data type: Variant[String,Hash]
Default value: {}
pull_on_start
Data type: Boolean
Default value: false
after
Data type: Variant[String,Array]
Default value: []
after_service
Data type: Variant[String,Array]
Default value: []
depends
Data type: Variant[String,Array]
Default value: []
depend_services
Data type: Variant[String,Array]
Default value: ['docker.service']
tty
Data type: Boolean
Default value: false
socket_connect
Data type: Variant[String,Array]
Default value: []
hostentries
Data type: Variant[String,Array]
Default value: []
before_start
Data type: Variant[String,Boolean]
Default value: false
before_stop
Data type: Variant[String,Boolean]
Default value: false
after_start
Data type: Variant[String,Boolean]
Default value: false
after_stop
Data type: Variant[String,Boolean]
Default value: false
remove_container_on_start
Data type: Boolean
Default value: true
remove_container_on_stop
Data type: Boolean
Default value: true
remove_volume_on_start
Data type: Boolean
Default value: false
remove_volume_on_stop
Data type: Boolean
Default value: false
stop_wait_time
Data type: Integer
Default value: 10
syslog_identifier
Data type: Optional[String]
Default value: undef
syslog_facility
Data type: Optional[String]
Default value: undef
read_only
Data type: Boolean
Default value: false
docker::secrets
The docker::secrets class.
Parameters
The following parameters are available in the docker::secrets defined type:
ensure
Data type: Enum[present,absent]
Default value: 'present'
label
Data type: Variant[String,Array]
Default value: []
secret_name
Data type: Optional[String]
Default value: undef
secret_path
Data type: Optional[String]
Default value: undef
docker::services
define that managers a Docker services
Parameters
The following parameters are available in the docker::services defined type:
ensureimagedetachenvlabelpublishreplicasttyuserworkdirextra_paramsupdatescalehost_socketregistry_mirrormountsnetworkscommandcreateservice_name
ensure
Data type: Enum[present,absent]
This ensures that the service is present or not.
Default value: 'present'
image
Data type: Optional[Variant[String,Array]]
The Docker image to spwan the service from.
Default value: undef
detach
Data type: Boolean
Exit immediately instead of waiting for the service to converge (default true)
Default value: true
env
Data type: Array
Set environment variables
Default value: []
label
Data type: Array
Service labels. This used as metdata to configure constraints etc.
Default value: []
publish
Data type: Optional[Variant[String,Array]]
Publish port(s) as node ports.
Default value: undef
replicas
Data type: Optional[Variant[String,Array]]
Number of tasks (containers per service)
Default value: undef
tty
Data type: Boolean
Allocate a pseudo-TTY
Default value: false
user
Data type: Optional[Variant[String,Array]]
Username or UID (format: <name|uid>[:<group|gid>])
Default value: undef
workdir
Data type: Optional[Variant[String,Array]]
Working directory inside the container
Default value: undef
extra_params
Data type: Array
Allows you to pass any other flag that the Docker service create supports. This must be passed as an array. See docker service create --help for all options
Default value: []
update
Data type: Boolean
This changes the docker command to docker service update, you must pass a service name with this option
Default value: false
scale
Data type: Boolean
This changes the docker command to docker service scale, this can only be used with service name and replicas
Default value: false
host_socket
Data type: Optional[Variant[String,Array]]
This will allow the service to connect to the host linux socket.
Default value: undef
registry_mirror
Data type: Optional[Variant[String,Array]]
This will allow the service to set a registry mirror.
Default value: undef
mounts
Data type: Optional[Variant[String,Array]]
Allows attaching filesystem mounts to the service (specified as an array)
Default value: undef
networks
Data type: Optional[Array]
Allows attaching the service to networks (specified as an array)
Default value: undef
command
Data type: Optional[Variant[String,Array]]
Command to run on the container
Default value: undef
create
Data type: Boolean
Default value: true
service_name
Data type: Optional[Variant[String,Array]]
Default value: undef
docker::stack
deploys Docker stacks or compose v3
Parameters
The following parameters are available in the docker::stack defined type:
ensure
Data type: Enum[present,absent]
This ensures that the stack is present or not.
Default value: 'present'
stack_name
Data type: Optional[String]
The name of the stack that you are deploying
Default value: undef
bundle_file
Data type: Optional[String]
Path to a Distributed Application Bundle file Please note this is experimental
Default value: undef
prune
Data type: Boolean
Prune services that are no longer referenced
Default value: false
resolve_image
Data type: Optional[Enum['always','changed','never']]
Query the registry to resolve image digest and supported platforms Only accepts ("always"|"changed"|"never")
Default value: undef
with_registry_auth
Data type: Boolean
Send registry authentication details to Swarm agents
Default value: false
compose_files
Data type: Optional[Array]
Default value: undef
docker::swarm
managers a Docker Swarm Mode cluster
Parameters
The following parameters are available in the docker::swarm defined type:
ensureinitjoinadvertise_addrautolockcert_expirydefault_addr_pooldefault_addr_pool_mask_lengthdispatcher_heartbeatexternal_caforce_new_clusterlisten_addrmax_snapshotssnapshot_intervaltokenmanager_ip
ensure
Data type: Enum[present,absent]
This ensures that the cluster is present or not. Note this forcefully removes a node from the cluster. Make sure all worker nodes have been removed before managers
Default value: 'present'
init
Data type: Boolean
This creates the first worker node for a new cluster. Set init to true to create a new cluster
Default value: false
join
Data type: Boolean
This adds either a worker or manger node to the cluster. The role of the node is defined by the join token. Set to true to join the cluster
Default value: false
advertise_addr
Data type: Optional[String]
The address that your node will advertise to the cluster for raft. On multihomed servers this flag must be passed
Default value: undef
autolock
Data type: Boolean
Enable manager autolocking (requiring an unlock key to start a stopped manager)
Default value: false
cert_expiry
Data type: Optional[String]
Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
Default value: undef
default_addr_pool
Data type: Optional[Array]
Array of default subnet pools for global scope networks (['30.30.0.0/16','40.40.0.0/16'])
Default value: undef
default_addr_pool_mask_length
Data type: Optional[String]
Default subnet pools mask length for default-addr-pools (CIDR block number)
Default value: undef
dispatcher_heartbeat
Data type: Optional[String]
Dispatcher heartbeat period (ns|us|ms|s|m|h) (default 5s)
Default value: undef
external_ca
Data type: Optional[String]
Specifications of one or more certificate signing endpoints
Default value: undef
force_new_cluster
Data type: Boolean
Force create a new cluster from current state
Default value: false
listen_addr
Data type: Optional[String]
The address that your node will listen to the cluster for raft. On multihomed servers this flag must be passed
Default value: undef
max_snapshots
Data type: Optional[String]
Number of additional Raft snapshots to retain
Default value: undef
snapshot_interval
Data type: Optional[String]
Number of log entries between Raft snapshots (default 10000)
Default value: undef
token
Data type: Optional[String]
The authentication token to join the cluster. The token also defines the type of node (worker or manager)
Default value: undef
manager_ip
Data type: Optional[String]
The ip address of a manager node to join the cluster.
Default value: undef
docker::system_user
manage docker group users
Parameters
The following parameters are available in the docker::system_user defined type:
create_user
Data type: Boolean
Boolean to cotrol whether the user should be created
Default value: true
docker::windows_account
Windows account that owns the docker services
Resource types
docker_compose
A type representing a Docker Compose file
Properties
The following properties are available in the docker_compose type.
ensure
Valid values: present, absent
The basic property that the resource should be in.
Default value: present
Parameters
The following parameters are available in the docker_compose type.
compose_files
An array of Docker Compose Files paths.
name
namevar
The name of the project
options
Additional options to be passed directly to docker-compose.
provider
The specific backend to use for this docker_compose resource. You will seldom need to specify this --- Puppet will
usually discover the appropriate provider for your platform.
scale
A hash of compose services and number of containers.
tmpdir
Override the temporary directory used by docker-compose.
This property is useful when the /tmp directory has been mounted with the noexec option. Or is otherwise being prevented It allows the module consumer to redirect docker-composes temporary files to a known directory.
The directory passed to this property must exist and be accessible by the user that is executing the puppet agent.
up_args
Arguments to be passed directly to docker-compose up.
docker_network
Type representing a Docker network
Properties
The following properties are available in the docker_network type.
driver
The network driver used by the network
ensure
Valid values: present, absent
The basic property that the resource should be in.
Default value: present
id
The ID of the network provided by Docker
ipam_driver
The IPAM (IP Address Management) driver
Parameters
The following parameters are available in the docker_network type.
additional_flags
Additional flags for the 'docker network create'
aux_address
Auxiliary ipv4 or ipv6 addresses used by the Network driver
gateway
An ipv4 or ipv6 gateway for the server subnet
ip_range
The range of IP addresses used by the network
name
namevar
The name of the network
options
Additional options for the network driver
provider
The specific backend to use for this docker_network resource. You will seldom need to specify this --- Puppet will
usually discover the appropriate provider for your platform.
subnet
The subnet in CIDR format that represents a network segment
docker_stack
A type representing a Docker Stack
Properties
The following properties are available in the docker_stack type.
ensure
Valid values: present, absent
The basic property that the resource should be in.
Default value: present
Parameters
The following parameters are available in the docker_stack type.
bundle_file
Path to a Distributed Application Bundle file.
compose_files
An array of Docker Compose Files paths.
name
namevar
The name of the stack
provider
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
v10.3.0 - 2025-04-14
Other
- (MODULES-11475): Fix formatting in docker run and service manifests #1017 (span786)
- Update package source to use rhel repo instead of deprecated centos. #999 (jbagleyjr)
v10.2.0 - 2025-03-10
Added
v10.1.0 - 2024-12-18
Added
- Add support for EL9 #1007 (ghoneycutt)
v10.0.1 - 2024-07-13
Fixed
v10.0.0 - 2024-07-04
Changed
- Use the docker-compose-plugin via 'docker compose' instead of 'docker-compose' #975 (nathanlcarlson)
Fixed
v9.1.0 - 2023-07-19
Added
- CONT-568 : Adding deferred function for password #918 (malikparvez)
v9.0.1 - 2023-07-06
Fixed
v8.0.0 - 2023-07-05
Changed
Added
- (CONT-1121) - Add support for CentOS 8 #926 (jordanbreen28)
v7.0.0 - 2023-05-02
Changed
- (CONT-776) - Add Puppet 8/Drop Puppet 6 #910 (jordanbreen28)
v6.1.0 - 2023-04-28
Added
Fixed
- Fix
dockerfact with recent version of docker #897 (smortex) - Use puppet yaml helper to workaround psych >4 breaking changes #877 (gfargeas)
v6.0.2 - 2022-12-08
Fixed
- (CONT-24) docker_stack always redoploying #878 (david22swan)
v6.0.1 - 2022-11-25
Fixed
v6.0.0 - 2022-11-21
Changed
- (CONT-263) Bumping required puppet version #871 (LukasAud)
- docker_run_flags: Shellescape any provided values #869 (LukasAud)
- (maint) Hardening manifests and tasks #863 (LukasAud)
v5.1.0 - 2022-10-21
Added
Fixed
- pdksync - (CONT-130) Dropping Support for Debian 9 #859 (jordanbreen28)
- Change
stop_wait_timevalue to match Docker default #858 (sebcdri)
v5.0.0 - 2022-08-19
Changed
Added
- pdksync - (GH-cat-11) Certify Support for Ubuntu 22.04 #850 (david22swan)
- adding optional variable for package_key_check_source to RedHat #846 (STaegtmeier)
- New create_user parameter on main class #841 (traylenator)
v4.4.0 - 2022-06-01
Added
Fixed
- Avoid empty array to -net parameter #837 (chelnak)
- (GH-785) Fix duplicate stack matching #836 (chelnak)
- Fix docker-compose, network and volumes not applying on 1st run, fix other idempotency #833 (canihavethisone)
- Fixed docker facts to check for active swarm clusters before running docker swarm sub-commands. #817 (nmaludy)
v4.3.0 - 2022-05-16
Added
- Add tmpdir option to docker_compose #823 (canihavethisone)
- Support different Architectures (like
aarch64) when installing Compose #812 (mpdude)
Fixed
- Only install docker-ce-cli with docker-ce #827 (vchepkov)
- remove some legacy facts #802 (traylenator)
- Fix missing comma in docker::image example #787 (Vincevrp)
- allow docker::networks::networks param to be undef #783 (jhoblitt)
v4.2.1 - 2022-04-14
Fixed
v4.2.0 - 2022-04-11
Added
- pdksync - (FM-8922) - Add Support for Windows 2022 #801 (david22swan)
- (IAC-1729) Add Support for Debian 11 #799 (david22swan)
Fixed
- pdksync - (GH-iac-334) Remove Support for Ubuntu 14.04/16.04 #807 (david22swan)
- Fix idempotency when using scaling with docker-compose #805 (canihavethisone)
- Make RedHat version check respect acknowledge_unsupported_os #788 (PolaricEntropy)
v4.1.2 - 2021-09-27
Fixed
- pdksync - (IAC-1598) - Remove Support for Debian 8 #775 (david22swan)
- Prefer timeout to time_limit for Facter::Core::Execution #774 (smortex)
- Fix facts gathering #773 (smortex)
v4.1.1 - 2021-08-26
Fixed
- (IAC-1741) Allow stdlib v8.0.0 #767 (david22swan)
- Remove stderr empty check to avoid docker_params_changed failures when warnings appear #764 (cedws)
- Duplicate declaration statement: docker_params_changed is already declared #763 (basti-nis)
- Timeout for hangs of the docker_client in the facts generation #759 (carabasdaniel)
v4.1.0 - 2021-06-28
Added
Fixed
- Fix docker::volumes hiera example #754 (pskopnik)
- Allow force update non-latest tagged image #752 (yanjunding)
- Allow management of the docker-ce-cli package #740 (kenyon)
v4.0.1 - 2021-05-26
Fixed
- (IAC-1497) - Removal of unsupported
translatedependency #737 (david22swan) - add simple quotes around env service flag #706 (adrianiurca)
v4.0.0 - 2021-03-04
v3.14.0 - 2021-03-04
Changed
- pdksync - Remove Puppet 5 from testing and bump minimal version to 6.0.0 #718 (carabasdaniel)
Fixed
- [MODULES-10898] Disable forced docker service restart for RedHat 7 and docker server 1.13 #730 (carabasdaniel)
- Make it possible to use pod's network #725 (seriv)
v3.13.1 - 2021-02-02
Fixed
- (IAC-1218) - docker_params_changed should be run by agent #705 (adrianiurca)
- Fix systemd units for systemd versions < v230 #704 (benningm)
- setting HOME environment to /root #698 (adrianiurca)
v3.13.0 - 2020-12-14
Added
- pdksync - (feat) - Bump Puppet boundary #687 (daianamezdrea)
- Ensure image digest checksum before starting #673 (tmanninger)
- Support multiple mirrors #659 #669 (TheLocehiliosan)
Fixed
- Options to docker-compose should be an Array, not a String #695 (adrianiurca)
- fixing issue #689 by setting HOME in docker command #692 (sdinten)
- (MAINT) Use docker-compose config instead file parsing #672 (rbelnap)
- Fix array of additional flags #671 (CAPSLOCK2000)
- Test against OS family rather than name #667 (bodgit)
v3.12.1 - 2020-10-14
Fixed
v3.12.0 - 2020-09-29
Added
Fixed
- (IAC-982) - Remove inappropriate terminology #654 (david22swan)
v3.11.0 - 2020-08-11
Added
- Fix #584: Deal with Arrays for the net list #647 (MG2R)
- pdksync - (IAC-973) - Update travis/appveyor to run on new default branch main #643 (david22swan)
Fixed
- [MODULES-10734] - improve params detection on docker::run #648 (adrianiurca)
v3.10.2 - 2020-07-17
Fixed
- (MODULES-10691) - Add root_dir in daemon.json #632 (daianamezdrea)
- Fixing the fix 'Fix the docker_compose options parameter position #378' #631 (awegmann)
- Blocking ordering between non-Windows service stops #622 (AndrewLipscomb)
- Allow all 3.x docker-compose minor versions #620 (runejuhl)
v3.10.1 - 2020-05-28
Fixed
- Fix unreachable StartLimitBurst value in unit template #616 (omeinderink)
- (MODULES-9696) remove docker_home_dirs fact #613 (carabasdaniel)
- [MODULES-10629] Throw error when docker login fails #610 (carabasdaniel)
- (maint) - facts fix for centos #608 (david22swan)
- major adjustments for current code style #607 (crazymind1337)
v3.10.0 - 2020-04-23
Added
- [IAC-291] Convert acceptance tests to Litmus #585 (carabasdaniel)
- Updated: Add Docker service (create, remote, scale) tasks #582 (Flask)
- Add after_start and after_stop options to docker::run define #580 (jantman)
- Make docker::machine::url configurable #569 (baurmatt)
- Let docker.service start docker services managed by puppetlabs/docker… #563 (jhejl)
- Allow bypassing curl package ensure if needed #477 (esalberg)
Fixed
- Enforce TLS1.2 on Windows; minor fixes for RH-based testing #603 (carabasdaniel)
- [MODULES-10628] Update documentation for docker volume and set options as parameter #599 (carabasdaniel)
- Allow module to work on SLES #591 (npwalker)
- (maint) Fix missing stubs in docker_spec.rb #589 (Filipovici-Andrei)
- Add Hiera lookups for resources in init.pp #586 (fe80)
- Use standardized quote type to help tests pass #566 (DLeich)
- Minimal changes to work with podman-docker #562 (seriv)
v3.9.1 - 2020-01-20
Fixed
- (maint) fix dependencies of powershell to 4.0.0 #568 (sheenaajay)
v3.9.0 - 2019-12-09
Added
Fixed
- Fix error does not show when image:tag does not exists (#552) #553 (rafaelcarv)
- Allow defining the name of the docker-compose symlink #544 (gtufte)
- Clarify usage of docker_stack type up_args and fix link to docs #537 (jacksgt)
- Move StartLimit* options to [Unit], fix StartLimitIntervalSec #531 (runejuhl)
v3.8.0 - 2019-10-01
Added
Fixed
- Fix multiple additional flags for docker_network #523 (lemrouch)
- :bug: Fix wrong service detach handling #520 (khaefeli)
- Fix aliased plugin names #514 (koshatul)
v3.7.0-bna - 2019-08-08
Added
Fixed
- Fixing error: #516 (darshannnn)
e2.6 - 2019-07-26
v3.7.0 - 2019-07-19
Added
v3.6.0 - 2019-06-25
Changed
Added
- (FM-8151) Add Windows Server 2019 support #493 (eimlav)
- Support for docker machine download and install #466 (acurus-puppetmaster)
- Add service_provider parameter to docker::run #376 (jameslikeslinux)
Fixed
- Tasks frozen string #499 (khaefeli)
- Fix #239 local_user permission denied #497 (thde)
- (MODULES-9193) Revert part of MODULES-9177 #490 (eimlav)
- (MODULES-9177) Fix version validation regex #489 (eimlav)
- Fix publish flag being erroneously added to docker service commands #471 (twistedduck)
- Fix container running check to work for windows hosts #470 (florindragos)
- Allow images tagged latest to update on each run #468 (electrofelix)
- Fix docker::image to not run images #465 (hugotanure)
3.5.0 - 2019-03-14
Fixed
- fix(syntax): Remove duplicate parenthesis #454 (jfroche)
- Docker::Services:: fix command parameter used with an array #452 (jacksgt)
- docker::services: Fix using multiple published ports #447 (jacksgt)
3.4.0 - 2019-02-25
e2.0 - 2019-02-21
Fixed
- fixing errors with bundle file conditional statement #436 (davejrt)
- #432 Fix frozen string error #434 (khaefeli)
3.3.0 - 2019-02-13
3.2.0 - 2019-01-17
Fixed
- centos repo fix #413 (davejrt)
- rhel fix #412 (davejrt)
- fixing various issues with tests across all supported OS #406 (davejrt)
- Fix shared scripts on non systemd systems #400 (glorpen)
- Do not load powershell profiles #396 (florindragos)
- Fix stack acceptance tests #395 (florindragos)
- fixing acceptance tests on debian #393 (davejrt)
- fixing deep merge issue and yaml alias #387 (davejrt)
- Adds a Usage example for daemon level extra_parameters #386 (mpepping)
- Fixing create_resources for volumes #384 (andytechdad)
- Fix the docker_compose options parameter position #378 (FlorentPoinsaut)
- Allow multiple values for subnet in docker_network #371 (florindragos)
- Cloud 2191 fix stack acceptance test #368 (MWilsonPuppet)
- Create shared start/stop scripts for better extensibility #367 (glorpen)
- Fixing incorrect variable names in docker_compose/ruby.rb #365 (lowerpuppet)
- update docker_stack to fix registry auth option #364 (davejrt)
- Fix registry local_user functionalitity. #353 (stejanse)
- Fix windows default paths #326 (florindragos)
3.1.0 - 2018-10-22
Fixed
- Fix acceptance tests for windows #349 (florindragos)
- pinning puppet version to fix failing spec tests #346 (MWilsonPuppet)
3.0.0 - 2018-09-27
Fixed
- Fix docker swarm tasks boolean params #338 (florindragos)
- CLOUD-2069 Adding support for multiple compose files. #332 (MWilsonPuppet)
- fixes puppet run failures with no IPAM driver #329 (davejrt)
- CLOUD-2078-Uninstall Docker on Linux #328 (MWilsonPuppet)
- Fix error messages from docker facts if docker not running #325 (stdietrich)
- Fix docker-compose provider to support images built on the fly #320 (florindragos)
- fixing bug in upstart systems #304 (davejrt)
- Fix for registry password not being inserted due to single quotes #299 (ConorPKeegan)
- Fix docker registry idempotency and add windows acceptance tests #298 (florindragos)
- Regex fix #292 (davejrt)
2.0.0 - 2018-07-18
Fixed
- fixes restarting containers with changes to run arguments #283 (davejrt)
- fix "start a container with cpuset" acceptance test on ubuntu1404 #236 (mihaibuzgau)
1.1.0 - 2018-03-16
Fixed
- (maint)CLOUD-1768 Fixing incorrect cpuset flag #183 #187 (MWilsonPuppet)
e1.1 - 2018-02-15
Fixed
1.0.5 - 2018-01-31
1.0.4 - 2018-01-03
1.0.3 - 2018-01-03
e1.0 - 2017-12-21
1.0.2 - 2017-11-17
1.0.1 - 2017-10-15
1.0.0 - 2017-10-11
Dependencies
- puppetlabs/stdlib (>= 9.0.0 < 10.0.0)
- puppetlabs/apt (>= 4.4.1 < 11.0.0)
- puppetlabs/powershell (>= 2.1.4 < 7.0.0)
- puppetlabs/reboot (>=2.0.0 < 6.0.0)
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the
copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other
entities that control, are controlled by, or are under common control with
that entity. For the purposes of this definition, "control" means (i) the
power, direct or indirect, to cause the direction or management of such
entity, whether by contract or otherwise, or (ii) ownership of
fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising
permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation source,
and configuration files.
"Object" form shall mean any form resulting from mechanical transformation
or translation of a Source form, including but not limited to compiled
object code, generated documentation, and conversions to
other media types.
"Work" shall mean the work of authorship, whether in Source or Object
form, made available under the License, as indicated by a copyright notice
that is included in or attached to the work (an example is provided in the
Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form,
that is based on (or derived from) the Work and for which the editorial
revisions, annotations, elaborations, or other modifications represent,
as a whole, an original work of authorship. For the purposes of this
License, Derivative Works shall not include works that remain separable
from, or merely link (or bind by name) to the interfaces of, the Work and
Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original
version of the Work and any modifications or additions to that Work or
Derivative Works thereof, that is intentionally submitted to Licensor for
inclusion in the Work by the copyright owner or by an individual or
Legal Entity authorized to submit on behalf of the copyright owner.
For the purposes of this definition, "submitted" means any form of
electronic, verbal, or written communication sent to the Licensor or its
representatives, including but not limited to communication on electronic
mailing lists, source code control systems, and issue tracking systems
that are managed by, or on behalf of, the Licensor for the purpose of
discussing and improving the Work, but excluding communication that is
conspicuously marked or otherwise designated in writing by the copyright
owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on
behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License.
Subject to the terms and conditions of this License, each Contributor
hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
royalty-free, irrevocable copyright license to reproduce, prepare
Derivative Works of, publicly display, publicly perform, sublicense,
and distribute the Work and such Derivative Works in
Source or Object form.
3. Grant of Patent License.
Subject to the terms and conditions of this License, each Contributor
hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
royalty-free, irrevocable (except as stated in this section) patent
license to make, have made, use, offer to sell, sell, import, and
otherwise transfer the Work, where such license applies only to those
patent claims licensable by such Contributor that are necessarily
infringed by their Contribution(s) alone or by combination of their
Contribution(s) with the Work to which such Contribution(s) was submitted.
If You institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or
contributory patent infringement, then any patent licenses granted to
You under this License for that Work shall terminate as of the date such
litigation is filed.
4. Redistribution.
You may reproduce and distribute copies of the Work or Derivative Works
thereof in any medium, with or without modifications, and in Source or
Object form, provided that You meet the following conditions:
1. You must give any other recipients of the Work or Derivative Works a
copy of this License; and
2. You must cause any modified files to carry prominent notices stating
that You changed the files; and
3. You must retain, in the Source form of any Derivative Works that You
distribute, all copyright, patent, trademark, and attribution notices from
the Source form of the Work, excluding those notices that do not pertain
to any part of the Derivative Works; and
4. If the Work includes a "NOTICE" text file as part of its distribution,
then any Derivative Works that You distribute must include a readable copy
of the attribution notices contained within such NOTICE file, excluding
those notices that do not pertain to any part of the Derivative Works,
in at least one of the following places: within a NOTICE text file
distributed as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or, within a
display generated by the Derivative Works, if and wherever such
third-party notices normally appear. The contents of the NOTICE file are
for informational purposes only and do not modify the License.
You may add Your own attribution notices within Derivative Works that You
distribute, alongside or as an addendum to the NOTICE text from the Work,
provided that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and may
provide additional or different license terms and conditions for use,
reproduction, or distribution of Your modifications, or for any such
Derivative Works as a whole, provided Your use, reproduction, and
distribution of the Work otherwise complies with the conditions
stated in this License.
5. Submission of Contributions.
Unless You explicitly state otherwise, any Contribution intentionally
submitted for inclusion in the Work by You to the Licensor shall be under
the terms and conditions of this License, without any additional
terms or conditions. Notwithstanding the above, nothing herein shall
supersede or modify the terms of any separate license agreement you may
have executed with Licensor regarding such Contributions.
6. Trademarks.
This License does not grant permission to use the trade names, trademarks,
service marks, or product names of the Licensor, except as required for
reasonable and customary use in describing the origin of the Work and
reproducing the content of the NOTICE file.
7. Disclaimer of Warranty.
Unless required by applicable law or agreed to in writing, Licensor
provides the Work (and each Contributor provides its Contributions)
on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied, including, without limitation, any warranties
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS
FOR A PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any risks
associated with Your exercise of permissions under this License.
8. Limitation of Liability.
In no event and under no legal theory, whether in tort
(including negligence), contract, or otherwise, unless required by
applicable law (such as deliberate and grossly negligent acts) or agreed
to in writing, shall any Contributor be liable to You for damages,
including any direct, indirect, special, incidental, or consequential
damages of any character arising as a result of this License or out of
the use or inability to use the Work (including but not limited to damages
for loss of goodwill, work stoppage, computer failure or malfunction,
or any and all other commercial damages or losses), even if such
Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability.
While redistributing the Work or Derivative Works thereof, You may choose
to offer, and charge a fee for, acceptance of support, warranty,
indemnity, or other liability obligations and/or rights consistent with
this License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf of any
other Contributor, and only if You agree to indemnify, defend, and hold
each Contributor harmless for any liability incurred by, or claims
asserted against, such Contributor by reason of your accepting any such
warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work
To apply the Apache License to your work, attach the following boilerplate
notice, with the fields enclosed by brackets "[]" replaced with your own
identifying information. (Don't include the brackets!) The text should be
enclosed in the appropriate comment syntax for the file format. We also
recommend that a file or class name and description of purpose be included
on the same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2013 Gareth Rushgrove
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied. See the License for the specific language governing
permissions and limitations under the License.