{"id":15022584,"url":"https://github.com/puppetlabs/puppetlabs-docker","last_synced_at":"2025-05-14T02:04:59.524Z","repository":{"id":38361686,"uuid":"97579583","full_name":"puppetlabs/puppetlabs-docker","owner":"puppetlabs","description":"The Puppet Docker repository","archived":false,"fork":false,"pushed_at":"2025-04-23T13:25:44.000Z","size":1752,"stargazers_count":92,"open_issues_count":67,"forks_count":320,"subscribers_count":91,"default_branch":"main","last_synced_at":"2025-04-27T20:18:16.303Z","etag":null,"topics":["hacktoberfest","module","supported"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-07-18T09:25:27.000Z","updated_at":"2025-04-25T05:20:38.000Z","dependencies_parsed_at":"2024-02-26T01:49:50.046Z","dependency_job_id":"67de1243-4e8e-4bda-acd1-25b95a2a3e16","html_url":"https://github.com/puppetlabs/puppetlabs-docker","commit_stats":{"total_commits":798,"total_committers":167,"mean_commits":4.778443113772455,"dds":0.9197994987468672,"last_synced_commit":"5a0775ba57094c5d8b2491e37bc462ebd83d6e8e"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251380925,"owners_count":21580339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","module","supported"],"created_at":"2024-09-24T19:58:08.755Z","updated_at":"2025-05-14T02:04:59.497Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Puppet Forge](https://img.shields.io/puppetforge/v/puppetlabs/docker.svg)](https://forge.puppetlabs.com/puppetlabs/docker)\n[![Puppet Forge Downloads](http://img.shields.io/puppetforge/dt/puppetlabs/docker.svg)](https://forge.puppetlabs.com/puppetlabs/docker)\n[![Puppet Forge Endorsement](https://img.shields.io/puppetforge/e/puppetlabs/docker.svg)](https://forge.puppetlabs.com/puppetlabs/docker)\n\n# Docker\n\n#### Table of Contents\n\n1. [Description](#description)\n2. [Setup](#setup)\n   * [Proxy on Windows](#proxy-on-windows)\n   * [Validating and unit testing the module](#validating-and-unit-testing-the-module)\n3. [Usage - Configuration options and additional functionality](#usage)\n   * [Images](#images)\n   * [Containers](#containers)\n   * [Networks](#networks)\n   * [Volumes](#volumes)\n   * [Compose](#compose)\n   * [Machine](#machine)\n   * [Swarm mode](#swarm-mode)\n   * [Tasks](#tasks)\n   * [Docker services](#docker-services)\n   * [Private registries](#private-registries)\n   * [Exec](#exec)\n   * [Plugins](#plugins)\n4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [License](#license)\n7. [Development - Guide for contributing to the module](#development)\n8. [Acceptance](#acceptance)\n\n\n## Description\n\nThe 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.\n\nDue 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.\n\n## Setup\n\nTo create the Docker hosted repository and install the Docker package, add a single class to the manifest file:\n\n```puppet\ninclude 'docker'\n```\n\nTo configure package sources independently and disable automatically including sources, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  use_upstream_package_source =\u003e false,\n}\n```\n\nThe 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.\n\nTo ensure the module configures the latest repositories, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  version =\u003e '17.09.0~ce-0~debian',\n}\n```\n\nUsing a version prior to 17.06, configures and installs from the old repositories:\n\n```puppet\nclass { 'docker':\n  version =\u003e '1.12.0-0~wheezy',\n}\n```\n\nDocker 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:\n\n```puppet\nclass { 'docker':\n  docker_ee                 =\u003e true,\n  docker_ee_source_location =\u003e 'https://\u003cdocker_ee_repo_url\u003e',\n  docker_ee_key_source      =\u003e 'https://\u003cdocker_ee_key_source_url\u003e',\n  docker_ee_key_id          =\u003e '\u003ckey id\u003e',\n}\n```\n\nTo install Docker EE on RHEL/CentOS:\n\n```puppet\nclass { 'docker':\n  docker_ee                 =\u003e true,\n  docker_ee_source_location =\u003e 'https://\u003cdocker_ee_repo_url\u003e',\n  docker_ee_key_source      =\u003e 'https://\u003cdocker_ee_key_source_url\u003e',\n}\n```\n\nFor 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/).\n\nFor 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:\n\n```puppet\nclass { 'docker':\n  use_upstream_package_source =\u003e false,\n  service_overrides_template  =\u003e false,\n  docker_ce_package_name      =\u003e 'docker',\n}\n```\n\nTo use the CE packages, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  use_upstream_package_source =\u003e false,\n  repo_opt                    =\u003e '',\n}\n```\n\nBy 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:\n\n```puppet\nclass { 'docker':\n  tcp_bind    =\u003e ['tcp://127.0.0.1:2375'],\n  socket_bind =\u003e 'unix:///var/run/docker.sock',\n  ip_forward  =\u003e true,\n  iptables    =\u003e true,\n  ip_masq     =\u003e true,\n  bip         =\u003e '192.168.1.1/24',\n  fixed_cidr  =\u003e '192.168.1.144/28',\n}\n```\n\nFor 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/).\n\nThe default group ownership of the Unix control socket differs based on OS. For example, on RHEL using docker-ce packages \u003e=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):\n\n```puppet\nclass {'docker':\n  socket_group    =\u003e 'root',\n  socket_override =\u003e true,\n}\n```\n\nThe socket_group parameter also takes a boolean for legacy cases where setting -G in /etc/sysconfig/docker is not desired:\n\n```puppet\ndocker::socket_group: false\n```\n\nTo 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:\n\n```puppet\ndocker::service_after_override: containerd.service\n```\n\nWhen setting up TLS, upload the related files (CA certificate, server certificate, and key) and include their paths in the manifest file:\n\n```puppet\nclass { 'docker':\n  tcp_bind   =\u003e ['tcp://0.0.0.0:2376'],\n  tls_enable =\u003e true,\n  tls_cacert =\u003e '/etc/docker/tls/ca.pem',\n  tls_cert   =\u003e '/etc/docker/tls/cert.pem',\n  tls_key    =\u003e '/etc/docker/tls/key.pem',\n}\n```\n\nTo specify which Docker rpm package to install, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  manage_package              =\u003e true,\n  use_upstream_package_source =\u003e false,\n  package_engine_name         =\u003e 'docker-engine'\n  package_source_location     =\u003e 'https://get.docker.com/rpm/1.7.0/centos-6/RPMS/x86_64/docker-engine-1.7.0-1.el6.x86_64.rpm',\n  prerequired_packages        =\u003e [ 'glibc.i686', 'glibc.x86_64', 'sqlite.i686', 'sqlite.x86_64', 'device-mapper', 'device-mapper-libs', 'device-mapper-event-libs', 'device-mapper-event' ]\n}\n```\n\nTo track the latest version of Docker, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  version =\u003e latest,\n}\n```\n\nTo install docker from a test or edge channel, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  docker_ce_channel =\u003e 'test'\n}\n```\n\nTo allocate a DNS server to the Docker daemon, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  dns =\u003e '8.8.8.8',\n}\n```\n\nTo add users to the Docker group, add the following array to the manifest file:\n\n```puppet\nclass { 'docker':\n  docker_users =\u003e ['user1', 'user2'],\n}\n```\n\nTo add daemon labels, add the following array to the manifest file:\n\n```puppet\nclass { 'docker':\n  labels =\u003e ['storage=ssd','stage=production'],\n}\n```\n\nTo pass additional parameters to the daemon, add `extra_parameters` to the manifest file:\n\n```puppet\nclass { 'docker':\n  extra_parameters =\u003e ['--experimental=true', '--metrics-addr=localhost:9323'],\n```\n\nTo uninstall docker, add the following to the manifest file:\n\n```puppet\nclass { 'docker':\n  ensure =\u003e absent\n}\n```\n\nOnly Docker EE is supported on Windows. To install docker on Windows 2016 and above, the `docker_ee` parameter must be specified:\n\n```puppet\nclass { 'docker':\n  docker_ee =\u003e true\n}\n```\n\nIf the curl package is being managed elsewhere and the curl ensure in this module is conflicting,\n it can be disabled by setting the following parameter globally or in compose / machine resources:\n\n```puppet\nclass { 'docker':\n  curl_ensure =\u003e false\n}\n```\n\n### Proxy on Windows\n\nTo 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)\nThis 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.\n\n```puppet\nwindows_env { 'HTTP_PROXY'\n  value  =\u003e 'http://1.2.3.4:80',\n  notify =\u003e Service['docker'],\n}\nwindows_env { 'HTTPS_PROXY'\n  value  =\u003e 'http://1.2.3.4:80',\n  notify =\u003e Service['docker'],\n}\nservice { 'docker'\n  ensure =\u003e 'running',\n}\n````\n\n### Validating and unit testing the module\n\nThis 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' metadata, syntax, and style.\n\nTo run all validations against this module, run the following command:\n\n```sh\npdk validate\n```\n\nTo 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).\n\nTo unit test the module, run the following command:\n\n```sh\npdk test unit\n```\n\nTo 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).\n\n## Usage\n\n### Images\n\nEach image requires a unique name; otherwise, the installation fails when a duplicate name is detected.\n\nTo install a Docker image, add the `docker::image` defined type to the manifest file:\n\n```puppet\ndocker::image { 'base': }\n```\n\nThe code above is equivalent to running the `docker pull base` command. However, it removes the default five-minute execution timeout.\n\nTo 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:\n\n```puppet\ndocker::image { 'ubuntu':\n  image_tag =\u003e 'precise'\n}\n```\n\nIncluding the `docker_file` parameter is equivalent to running the `docker build -t ubuntu - \u003c /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:\n\n```puppet\ndocker::image { 'ubuntu':\n  docker_file =\u003e '/tmp/Dockerfile'\n}\n```\n\nIncluding 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:\n\n```puppet\ndocker::image { 'ubuntu':\n  docker_dir =\u003e '/tmp/ubuntu_image'\n}\n```\n\nTo rebuild an image, subscribe to external events such as Dockerfile changes by adding the following code to the manifest file:\n\n```puppet\ndocker::image { 'ubuntu':\n  docker_file =\u003e '/tmp/Dockerfile',\n  subscribe   =\u003e File['/tmp/Dockerfile'],\n}\n\nfile { '/tmp/Dockerfile':\n  ensure =\u003e file,\n  source =\u003e 'puppet:///modules/someModule/Dockerfile',\n}\n```\n\nTo remove an image, add the following code to the manifest file:\n\n```puppet\ndocker::image { 'base':\n  ensure =\u003e 'absent'\n}\n\ndocker::image { 'ubuntu':\n  ensure    =\u003e 'absent',\n  image_tag =\u003e 'precise'\n}\n```\n\nTo configure the `docker::images` class when using Hiera, add the following code to the manifest file:\n\n```yaml\n---\n  classes:\n    - docker::images\n\ndocker::images::images:\n  ubuntu:\n    image_tag: 'precise'\n```\n\n### Containers\n\nTo launch containers, add the following code to the manifest file:\n\n```puppet\ndocker::run { 'helloworld':\n  image   =\u003e 'base',\n  command =\u003e '/bin/sh -c \"while true; do echo hello world; sleep 1; done\"',\n}\n```\n\nThis 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.\n\n`run` includes a number of optional parameters:\n\n```puppet\ndocker::run { 'helloworld':\n  image            =\u003e 'base',\n  detach           =\u003e true,\n  service_prefix   =\u003e 'docker-',\n  command          =\u003e '/bin/sh -c \"while true; do echo hello world; sleep 1; done\"',\n  ports            =\u003e ['4444', '4555'],\n  expose           =\u003e ['4666', '4777'],\n  links            =\u003e ['mysql:db'],\n  net              =\u003e ['my-user-def-net','my-user-def-net-2'],\n  disable_network  =\u003e false,\n  volumes          =\u003e ['/var/lib/couchdb', '/var/log'],\n  volumes_from     =\u003e '6446ea52fbc9',\n  memory_limit     =\u003e '10m', # (format: '\u003cnumber\u003e\u003cunit\u003e', where unit = b, k, m or g)\n  cpuset           =\u003e ['0', '3'],\n  username         =\u003e 'example',\n  hostname         =\u003e 'example.com',\n  env              =\u003e ['FOO=BAR', 'FOO2=BAR2'],\n  env_file         =\u003e ['/etc/foo', '/etc/bar'],\n  labels           =\u003e ['com.example.foo=\"true\"', 'com.example.bar=\"false\"'],\n  dns              =\u003e ['8.8.8.8', '8.8.4.4'],\n  restart_service  =\u003e true,\n  privileged       =\u003e false,\n  pull_on_start    =\u003e false,\n  before_stop      =\u003e 'echo \"So Long, and Thanks for All the Fish\"',\n  before_start     =\u003e 'echo \"Run this on the host before starting the Docker container\"',\n  after_stop       =\u003e 'echo \"container has stopped\"',\n  after_start      =\u003e 'echo \"container has started\"',\n  after            =\u003e [ 'container_b', 'mysql' ],\n  depends          =\u003e [ 'container_a', 'postgres' ],\n  stop_wait_time   =\u003e 10,\n  read_only        =\u003e false,\n  extra_parameters =\u003e [ '--restart=always' ],\n}\n```\n\nYou can specify the `ports`, `expose`, `env`, `dns`, and `volumes` values with a single string or an array.\n\nTo pull the image before it starts, specify the `pull_on_start` parameter.\n\nUse 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.\n\nTo 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.\n\nAdding the container name to the `after` parameter to specify which containers start first affects the generation of the `init.d/systemd` script.\n\nAdd 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.\n\nThe `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.\n\nBy default, automatic restarting of the service on failure is enabled by the service file for systemd based systems.\n\nIt'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.\n\nNOTE: 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.\n\nTo use an image tag, add the following code to the manifest file:\n\n```puppet\ndocker::run { 'helloworld':\n  image   =\u003e 'ubuntu:precise',\n  command =\u003e '/bin/sh -c \"while true; do echo hello world; sleep 1; done\"',\n}\n```\n\nBy 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:\n\n```puppet\ndocker::run { 'helloworld':\n  remove_container_on_start =\u003e true,\n  remove_volume_on_start    =\u003e false,\n  remove_container_on_stop  =\u003e true,\n  remove_volume_on_stop     =\u003e false,\n}\n```\n\nIf using Hiera, you can configure the `docker::run_instance` class:\n\n```yaml\n---\n  classes:\n    - docker::run_instance\n\n  docker::run_instance::instance:\n    helloworld:\n      image: 'ubuntu:precise'\n      command: '/bin/sh -c \"while true; do echo hello world; sleep 1; done\"'\n```\n\nTo remove a running container, add the following code to the manifest file. This also removes the systemd service file associated with the container.\n\n```puppet\ndocker::run { 'helloworld':\n  ensure =\u003e absent,\n}\n```\n\nTo 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.\n\n```puppet\ndocker::run { 'helloworld':\n  image                 =\u003e 'base',\n  command               =\u003e 'command',\n  health_check_cmd      =\u003e '\u003ccommand_to_execute_to_check_your_containers_health\u003e',\n  restart_on_unhealthy  =\u003e true,\n  health_check_interval =\u003e '\u003ctime between running docker healthcheck\u003e',\n```\n\nTo run command on Windows 2016 requires the `restart` parameter to be set:\n\n```puppet\ndocker::run { 'helloworld':\n  image   =\u003e 'microsoft/nanoserver',\n  command =\u003e 'ping 127.0.0.1 -t',\n  restart =\u003e 'always'\n```\n\n### Networks\n\nDocker 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:\n\n```puppet\ndocker_network { 'my-net':\n  ensure   =\u003e present,\n  driver   =\u003e 'overlay',\n  subnet   =\u003e '192.168.1.0/24',\n  gateway  =\u003e '192.168.1.1',\n  ip_range =\u003e '192.168.1.4/32',\n}\n```\n\nThe 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.\n\nTo configure the cluster store, update the `docker` class in the manifest file:\n\n```puppet\nextra_parameters =\u003e '--cluster-store=\u003cbackend\u003e://172.17.8.101:\u003cport\u003e --cluster-advertise=\u003cinterface\u003e:2376'\n```\n\nIf using Hiera, configure the `docker::networks` class in the manifest file:\n\n```yaml\n---\n  classes:\n    - docker::networks\n\ndocker::networks::networks:\n  local-docker:\n    ensure: 'present'\n    subnet: '192.168.1.0/24'\n    gateway: '192.168.1.1'\n```\n\nA defined network can be used on a `docker::run` resource with the `net` parameter.\n\n#### Windows\n\nOn Windows, only one NAT network is supported. To support multiple networks, Windows Server 2016 with KB4015217 is required. See [Windows Container Network Drivers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/container-networking/network-drivers-topologies) and [Windows Container Networking](https://docs.microsoft.com/en-us/virtualization/windowscontainers/container-networking/architecture).\n\nThe Docker daemon will create a default NAT network on the first start unless specified otherwise. To disable the network creation, use the parameter `bridge =\u003e 'none'` when installing docker.\n\n### Volumes\n\nDocker 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:\n\n```puppet\ndocker_volume { 'my-volume':\n  ensure =\u003e present,\n}\n```\n\nYou can pass additional mount options to the `local` driver. For mounting an NFS export, use:\n\n```puppet\ndocker_volume { 'nfs-volume':\n  ensure  =\u003e present,\n  driver  =\u003e 'local',\n  options =\u003e ['type=nfs','o=addr=%{custom_manager},rw','device=:/srv/blueocean']\n}\n\n```\n\nThe name value and the `ensure` parameter are required. If you do not include the `driver` value, the default `local` is used.\n\nIf using Hiera, configure the `docker::volumes` class in the manifest file:\n\n```yaml\n---\n  classes:\n    - docker::volumes\n\ndocker::volumes::volumes:\n  blueocean:\n    ensure: present\n    driver: local\n    options:\n      - ['type=nfs','o=addr=%{custom_manager},rw','device=:/srv/blueocean']\n```\n\nAvailable parameters for `options` depend on the used volume driver. For details, see\n[Using volumes](https://docs.docker.com/storage/volumes/) from the Docker manual.\n\nSome of the key advantages for using `volumes` over `bind mounts` are:\n\n* Easier to back up or migrate rather than `bind mounts` (legacy volumes).\n* Managed with Docker CLI or API (Puppet type uses the CLI commands).\n* Works on Windows and Linux.\n* Easily shared between containers.\n* Allows for store volumes on remote hosts or cloud providers.\n* Encrypt contents of volumes.\n* Add other functionality\n* New volume's contents can be pre-populated by a container.\n\nWhen 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.\n\nRunning `docker::run` with native volumes:\n\n```puppet\ndocker::run { 'helloworld':\n  image   =\u003e 'ubuntu:precise',\n  command =\u003e '/bin/sh -c \"while true; do echo hello world; sleep 1; done\"',\n  volumes =\u003e ['my-volume:/var/log'],\n}\n```\n\n### Compose\n\nDocker 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.\n\nBefore you use the `docker_compose` type, you must install the Docker Compose utility.\n\nTo install Docker Compose, add the following code to the manifest file:\n\n```puppet\nclass {'docker::compose':\n  ensure  =\u003e present,\n  version =\u003e '1.9.0',\n}\n```\n\nSet the `version` parameter to any version you need to install.\n\nThis is an example of a Compose file:\n\n```yaml\ncompose_test:\n  image: ubuntu:14.04\n  command: /bin/sh -c \"while true; do echo hello world; sleep 1; done\"\n```\n\nSpecify 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:\n\n```puppet\ndocker_compose { 'test':\n  compose_files =\u003e ['/tmp/docker-compose.yml'],\n  ensure        =\u003e present,\n}\n```\n\nPuppet automatically runs Compose because the relevant Compose services aren't running. If required, include additional options such as enabling experimental features and scaling rules.\n\nAdditionally, 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.\n\nIn 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.\n\n```puppet\ndocker_compose { 'test':\n  compose_files =\u003e ['/tmp/docker-compose.yml'],\n  ensure        =\u003e present,\n  scale         =\u003e {\n    'compose_test' =\u003e 2,\n  },\n  tmpdir        =\u003e '/usr/local/share/tmp_docker',\n  options       =\u003e ['--x-networking']\n}\n```\n\nGive options to the ```docker-compose up``` command, such as ```--remove-orphans```, by using the ```up_args``` option.\n\nTo supply multiple overide compose files add the following to the manifest file:\n\n```puppet\ndocker_compose {'test':\n  compose_files =\u003e ['server-docker-compose.yml', 'override-compose.yml'],\n}\n```\n\nPlease 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.\n\nIf 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.\n\nNOTE: this define will be deprecated in a future release in favor of the [docker stack type](REFERENCE.md#docker_stack)\n\nTo deploy the stack, add the following code to the manifest file:\n\n```puppet\n docker::stack { 'yourapp':\n   ensure        =\u003e present,\n   stack_name    =\u003e 'yourapp',\n   compose_files =\u003e ['/tmp/docker-compose.yaml'],\n   require       =\u003e [Class['docker'], File['/tmp/docker-compose.yaml']],\n}\n```\n\nTo remove the stack, set `ensure  =\u003e absent`.\n\nIf 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.\n\nTo deploy the stack, add the following code to the manifest file.\n\n```puppet\ndocker::stack { 'yourapp':\n  ensure             =\u003e present,\n  stack_name         =\u003e 'yourapp',\n  compose_files      =\u003e ['/tmp/docker-compose.yaml'],\n  with_registry_auth =\u003e true,\n  require            =\u003e [Class['docker'], File['/tmp/docker-compose.yaml']],\n}\n```\n\nTo 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](REFERENCE.md#docker_stack).\n\n```puppet\ndocker_stack { 'test':\n  compose_files =\u003e ['/tmp/docker-compose.yml'],\n  ensure        =\u003e present,\n  up_args       =\u003e '--with-registry-auth',\n}\n```\n\nTo remove the stack, set `ensure  =\u003e absent`.\n\n### Machine\n\nYou 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.\n\nFor more information on machines, see the [Docker Machines](https://docs.docker.com/machine/) documentation.\n\nThis module only installs the Docker Machine utility.\n\nTo install Docker Machine, add the following code to the manifest file:\n\n```puppet\nclass {'docker::machine':\n  ensure  =\u003e present,\n  version =\u003e '1.16.1',\n}\n```\n\nSet the `version` parameter to any version you need to install.\n\n### Swarm mode\n\nTo natively manage a cluster of Docker Engines known as a swarm, Docker Engine 1.12 includes a swarm mode.\n\nTo cluster your Docker engines, use one of the following Puppet resources:\n\n* [Swarm manager](#Swarm-manager)\n* [Swarm worker](#Swarm-worker)\n\n#### Windows\n\nTo configure swarm, Windows Server 2016 requires KB4015217 and the following firewall ports to be open on all nodes:\n\n* TCP port 2377 for cluster management communications\n* TCP and UDP port 7946 for communication among nodes\n* UDP port 4789 for overlay network traffic\n\n#### Swarm manager\n\nTo configure the swarm manager, add the following code to the manifest file:\n\n```puppet\ndocker::swarm {'cluster_manager':\n  init           =\u003e true,\n  advertise_addr =\u003e '192.168.1.1',\n  listen_addr    =\u003e '192.168.1.1',\n}\n```\n\nFor a multihomed server and to enable cluster communications between the node, include the ```advertise_addr``` and ```listen_addr``` parameters.\n\n#### Swarm worker\n\nTo configure the swarm worker, add the following code to the manifest file:\n\n```puppet\ndocker::swarm {'cluster_worker':\n  join           =\u003e true,\n  advertise_addr =\u003e '192.168.1.2',\n  listen_addr    =\u003e '192.168.1.2',\n  manager_ip     =\u003e '192.168.1.1',\n  token          =\u003e 'your_join_token'\n}\n```\n\nTo 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.\n\nTo remove a node from a cluster, add the following code to the manifest file:\n\n```puppet\ndocker::swarm {'cluster_worker':\n  ensure =\u003e absent\n}\n```\n\n### Tasks\n\nThe docker module has an example task that allows a user to initialize, join and leave a swarm.\n\n```puppet\nbolt task run docker::swarm_init listen_addr=172.17.10.101 adverstise_addr=172.17.10.101 ---nodes swarm-master --user \u003cuser\u003e --password \u003cpassword\u003e --modulepath \u003cmodule_path\u003e\n\ndocker swarm init --advertise-addr=172.17.10.101 --listen-addr=172.17.10.101\nSwarm initialized: current node (w8syk0g286vd7d9kwzt7jl44z) is now a manager.\n```\n\nTo add a worker to this swarm, run the following command:\n\n```puppet\n    docker swarm join --token SWMTKN-1-317gw63odq6w1foaw0xkibzqy34lga55aa5nbjlqekcrhg8utl-08vrg0913zken8h9vfo4t6k0t 172.17.10.101:2377\n```\n\nTo add a manager to this swarm, run `docker swarm join-token manager` and follow the instructions.\n\n```puppet\nRan on 1 node in 4.04 seconds\n```\n\n```puppet\nbolt task run docker::swarm_token node_role=worker ---nodes swarm-master --user \u003cuser\u003e --password \u003cpassword\u003e --modulepath \u003cmodule_path\u003e\n\nSWMTKN-1-317gw63odq6w1foaw0xkibzqy34lga55aa5nbjlqekcrhg8utl-08vrg0913zken8h9vfo4t6k0t\n\nRan on 1 node in 4.02 seconds\n```\n\n```puppet\nbolt task run docker::swarm_join listen_addr=172.17.10.102 adverstise_addr=172.17.10.102 token=\u003cswarm_token\u003e manager_ip=172.17.10.101:2377 --nodes swarm-02 --user root --password puppet --modulepath /tmp/modules\n\nThis node joined a swarm as a worker.\n\nRan on 1 node in 4.68 seconds\n```\n\n```puppet\nbolt task run docker::swarm_leave --nodes swarm-02 --user root --password puppet --modulepath --modulepath \u003cmodule_path\u003e\n\nNode left the swarm.\n\nRan on 1 node in 6.16 seconds\n```\n\n### Docker services\n\nDocker services create distributed applications across multiple swarm nodes. Each Docker service replicates a set of containers across the swarm.\n\nTo create a Docker service, add the following code to the manifest file:\n\n```puppet\ndocker::services {'redis':\n    create       =\u003e true,\n    service_name =\u003e 'redis',\n    image        =\u003e 'redis:latest',\n    publish      =\u003e '6379:639',\n    replicas     =\u003e '5',\n    mounts       =\u003e ['type=bind,source=/etc/my-redis.conf,target=/etc/redis/redis.conf,readonly'],\n    extra_params =\u003e ['--update-delay 1m', '--restart-window 30s'],\n    command      =\u003e ['redis-server', '--appendonly', 'yes'],\n  }\n```\n\nTo 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.\n\nTo update the service, add the following code to the manifest file:\n\n```puppet\ndocker::services {'redis_update':\n  create       =\u003e false,\n  update       =\u003e true,\n  service_name =\u003e 'redis',\n  replicas     =\u003e '3',\n}\n```\n\nTo update a service without creating a new one, include the the `update =\u003e true` and `create =\u003e false` parameters.\n\nTo scale a service, add the following code to the manifest file:\n\n```puppet\ndocker::services {'redis_scale':\n  create       =\u003e false,\n  scale        =\u003e true,\n  service_name =\u003e 'redis',\n  replicas     =\u003e '10',\n}\n```\n\nTo scale the service without creating a new one, provide the `scale =\u003e true` parameter and the `create =\u003e false` parameters. In the example above, the service is scaled to 10.\n\nTo remove a service, add the following code to the manifest file:\n\n```puppet\ndocker::services {'redis':\n  create       =\u003e false,\n  ensure       =\u003e 'absent',\n  service_name =\u003e 'redis',\n}\n```\n\nTo remove the service from a swarm, include the `ensure =\u003e absent` parameter and the `service_name` parameter.\n\n### Private registries\n\nWhen a server is not specified, images are pushed and pulled from [index.docker.io](https://index.docker.io). To qualify your image name, create a private repository without authentication.\n\nTo 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:\n\n```puppet\ndocker::registry { 'example.docker.io:5000':\n  username =\u003e 'user',\n  password =\u003e 'secret',\n  email    =\u003e 'user@example.com',\n  version  =\u003e '\u003cdocker_version\u003e'\n}\n```\n\nTo pull images from the docker store, use the following as the registry definition with your docker hub credentials.\n\n```puppet\n  docker::registry {'https://index.docker.io/v1/':\n    username =\u003e 'username',\n    password =\u003e 'password',\n  }\n```\n\nIf using hiera, configure the `docker::registry_auth` class:\n\n```yaml\ndocker::registry_auth::registries:\n  'example.docker.io:5000':\n    username: 'user1'\n    password: 'secret'\n    email: 'user1@example.io'\n    version: '\u003cdocker_version\u003e'\n```\n\nIf 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).\n\nAdd the following code to the manifest file:\n\n```puppet\ndocker::registry { 'example.docker.io:5000':\n  username =\u003e 'user',\n  password =\u003e 'secret',\n}\n```\n\nIf using hiera, configure the 'docker::registry_auth' class:\n\n```yaml\ndocker::registry_auth::registries:\n  'example.docker.io:5000':\n    username: 'user1'\n    password: 'secret'\n```\n\nTo log out of a registry, add the following code to the manifest file:\n\n```puppet\ndocker::registry { 'example.docker.io:5000':\n  ensure =\u003e 'absent',\n}\n```\n\nTo set a preferred registry mirror, add the following code to the manifest file:\n\n```puppet\nclass { 'docker':\n  registry_mirror =\u003e 'http://testmirror.io'\n}\n```\n\n### Exec\n\nWithin the context of a running container, the docker module supports arbitrary commands:\n\n```puppet\ndocker::exec { 'cron_allow_root':\n  detach      =\u003e true,\n  container   =\u003e 'mycontainer',\n  command     =\u003e '/bin/echo root \u003e\u003e /usr/lib/cron/cron.allow',\n  onlyif      =\u003e 'running',\n  tty         =\u003e true,\n  env         =\u003e ['FOO=BAR', 'FOO2=BAR2'],\n  unless      =\u003e 'grep root /usr/lib/cron/cron.allow 2\u003e/dev/null',\n  refreshonly =\u003e true,\n}\n```\n\n### Plugin\n\nThe module supports the installation of Docker plugins:\n\n```puppet\ndocker::plugin {'foo/fooplugin:latest':\n  settings =\u003e ['VAR1=test','VAR2=value']\n}\n```\n\nTo disable an active plugin:\n\n```puppet\ndocker::plugin {'foo/fooplugin:latest':\n  enabled =\u003e false,\n}\n```\n\nTo remove an active plugin:\n\n```puppet\ndocker::plugin {'foo/fooplugin:latest'\n  ensure =\u003e 'absent',\n  force_remove =\u003e true,\n}\n```\n\n## Reference\n\nFor information on classes, types, and functions, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-docker/blob/main/REFERENCE.md).\n\n## Limitations\n\nThis module supports:\n\n* EL 7 - limited support available, see note below.\n* EL 8\n* EL 9\n* Debian 8.0\n* Debian 9.0\n* Debian 10\n* Debian 11\n* Ubuntu 18.04\n* Ubuntu 20.04\n* Ubuntu 22.04\n* Windows Server 2016 (Docker Enterprise Edition only)\n* Windows Server 2019 (Docker Enterprise Edition only)\n* Windows Server 2022 (Docker Enterprise Edition only)\n\nOn 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.\n\n## License\n\nThis 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](https://opensource.org/license/agpl-v3/), [BSD-2](https://opensource.org/license/bsd-2-clause/), [BSD-3](https://opensource.org/license/bsd-3-clause/), [GPL2.0](https://opensource.org/license/gpl-2-0/), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.\n\n## Development\n\nIf you would like to contribute to this module, see the guidelines in [CONTRIBUTING.MD](https://github.com/puppetlabs/puppetlabs-docker/blob/main/CONTRIBUTING.md).\n\n## Acceptance\n\nAcceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).\nTo run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-docker/lists"}