diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c6270b..6bfbe2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,245 +1,261 @@ # Change log All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org). +## [v3.8.0](https://github.com/puppetlabs/puppetlabs-docker/tree/v3.8.0) (2019-10-01) + +[Full Changelog](https://github.com/puppetlabs/puppetlabs-docker/compare/v3.7.0...v3.8.0) + +### Added + +- pdksync - Add support on Debian10 [\#525](https://github.com/puppetlabs/puppetlabs-docker/pull/525) ([lionce](https://github.com/lionce)) +- Add new Docker Swarm Tasks \(node ls, rm, update; service scale\) [\#509](https://github.com/puppetlabs/puppetlabs-docker/pull/509) ([khaefeli](https://github.com/khaefeli)) + +### Fixed + +- Fix multiple additional flags for docker\_network [\#523](https://github.com/puppetlabs/puppetlabs-docker/pull/523) ([lemrouch](https://github.com/lemrouch)) +- :bug: Fix wrong service detach handling [\#520](https://github.com/puppetlabs/puppetlabs-docker/pull/520) ([khaefeli](https://github.com/khaefeli)) +- Fixing error: [\#516](https://github.com/puppetlabs/puppetlabs-docker/pull/516) ([darshannnn](https://github.com/darshannnn)) +- Fix aliased plugin names [\#514](https://github.com/puppetlabs/puppetlabs-docker/pull/514) ([koshatul](https://github.com/koshatul)) + ## [v3.7.0](https://github.com/puppetlabs/puppetlabs-docker/tree/v3.7.0) (2019-07-18) [Full Changelog](https://github.com/puppetlabs/puppetlabs-docker/compare/v3.6.0...v3.7.0) ### Added - Added option to override docker-compose download location [\#482](https://github.com/puppetlabs/puppetlabs-docker/pull/482) ([piquet90](https://github.com/piquet90)) ## [v3.6.0](https://github.com/puppetlabs/puppetlabs-docker/tree/v3.6.0) (2019-06-25) [Full Changelog](https://github.com/puppetlabs/puppetlabs-docker/compare/3.5.0...v3.6.0) ### Changed - \(FM-8100\) Update minimum supported Puppet version to 5.5.10 [\#486](https://github.com/puppetlabs/puppetlabs-docker/pull/486) ([eimlav](https://github.com/eimlav)) ### Added - \(FM-8151\) Add Windows Server 2019 support [\#493](https://github.com/puppetlabs/puppetlabs-docker/pull/493) ([eimlav](https://github.com/eimlav)) - Support for docker machine download and install [\#466](https://github.com/puppetlabs/puppetlabs-docker/pull/466) ([acurus-puppetmaster](https://github.com/acurus-puppetmaster)) - Add service\_provider parameter to docker::run [\#376](https://github.com/puppetlabs/puppetlabs-docker/pull/376) ([iamjamestl](https://github.com/iamjamestl)) ### Fixed - Tasks frozen string [\#499](https://github.com/puppetlabs/puppetlabs-docker/pull/499) ([khaefeli](https://github.com/khaefeli)) - Fix \#239 local\_user permission denied [\#497](https://github.com/puppetlabs/puppetlabs-docker/pull/497) ([thde](https://github.com/thde)) - \(MODULES-9193\) Revert part of MODULES-9177 [\#490](https://github.com/puppetlabs/puppetlabs-docker/pull/490) ([eimlav](https://github.com/eimlav)) - \(MODULES-9177\) Fix version validation regex [\#489](https://github.com/puppetlabs/puppetlabs-docker/pull/489) ([eimlav](https://github.com/eimlav)) - Fix publish flag being erroneously added to docker service commands [\#471](https://github.com/puppetlabs/puppetlabs-docker/pull/471) ([twistedduck](https://github.com/twistedduck)) - Fix container running check to work for windows hosts [\#470](https://github.com/puppetlabs/puppetlabs-docker/pull/470) ([florindragos](https://github.com/florindragos)) - Allow images tagged latest to update on each run [\#468](https://github.com/puppetlabs/puppetlabs-docker/pull/468) ([electrofelix](https://github.com/electrofelix)) - Fix docker::image to not run images [\#465](https://github.com/puppetlabs/puppetlabs-docker/pull/465) ([hugotanure](https://github.com/hugotanure)) # 3.5.0 Changes range for dependent modules Use multiple networks in docker::run and docker::services Fixes quotes with docker::services command Publish multiple ports to docker::services A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/milestone/7?closed=1) # 3.4.0 Introduces docker_stack type and provider Fixes frozen string in docker swarm token task Acceptance testing updates Allow use of newer translate module A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/milestone/6?closed=1) # Version 3.3.0 Pins apt repo to 500 to ensure packages are updated Fixes issue in docker fact failing when docker is not started Acceptance testing updates Allows more recent version of the reboot module A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/milestone/5?closed=1) # Version 3.2.0 Adds in support for Puppet 6 Containers will be restared due to script changes in [PR #367](https://github.com/puppetlabs/puppetlabs-docker/pull/367) A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/milestone/4?closed=1) # Version 3.1.0 Adding in the following faetures/functionality - Docker Stack support on Windows. # Version 3.0.0 Various fixes for github issues - 206 - 226 - 241 - 280 - 281 - 287 - 289 - 294 - 303 - 312 - 314 Adding in the following features/functionality -Support for multiple compose files. A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/issues?q=is%3Aissue+milestone%3AV3.0.0+is%3Aclosed) # Version 2.0.0 Various fixes for github issues - 193 - 197 - 198 - 203 - 207 - 208 - 209 - 211 - 212 - 213 - 215 - 216 - 217 - 218 - 223 - 224 - 225 - 228 - 229 - 230 - 232 - 234 - 237 - 243 - 245 - 255 - 256 - 259 Adding in the following features/functionality - Ability to define swarm clusters in Hiera. - Support docker compose file V2.3. - Support refresh only flag. - Support for Docker healthcheck and unhealthy container restart. - Support for Docker on Windows: - Add docker ee support for windows server 2016. - Docker image on Windows. - Docker run on Windows. - Docker compose on Windows. - Docker swarm on Windows. - Add docker exec functionality for docker on windows. - Add storage driver for Windows. A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/milestone/2?closed=1) # Version 1.1.0 Various fixes for Github issues - 183 - 173 - 173 - 167 - 163 - 161 Adding in the following features/functionality - IPv6 support - Define type for docker plugins A full list of issues and PRs associated with this release can be found [here](https://github.com/puppetlabs/puppetlabs-docker/milestone/1?closed=1) # Version 1.0.5 Various fixes for Github issues - 98 - 104 - 115 - 122 - 124 Adding in the following features/functionality - Removed all unsupported OS related code from module - Removed EPEL dependency - Added http support in compose proxy - Added in rubocop support and i18 gem support - Type and provider for docker volumes - Update apt module to latest - Added in support for a registry mirror - Facts for docker version and docker info - Fixes for $pass_hash undef - Fixed typo in param.pp - Replaced deprecated stblib functions with data types # Version 1.0.4 Correcting changelog # Version 1.0.3 Various fixes for Github issues - 33 - 68 - 74 - 77 - 84 Adding in the following features/functionality: - Add tasks to update existing service - Backwards compatible TMPDIR - Optional GPG check on repos - Force pull on image tag 'latest' - Add support for overlay2.override_kernel_check setting - Add docker network fact - Add pw hash for registry login idompodency - Additional flags for creating a network - Fixing incorrect repo url for redhat # Version 1.0.2 Various fixes for Github issues - 9 - 11 - 15 - 21 Add tasks support for Docker Swarm # Version 1.0.1 Updated metadata and CHANGELOG # Version 1.0.0 Forked for garethr/docker v5.3.0 Added support for: - Docker services within a swarm cluster - Swarm mode - Docker secrets \* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)* diff --git a/README.md b/README.md index 741329d..3a62d1f 100755 --- a/README.md +++ b/README.md @@ -1,1636 +1,1012 @@ [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-docker.svg?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-docker) [![Puppet Forge](https://img.shields.io/puppetforge/v/puppetlabs/docker.svg)](https://forge.puppetlabs.com/puppetlabs/docker) [![Puppet Forge Downloads](http://img.shields.io/puppetforge/dt/puppetlabs/docker.svg)](https://forge.puppetlabs.com/puppetlabs/docker) [![Puppet Forge Endorsement](https://img.shields.io/puppetforge/e/puppetlabs/docker.svg)](https://forge.puppetlabs.com/puppetlabs/docker) # Docker #### Table of Contents 1. [Description](#description) 2. [Setup](#setup) * [Proxy on Windows](#proxy-on-windows) * [Validating and unit testing the module](#validating-and-unit-testing-the-module) 3. [Usage - Configuration options and additional functionality](#usage) * [Images](#images) * [Containers](#containers) * [Networks](#networks) * [Volumes](#volumes) * [Compose](#compose) * [Machine](#machine) * [Swarm mode](#swarm-mode) * [Tasks](#tasks) * [Docker services](#docker-services) * [Private registries](#private-registries) * [Exec](#exec) * [Plugins](#plugins) 4. [Reference - An under-the-hood peek at what the module is doing and how](#reference) - * [Classes](#classes) - * [Defined types](#defined-types) - * [Types](#types) - * [Parameters](#parameters) - * [Functions](#functions) 5. [Limitations - OS compatibility, etc.](#limitations) 6. [Development - Guide for contributing to the module](#development) ## Description The Puppet docker module installs, configures, and manages [Docker](https://github.com/docker/docker) from the [Docker repository](https://docs.docker.com/installation/). It supports the latest [Docker CE (Community Edition)](https://www.docker.com/community-edition) for Linux based distributions and [Docker EE(Enterprise Edition)](https://www.docker.com/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: ```puppet include 'docker' ``` To configure package sources independently and disable automatically including sources, add the following code to the manifest file: ```puppet class { 'docker': use_upstream_package_source => false, } ``` The latest Docker [repositories](https://docs.docker.com/engine/installation/linux/docker-ce/debian/#set-up-the-repository) 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: ```puppet class { 'docker': version => '17.09.0~ce-0~debian', } ``` Using a version prior to 17.06, configures and installs from the old repositories: ```puppet class { 'docker': version => '1.12.0-0~wheezy', } ``` Docker provides a enterprise addition of the [Docker Engine](https://www.docker.com/enterprise-edition), called Docker EE. To install Docker EE on Debian systems, add the following code to the manifest file: ```puppet class { 'docker': docker_ee => true, docker_ee_source_location => 'https://', docker_ee_key_source => 'https://', docker_ee_key_id => '', } ``` To install Docker EE on RHEL/CentOS: ```puppet class { 'docker': docker_ee => true, docker_ee_source_location => 'https://', docker_ee_key_source => 'https://', } ``` 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](https://wiki.centos.org/AdditionalResources/Repositories) and the official [Docker documentation](https://docs.docker.com/install/linux/docker-ce/centos/). 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: ```puppet 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: ```puppet 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: ```puppet 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](https://docs.docker.com/v17.09/engine/userguide/networking/default_network/custom-docker0/). 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): ```puppet 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: ```puppet 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: ```puppet 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: ```puppet 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: ```puppet 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: ```puppet class { 'docker': version => 'latest', } ``` To install docker from a test or edge channel, add the following code to the manifest file: ```puppet class { 'docker': docker_ce_channel => 'test' } ``` To allocate a dns server to the Docker daemon, add the following code to the manifest file: ```puppet class { 'docker': dns => '8.8.8.8', } ``` To add users to the Docker group, add the following array to the manifest file: ```puppet class { 'docker': docker_users => ['user1', 'user2'], } ``` To add daemon labels, add the following array to the manifest file: ```puppet class { 'docker': labels => ['storage=ssd','stage=production'], } ``` To pass additional parameters to the daemon, add `extra_parameters` to the manifest file: ```puppet class { 'docker': extra_parameters => ['--experimental=true', '--metrics-addr=localhost:9323'], ``` To uninstall docker, add the following to the manifest file: ```puppet 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: ```puppet class { 'docker': docker_ee => true } ``` ### 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](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-docker/configure-docker-daemon#proxy-configuration) 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. ```puppet 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)](https://puppet.com/docs/pdk/1.x/pdk.html), which provides tools to help run unit tests on the module and validate the modules's 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](https://puppet.com/docs/pdk/1.x/pdk_reference.html#pdk-validate-command). 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](https://puppet.com/docs/pdk/1.x/pdk_reference.html#pdk-test-unit-command). ## 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: ```puppet 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: ```puppet 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: ```puppet 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: ```puppet 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: ```puppet 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: ```puppet 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: ```yaml --- classes: - docker::images docker::images::images: ubuntu: image_tag: 'precise' ``` ### Containers To launch containers, add the following code to the manifest file: ```puppet 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: ```puppet 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: '', 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 => [ 'container_b', 'mysql' ], depends => [ 'container_a', 'postgres' ], stop_wait_time => 0, 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 container 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 consuquences and have a specific use case. To execute a command before the container stops, specify the `before_stop` parameter. 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 depended 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: ```puppet 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: ```puppet 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: ```yaml --- 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. ```puppet docker::run { 'helloworld': ensure => absent, } ``` To enable the restart of an unhealthy container, add the following code to the manifest file. In order to set the health check interval time set the optional health_check_interval parameter, the default health check interval is 30 seconds. ```puppet docker::run { 'helloworld': image => 'base', command => 'command', health_check_cmd => '', restart_on_unhealthy => true, health_check_interval => '