Merge pull request #1 from puppetlabs/master

rebase

.travis.yml

@@ -10,29 +10,17 @@ before_install:
   - gem --version
   - bundle -v
 script:
-  - 'bundle exec rake $CHECK'
-bundler_args: --without system_tests
+  - 'bundle exec rake syntax lint metadata_lint check:symlinks check:git_ignore check:dot_underscore check:test_file rubocop'
+  - 'bundle exec rake parallel_spec'
+bundler_args:
 rvm:
-  - 2.5.1
+  - 2.4.4
 env:
-  global:
-    - BEAKER_PUPPET_COLLECTION=puppet6 PUPPET_GEM_VERSION="~> 6.0"
+  - PUPPET_GEM_VERSION="~> 4.0"
+  - PUPPET_GEM_VERSION="~> 5.0"
+  - PUPPET_GEM_VERSION="~> 6.0"
 matrix:
   fast_finish: true
-  include:
-    -
-      env: CHECK="syntax lint metadata_lint check:symlinks check:git_ignore check:dot_underscore check:test_file rubocop"
-    -
-      env: CHECK=parallel_spec
-    -
-      env: PUPPET_GEM_VERSION="~> 6.0" CHECK=parallel_spec
-      rvm: 2.4.4
-    -
-      env: PUPPET_GEM_VERSION="~> 5.0" CHECK=parallel_spec
-      rvm: 2.4.4
-    -
-      env: PUPPET_GEM_VERSION="~> 4.0" CHECK=parallel_spec
-      rvm: 2.1.9
 branches:
   only:
     - master

README.md

@@ -9,33 +9,33 @@
 
 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)
-   * [Swarm mode](#swarmmode)
+   * [Swarm mode](#swarm-mode)
    * [Tasks](#tasks)
-   * [Docker services](#dockerservices)
-   * [Private registries](#privateregistries)
+   * [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](#definedtypes)
+   * [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)
 
-## Overview
-
-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.
 
 ## Description
 
-This module install, configures, and manages [Docker](https://github.com/docker/docker).
+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.
 
@@ -127,10 +127,11 @@ class { 'docker':
   bip             => '192.168.1.1/24',
   fixed_cidr      => '192.168.1.144/28',
 }
-
-For more information about the options to configure the default docker bridge, see (this)[https://docs.docker.com/v17.09/engine/userguide/networking/default_network/custom-docker0/] page.
 ```
 
+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/).
+
+
 When setting up TLS, upload the related files (CA certificate, server certificate, and key) and include their paths in the manifest file:
 
 ```puppet
@@ -237,6 +238,26 @@ service { 'docker'
 }
 ````
 
+### 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
@@ -332,6 +353,7 @@ This is equivalent to running the  `docker run -d base /bin/sh -c "while true; d
 ```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'],
@@ -376,9 +398,9 @@ The `extra_parameters` parameter, which contains an array of command line argume
 
 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 ise used, whether it be in a remote registry or installed on the server already by the `docker::image` define type.
+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. For this this reason it highly recommended that an alternative tag be used, or the image be removed before pulling latest again.
+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:
 
@@ -615,7 +637,7 @@ To deploy the stack, add the following code to the manifest file:
 
 To remove the stack, set `ensure  => absent`.
 
-If you are using a v3.2compose 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.
+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.
 
@@ -824,7 +846,7 @@ docker::registry_auth::registries:
     version: '<docker_version>'
 ```
 
-If using Docker V1.11 or later, the docker login email flag has been deprecated [docker_change_log](https://docs.docker.com/release-notes/docker-engine/#1110-2016-04-13).
+If using Docker V1.11 or later, the docker login email flag has been deprecated. See the [docker_change_log](https://docs.docker.com/release-notes/docker-engine/#1110-2016-04-13).
 
 Add the following code to the manifest file:
 
@@ -879,7 +901,7 @@ docker::exec { 'cron_allow_root':
 
 ### Plugin
 
-The module supports the installation of docker plugins:
+The module supports the installation of Docker plugins:
 
 ```puppet
 docker::plugin {'foo/fooplugin:latest':
@@ -891,7 +913,7 @@ To disable an active plugin:
 
 ```puppet
 docker::plugin {'foo/fooplugin:latest':
-  enaled => false,
+  enabled => false,
 }
 ```
 
@@ -920,14 +942,15 @@ thub.com
 * docker::registry_auth
 * docker::run_instance
 * docker::services
+* docker::swarms
 * docker::systemd_reload
 * docker::volumes
 
 #### Private classes
 
-* docker::repos
-* docker::install
 * docker::config
+* docker::install
+* docker::repos
 * docker::service
 
 ### Defined types
@@ -941,6 +964,7 @@ thub.com
 * docker::stack
 * docker::swarm
 * docker::system_user
+* docker::windows_account
 
 ### Types
 
@@ -990,7 +1014,7 @@ An ipv6 or ipv4 gateway for the master subnet.
 
 #### `ip_range`
 
-The range of ip addresses used by the network.
+The range of IP addresses used by the network.
 
 #### `ipam_driver`
 
@@ -1118,7 +1142,7 @@ Enable the Docker unrestricted inter-container and the daemon host communication
 
 To disable, it requires `iptables=true`.
 
-Defaults to undef. The default value for the Docker daemon is `true`.
+Defaults to `undef`. The default value for the Docker daemon is `true`.
 
 #### `bip`
 
@@ -1336,7 +1360,7 @@ Default value is `10G`.
 
 #### `dm_fs`
 
-The filesystem to use for the base image (xfs or ext4).
+The file system to use for the base image (xfs or ext4).
 
 Defaults to `ext4`.
 
@@ -1358,27 +1382,27 @@ Do not change this parameter after the lvm devices initialize.
 
 #### `dm_loopdatasize`
 
-Specifies the size to use when creating the loopback file for the data device which is used for the thin pool.
+Specifies the size to use when creating the loop back file for the data device which is used for the thin pool.
 
 Default size is `100G`.
 
 #### `dm_loopmetadatasize`
 
-Specifies the size to use when creating the loopback file for the metadata device which is used for the thin pool.
+Specifies the size to use when creating the loop back file for the meta data device which is used for the thin pool.
 
 Default size is `2G`.
 
 #### `dm_datadev`
 
 This is deprecated. Use `dm_thinpooldev`.
 
-A custom blockdevice to use for data for the thin pool.
+A custom block device to use for data for the thin pool.
 
 #### `dm_metadatadev`
 
 This is deprecated. Use `dm_thinpooldev`.
 
-A custom blockdevice to use for metadata for the thin pool.
+A custom block device to use for meta data for the thin pool.
 
 #### `dm_thinpooldev`
 
@@ -1470,7 +1494,7 @@ The volume group to use for docker storage.
 
 #### `storage_root_size`
 
-The maximum size of the root filesystem.
+The maximum size of the root file system.
 
 #### `storage_data_size`
 
@@ -1502,6 +1526,12 @@ Extends the pool by the specified percentage when the threshold is passed.
 
 For further explanation please refer to the[PE documentation](https://puppet.com/docs/pe/2017.3/orchestrator/running_tasks.html) or [Bolt documentation](https://puppet.com/docs/bolt/latest/bolt.html) on how to execute a task.
 
+### Functions
+
+#### `docker::sanitised_name`
+
+Sanitises string or array of strings for safe usage as container name inside scripts and commands.
+
 ## Limitations
 
 This module supports:

functions/sanitised_name.pp

@@ -0,0 +1,12 @@
+# == Function: docker::sanitised_name
+#
+# Function to sanitise container name.
+#
+# === Parameters
+#
+# [*name*]
+#   Name to sanitise
+#
+function docker::sanitised_name($name){
+  regsubst($name, '[^0-9A-Za-z.\-_]', '-', 'G')
+}

lib/facter/docker.rb

@@ -84,13 +84,13 @@ def interfaces
           docker['network'] = {}
 
           docker['network']['managed_interfaces'] = {}
-          network_list = Facter::Util::Resolution.exec('docker network ls | tail -n +2')
+          network_list = Facter::Util::Resolution.exec("#{docker_command} network ls | tail -n +2")
           docker_network_names = []
           network_list.each_line { |line| docker_network_names.push line.split[1] }
           docker_network_ids = []
           network_list.each_line { |line| docker_network_ids.push line.split[0] }
           docker_network_names.each do |network|
-            inspect = JSON.parse(Facter::Util::Resolution.exec("docker network inspect #{network}"))
+            inspect = JSON.parse(Facter::Util::Resolution.exec("#{docker_command} network inspect #{network}"))
             docker['network'][network] = inspect[0]
             network_id = docker['network'][network]['Id'][0..11]
             interfaces.each do |iface|

lib/puppet/parser/functions/docker_stack_flags.rb

@@ -5,7 +5,7 @@
 # docker_stack_flags.rb
 #
 module Puppet::Parser::Functions
-  # Transforms a hash into a string of docker swarm init flags
+  # Transforms a hash into a string of docker stack flags
   newfunction(:docker_stack_flags, type: :rvalue) do |args|
     opts = args[0] || {}
     flags = []
@@ -25,7 +25,7 @@ module Puppet::Parser::Functions
     end
 
     if opts['prune'] && opts['prune'].to_s != 'undef'
-      flags << "--prune '#{opts['prune']}'"
+      flags << '--prune'
     end
 
     if opts['with_registry_auth'] && opts['with_registry_auth'].to_s != 'undef'

manifests/registry.pp

@@ -97,7 +97,7 @@
       $server_strip = regsubst($server, '/', '_', 'G')
 
       # no - with pw_hash
-      $local_user_strip = regsubst($local_user, '-', '', 'G')
+      $local_user_strip = regsubst($local_user, '[-_]', '', 'G')
 
       $_pass_hash = $pass_hash ? {
         Undef   => pw_hash($docker_auth, 'SHA-512', $local_user_strip),

manifests/run.pp

@@ -109,6 +109,7 @@
   Variant[String,Boolean] $docker_service               = false,
   Optional[Boolean] $disable_network                    = false,
   Optional[Boolean] $privileged                         = false,
+  Optional[Boolean] $detach                             = undef,
   Variant[String,Array[String],Undef] $extra_parameters = undef,
   Optional[String] $systemd_restart                     = 'on-failure',
   Variant[String,Hash,Undef] $extra_systemd_parameters  = {},
@@ -169,6 +170,12 @@
     assert_type(Pattern[/^(no|always|on-success|on-failure|on-abnormal|on-abort|on-watchdog)$/], $systemd_restart)
   }
 
+  if $detach == undef {
+    $valid_detach = $docker::params::detach_service_in_init
+  } else {
+    $valid_detach = $detach
+  }
+
   $extra_parameters_array = any2array($extra_parameters)
   $after_array = any2array($after)
   $depends_array = any2array($depends)
@@ -204,19 +211,19 @@
     osfamily              => $::osfamily,
   })
 
-  $sanitised_title = regsubst($title, '[^0-9A-Za-z.\-_]', '-', 'G')
+  $sanitised_title = docker::sanitised_name($title)
   if empty($depends_array) {
     $sanitised_depends_array = []
   }
   else {
-    $sanitised_depends_array = regsubst($depends_array, '[^0-9A-Za-z.\-_]', '-', 'G')
+    $sanitised_depends_array = docker::sanitised_name($depends_array)
   }
 
   if empty($after_array) {
     $sanitised_after_array = []
   }
   else {
-    $sanitised_after_array = regsubst($after_array, '[^0-9A-Za-z.\-_]', '-', 'G')
+    $sanitised_after_array = docker::sanitised_name($after_array)
   }
 
   if $::osfamily == 'windows' {

manifests/stack.pp

@@ -40,7 +40,7 @@
   Optional[String] $stack_name                                   = undef,
   Optional[String] $bundle_file                                  = undef,
   Optional[Array] $compose_files                                 = undef,
-  Optional[String] $prune                                        = undef,
+  Optional[Boolean] $prune                                       = false,
   Optional[Boolean] $with_registry_auth                          = false,
   Optional[Pattern[/^always$|^changed$|^never$/]] $resolve_image = undef,
 ){