{"id":15013911,"url":"https://github.com/garethr/garethr-docker","last_synced_at":"2025-04-12T14:58:02.684Z","repository":{"id":8339906,"uuid":"9897045","full_name":"garethr/garethr-docker","owner":"garethr","description":"Puppet module for managing docker","archived":false,"fork":false,"pushed_at":"2020-11-29T12:37:53.000Z","size":1208,"stargazers_count":397,"open_issues_count":178,"forks_count":525,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-04-03T14:11:43.660Z","etag":null,"topics":["docker","puppet"],"latest_commit_sha":null,"homepage":null,"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/garethr.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":null,"security":null,"support":null}},"created_at":"2013-05-06T21:13:55.000Z","updated_at":"2024-08-14T15:27:06.000Z","dependencies_parsed_at":"2022-08-07T03:00:12.152Z","dependency_job_id":null,"html_url":"https://github.com/garethr/garethr-docker","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garethr%2Fgarethr-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garethr%2Fgarethr-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garethr%2Fgarethr-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garethr%2Fgarethr-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/garethr","download_url":"https://codeload.github.com/garethr/garethr-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248358963,"owners_count":21090453,"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":["docker","puppet"],"created_at":"2024-09-24T19:44:55.821Z","updated_at":"2025-04-12T14:58:02.662Z","avatar_url":"https://github.com/garethr.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Puppet module for installing, configuring and managing\n[Docker](https://github.com/docker/docker) from the [official repository](https://docs.docker.com/installation/) or alternatively from [EPEL on RedHat](https://docs.docker.io/en/latest/installation/rhel/) based distributions.\n\n[![Puppet\nForge](https://img.shields.io/puppetforge/v/garethr/docker.svg)](https://forge.puppetlabs.com/garethr/docker) [![Build\nStatus](https://secure.travis-ci.org/garethr/garethr-docker.png)](https://travis-ci.org/garethr/garethr-docker) [![Documentation\nStatus](https://img.shields.io/badge/docs-puppet--strings-lightgrey.svg)](https://garethr.github.io/garethr-docker) [![Puppet Forge\nDownloads](https://img.shields.io/puppetforge/dt/garethr/docker.svg)](https://forge.puppetlabs.com/garethr/docker) [![Puppet Forge\nEndorsement](https://img.shields.io/puppetforge/e/garethr/docker.svg)](https://forge.puppetlabs.com/garethr/docker)\n\n\n## Support\n\nThis module is currently tested on:\n\n* Debian 8.0\n* Debian 7.8\n* Ubuntu 12.04\n* Ubuntu 14.04\n* Centos 7.0\n* Centos 6.6\n\nIt may work on other distros and additional operating systems will be\nsupported in the future. It's definitely been used with the following\ntoo:\n\n* Archlinux\n* Amazon Linux\n* Fedora\n* Gentoo\n\n## Examples\n\n* [Launch vNext app in Docker using Puppet](https://github.com/garethr/puppet-docker-vnext-example)\n  This example contains a fairly simple example using Vagrant to launch a\n  Linux virtual machine, then Puppet to install Docker, build an image and\n  run a container. For added spice the container runs a ASP.NET vNext\n  application.\n* [Multihost containers connected with\n  Consul](https://github.com/garethr/puppet-docker-example)\n  Launch multiple hosts running simple application containers and\n  connect them together using Nginx updated by Consul and Puppet.\n* [Configure Docker Swarm using\n  Puppet](https://github.com/garethr/puppet-docker-swarm-example)\n  Build a cluster of hosts running Docker Swarm configured by Puppet.\n\n## Usage\n\nThe module includes a single class:\n\n```puppet\ninclude 'docker'\n```\n\nBy default this sets up the docker hosted repository if necessary for your OS\nand installs the docker package and on Ubuntu, any required Kernel extensions.\n\nIf you don't want this module to mess about with your Kernel then you can disable\nthis feature like so. It is only enabled (and supported) by default on Ubuntu:\n\n```puppet\nclass { 'docker':\n  manage_kernel =\u003e false,\n}\n```\n\nIf you want to configure your package sources independently, inform this module\nto not auto-include upstream sources (This is already disabled on Archlinux\nas there is no further upstream):\n\n```puppet\nclass { 'docker':\n  use_upstream_package_source =\u003e false,\n}\n```\n\nDocker recently [launched new official\nrepositories](https://blog.docker.com/2015/07/new-apt-and-yum-repos/#comment-247448)\nwhich are now the default for the module from version 5. If you want to\nstick with the old repositories you can do so with the following:\n\n```puppet\nclass { 'docker':\n  package_name =\u003e 'lxc-docker',\n  package_source_location =\u003e 'https://get.docker.com/ubuntu',\n  package_key_source =\u003e 'https://get.docker.com/gpg',\n  package_key =\u003e '36A1D7869245C8950F966E92D8576A8BA88D21E',\n  package_release =\u003e 'docker',\n}\n```\n\nDocker also provide a [commercially\nsupported](https://docs.docker.com/docker-trusted-registry/install/install-csengine/)\nversion of the Docker Engine, called Docker CS, available from a separate repository.\nThis can be installed with the module using the following:\n\n```puppet\nclass { 'docker':\n  docker_cs =\u003e true,\n}\n```\n\nThe module also now uses the upstream repositories by default for RHEL\nbased distros, including Fedora. If you want to stick with the distro packages\nyou should use the following:\n\n```puppet\nclass { 'docker':\n  use_upstream_package_source =\u003e false,\n  package_name =\u003e 'docker',\n}\n```\n\nBy default the docker daemon will bind to a unix socket at\n/var/run/docker.sock. This can be changed, as well as binding to a tcp\nsocket if required.\n\n```puppet\nclass { 'docker':\n  tcp_bind        =\u003e ['tcp://127.0.0.1:4243','tcp://10.0.0.1:4243'],\n  socket_bind     =\u003e 'unix:///var/run/docker.sock',\n  ip_forward      =\u003e true,\n  iptables        =\u003e true,\n  ip_masq         =\u003e true,\n  bridge          =\u003e br0,\n  fixed_cidr      =\u003e '10.20.1.0/24',\n  default_gateway =\u003e '10.20.0.1',\n}\n```\n\nFor TLS setup you should upload related files (such as CA certificate, server certificate and key) and use their paths in manifest\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\nUnless specified this installs the latest version of docker from the docker\nrepository on first run. However if you want to specify a specific version you\ncan do so, unless you are using Archlinux which only supports the latest release.\nNote that this relies on a package with that version existing in the reposiroty.\n\n```puppet\nclass { 'docker':\n  version =\u003e '0.5.5',\n}\n```\n\nAnd if you want to install a specific rpm package of docker you can do so:\n\n```puppet\nclass { 'docker' :\n  manage_package              =\u003e true,\n  use_upstream_package_source =\u003e false,\n  package_name                =\u003e 'docker-engine'\n  package_source              =\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\nAnd if you want to track the latest version you can do so:\n\n```puppet\nclass { 'docker':\n  version =\u003e 'latest',\n}\n```\n\nIn some cases dns resolution won't work well in the container unless you give a dns server to the docker daemon like this:\n\n```puppet\nclass { 'docker':\n  dns =\u003e '8.8.8.8',\n}\n```\n\nTo add users to the Docker group you can pass an array like this:\n\n```puppet\nclass { 'docker':\n  docker_users =\u003e ['user1', 'user2'],\n}\n```\n\nTo add daemon labels you can pass an array like this:\n\n```puppet\nclass { 'docker':\n  labels =\u003e ['storage=ssd','stage=production'],\n}\n```\n\nThe class contains lots of other options, please see the inline code\ndocumentation for the full options.\n\n### Images\n\nThe next step is probably to install a docker image; for this we have a defined type which can be used like so:\n\n```puppet\ndocker::image { 'base': }\n```\n\nThis is equivalent to running `docker pull base`. This is downloading a large binary so on first run can take a while. For that reason this define turns off the default 5 minute timeout for exec. Takes an optional parameter for installing image tags that is the equivalent to running `docker pull -t=\"precise\" ubuntu`:\n\n```puppet\ndocker::image { 'ubuntu':\n  image_tag =\u003e 'precise'\n}\n```\n\nNote: images will only install if an image of that name does not already exist.\n\nA images can also be added/build from a dockerfile with the `docker_file` property, this equivalent to running `docker build -t ubuntu - \u003c /tmp/Dockerfile`\n\n```puppet\ndocker::image { 'ubuntu':\n  docker_file =\u003e '/tmp/Dockerfile'\n}\n```\n\nImages can also be added/build from a directory containing a dockerfile with the `docker_dir` property, this is equivalent to running `docker build -t ubuntu /tmp/ubuntu_image`\n\n```puppet\ndocker::image { 'ubuntu':\n  docker_dir =\u003e '/tmp/ubuntu_image'\n}\n```\n\nYou can trigger a rebuild of the image by subscribing to external events like Dockerfile changes:\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\nYou can also remove images you no longer need with:\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\nIf using hiera, there's a `docker::images` class you can configure, for example:\n\n```yaml\n---\n  classes:\n    - docker::images\n\ndocker::images::images:\n  ubuntu:\n    image_tag: 'precise'\n```\n\n\n### Containers\n\nNow you have an image you can launch containers:\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 following:\n\n    docker run -d base /bin/sh -c \"while true; do echo hello world; sleep 1; done\"\n\nThis will launch a Docker container managed by the local init system.\n\nRun also takes a number of optional parameters:\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  ports           =\u003e ['4444', '4555'],\n  expose          =\u003e ['4666', '4777'],\n  links           =\u003e ['mysql:db'],\n  net             =\u003e 'my-user-def-net',\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  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           =\u003e [ 'container_b', 'mysql' ],\n  depends         =\u003e [ 'container_a', 'postgres' ],\n  extra_parameters =\u003e [ '--restart=always' ],\n}\n```\n\nPorts, expose, env, env_file, dns and volumes can be set with either a single string or as above with an array of values.\n\nSpecifying `pull_on_start` will pull the image before each time it is started.\n\nSpecifying `before_stop` will execute a command before stopping the container.\n\nThe `after` option allows expressing containers that must be started before. This affects the generation of the init.d/systemd script.\n\nThe `depends` option allows expressing container dependencies. The depended container will be started before this container(s), and this container will be stopped before the depended container(s). This affects the generation of the init.d/systemd script. You can use `depend_services` to specify dependency for generic services (non-docker) that should be started before this container.\n\n`extra_parameters` : 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.\n\nThe service file created for systemd based systems enables automatic restarting of the service on failure by default.\n\nTo use an image tag just append the tag name to the image name separated by a semicolon:\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 the generated init scripts will remove the container (but not\nany associated volumes) when the service is stopped or started. This\nbehaviour can be modified using the following, with defaults shown:\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, there's a `docker::run_instance` class you can configure, for example:\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\n### Networks\n\nAs of Docker 1.9.x, Docker has official support for networks. The module\nnow exposes a type, `docker_network`, used to manage those. This works\nlike:\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\nOnly the name is required, along with an ensure value. If you don't pass\na driver Docker network will use the default bridge. Note that some\nnetworks require the Docker daemon to be configured to use them, for\ninstance for the overlay network you'll need a cluster store configured.\nYou can do that on the `docker` class like so:\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, there's a `docker::networks` class you can configure, for example:\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```\nThe network defined can then be used on a `docker::run` resource with the `net` parameter.\n### Compose\n\nDocker Compose allows for describing a set of containers in a simple\nYAML format, and then running a command to build and run those\ncontainers. The `docker_compose` type included in the module allows for\nusing Puppet to run Compose. This means you can have Puppet remediate\nany issues and make sure reality matches the model in your Compose\nfile.\n\nBefore using the docker_compose type make sure the docker-compose utility is installed:\n\n```puppet\nclass {'docker::compose': \n  ensure =\u003e present,\n}\n```\n\nHere's an example. Given the following 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\nThat could be added to the machine you're running Puppet using a `file`\nresource or any other means.\n\nThen define a `docker_compose` resource pointing at the Compose file\nlike so:\n\n```puppet\ndocker_compose { '/tmp/docker-compose.yml':\n  ensure  =\u003e present,\n}\n```\n\nNow when Puppet runs it will automatically run Compose is required,\nfor example because the relevant Compose services aren't running.\n\nYou can also pass additional options (for example to enable experimental\nfeatures) as well as provide scaling rules. The following example\nrequests 2 containers be running for example. Puppet will now run\nCompose if the number of containers for a given service don't match the\nprovided scale values.\n\n```puppet\ndocker_compose { '/tmp/docker-compose.yml':\n  ensure  =\u003e present,\n  scale   =\u003e {\n    'compose_test' =\u003e 2,\n  },\n  options =\u003e '--x-networking'\n}\n```\n\nIt is also possible to give options to the ```docker-compose up``` command\nsuch as ```--remove-orphans``` using the ```up_args``` option.\n\n### Swarm mode\nDocker Engine 1.12 includes swarm mode for natively managing a cluster of Docker Engines called a swarm. You can now cluster your Docker engines with the one of the following Puppet resources.\nFor a swarm manager:\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```\nIn the above example we have configured a swarm manager with ```init =\u003e true``` then set the ```advertise_addr``` and ```listen_addr```. Both the ```advertise_addr``` and ```listen_addr``` are set for the cluster communications between nodes. Please note the ```advertise_addr``` and ```listen_addr``` must be set for a multihomed server. For more advance flags to configure raft snapshots etc please read the readme at the top of the ```docker::swarm``` class.  \n\nFor a swarm worker:\n```puppet\ndocker::swarm {'cluster_worker':\njoin           =\u003e true,\nadvertise_addr =\u003e '192.168.1.2',\nlisten_addr    =\u003e '192.168.1.2,\nmanager_ip     =\u003e '192.168.1.1',\ntoken          =\u003e 'SWMTKN-1-2lw8bnr57qsu74d6iq2q1wr2wq2i334g7425dfr3zucimvh4bl-2vwn6gysbdj605l37c61iixie'\n} \n```\n\nIn this example we have joined a node to the cluster using ```join =\u003e true```. For a worker node or second manager you need to pass a current managers ip address ```manager_ip =\u003e '192.168.1.1'```\nThe other important configuration is the token you pass to the manager. The token will define the nodes role in the cluster, as there will be a token to create another manager and a different token for the worker nodes.\n\nTo remove a node from a cluster use the following:\n```puppet\ndocker::swarm {'cluster_worker':\nensure =\u003e absent\n}\n```\n### Docker services\nDocker services allow to create distributed applications across multiple swarm nodes. A service is a set of containers that are replicated across your swarm.\nTo configure a service with Puppet code please see the following examples\n\nTo create a service\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    extra_params =\u003e ['--update-delay 1m', '--restart-window 30s']\n  }\n```\nIn this example we are creating a service called `redis`, as it is a new service we have set `create =\u003e true`. The `service_name` resource is the name which Docker knows the service as. The `image` resource is the image you want to base the service off, `publish` is the ports that want exposed to the outside world for the service to be consumed, `replicas` sets the amount of tasks (containers) that you want running in the service, `extra_params` allows you to configure any of the other flags that Docker gives you when you create a service for more info see `docker service create --help`\n\nTo update the service\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\nIn this example we have taken the service that we created earlier `redis` set the `create =\u003e false` and this time added `update =\u003e true`. We then decleared the service name `redis` we have then updated the servce to have only 3 replicas, not 5. The `extra_params` resource is also available in the update class.\n\nTo scale a service\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```\nIn this example we have used the command `docker service scale` with Puppet code. We have taken our service `redis` set the `create =\u003e false` and `scale =\u003e true` When using scale you have to declare your `service_name` then the number of replicas that you want. In this example we are going to scale to `10`\n\nTo remove a service\n```puppet\ndocker::services {'redis':\n  ensure =\u003e 'absent',\n  service_name =\u003e 'redis',\n}\n```\nTo remove a a service from your swarm just set `ensure =\u003e absent` and the service_name of your service.\n\n### Private registries\nBy default images will be pushed and pulled from [index.docker.io](https://index.docker.io) unless you've specified a server. If you have your own private registry without authentication, you can fully qualify your image name. If your private registry requires authentication you may configure a registry:\n\n```puppet\ndocker::registry { 'example.docker.io:5000':\n  username =\u003e 'user',\n  password =\u003e 'secret',\n  email    =\u003e 'user@example.com',\n}\n```\n\nYou can logout of a registry if it is no longer required.\n\n```puppet\ndocker::registry { 'example.docker.io:5000':\n  ensure =\u003e 'absent',\n}\n```\n\nIf using hiera, there's a docker::registry_auth class you can configure, for example:\n\n```yaml\ndocker::registry_auth::registries:\n  'example.docker.io:5000':\n    username: 'user1'\n    password: 'secret'\n    email: 'user1@example.io'\n```\n\n### Exec\n\nDocker also supports running arbitrary commands within the context of a\nrunning container. And now so does the Puppet module.\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  tty          =\u003e true,\n  unless       =\u003e 'grep root /usr/lib/cron/cron.allow 2\u003e/dev/null',\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarethr%2Fgarethr-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgarethr%2Fgarethr-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarethr%2Fgarethr-docker/lists"}