Forge Home

systemd_docker

Sets up Docker container via systemd service units.

45,617 downloads

45,617 latest version

3.1 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.0.0 (latest)
released Feb 4th 2018
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.0.0 < 6.0.0
  • ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'kb-systemd_docker', '0.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add kb-systemd_docker
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install kb-systemd_docker --version 0.0.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

kb/systemd_docker — version 0.0.0 Feb 4th 2018

systemd_docker

table of contents

  1. overview
  2. [module description](#module description)
  3. setup – the basics of getting started with systemd_docker
  4. reference
  5. limitations

overview

This module uses systemd::service and creates unit files via that.

module description

Your scenario:

  • You got some docker hosts, but managing them via docker-swarm is overkill.
  • All your docker hosts run on the operating system systemd.
  • You've already wrote some systemd.service(5) unit files and used them.

setup

beginning with systemd_docker

systemd_docker::container { 'my_sandbox':
    image                         => {
            name                          => 'myregistry:5000/someimage',
        },
}

produces a file at /etc/systemd/system/my_sandbox.service via a systemd::service resource, that looks like this

    # name: my_sandbox
    # auth: root
    # note: managed by puppet (env:development mod:systemd_docker)
    #  vim: set filetype=dosini tabstop=30 noexpandtab:
    
    [Unit]
    Requires                    = docker.service
    After                       = docker.service
    
    [Service]
    ExecStartPre                = -/usr/bin/docker stop -t 61 my_sandbox
    ExecStartPre                = -/usr/bin/docker rm my_sandbox
    ExecStartPre                = /usr/bin/docker pull myregistry:5000/someimage
    ExecStartPre                = /usr/bin/docker run \
                                  --detach \
                                  --name my_sandbox \
                                  myregistry:5000/someimage
    ExecStart                   = /usr/bin/docker logs -f my_sandbox
    ExecStop                    = -/usr/bin/docker stop -t 61 my_sandbox
    ExecStopPost                = -/usr/bin/docker stop -t 61 my_sandbox
    TimeoutStartSec             = 360
    TimeoutStopSec              = 300
    
    [Install]
    
    # EOF

This layout might be subject to change (any major release). This module targets at stable/oldstable Debian releases.

setting up a puppet server

In our environment all docker hosts, i.e. machines each regularly running a dockerd(8), have the docker_host class included. All systemd(1) related resources serving the task docker_host are located in a subclass docker_host::systemd:

class docker_host::systemd {
    # ... preparations ... mounts ...
    
    #########################################################################
    #                                                                       #
    # C O N T A I N E R   D E F I N I T I O N S                             #
    #                                                                       #
    #########################################################################
    
    $_basic_bind_mounts            = [
            {
                host_path                     => '/etc/timezone',
                container_path                => '/etc/timezone',
                read_only                     => true,
            },
            {
                host_path                     => '/etc/localtime',
                container_path                => '/etc/localtime',
                read_only                     => true,
            },
        ]
    
    # ...
    
    # puppet master server ==================================================
    $_pp_requires_after            = [
            'docker.service',
            'docker-pp-ssl.mount',
            'docker-pp-code.mount',
        ]
    systemd_docker::container { 'dcpuppet':
        unit_description              => 'puppet master (in server) as docker container',
        # the hostname _has_ to be puppet (keyword: SSL certificates)
        hostname                      => 'puppet',
        binds                         => $_basic_bind_mounts + [
                # save accepted node's certificates:
                # otherwise the /agents/ refuse to speak with a puppetmaster
                # which knew them yesterday
                {
                    host_path                     => Systemd::Mount['docker_pp_ssl']['mount_where'],
                    container_path                => '/etc/puppetlabs/puppet/ssl/',
                    read_only                     => false,
                },
                {
                    host_path                     => Systemd::Mount['docker_pp_code']['mount_where'],
                    container_path                => '/etc/puppetlabs/code/',
                    # specify ro here! bc Systemd_docker::Container[pprepo] (below) writes to it
                    read_only                     => true,
                },
            ],
        port_bindings                 => [
                {
                    port                          => 8140,
                    protocol                      => 'tcp',
                    host_port                     => 8140,
                }
            ],
        env                           => [
                'PUPPETSERVER_JAVA_ARGS="-Xms384m -Xmx384m -XX:MaxPermSize=256m"',
            ],
        image                         => {
                name                          => 'puppet/puppetserver-standalone',
            },
        unit_requires                 => $_pp_requires_after,
        unit_after                    => $_pp_requires_after,
        install_wanted_by             => ['docker_containers.target'],
        enable_service                => true,
        # require for `systemd-analyze verify` (rdepending units have to present)
        require                       => [
                Systemd::Mount['docker_pp_ssl', 'docker_pp_code'],
                Systemd::Target['docker_containers'],
            ],
    }
    
    # ...
}

reference

types

systemd_docker::container

  • The resource title becomes the container's name.
  • Of all parameters image is mandatory.
  • The parameter names originate from the remote API reference, since they are less ambiguous (more machine readable).
  • This resource type accepts all parameters a systemd::service resource has. Following additions were made:
    • the following parameters also accept and default to default
      • unit_requires
      • unit_after
      • service_exec_start_pre
      • service_exec_start
      • service_exec_stop
    • You want to leave the above named parameters untouched (taking their default value default) in order to achieve the desired behavior.
ensure
  • abstract: whether this container is defined via a systemd.service(5) unit

  • behavior

    • 'present': the unit is defined

    • 'absent': the unit is not defined

  • note: This parameter is mentioned here for emphasis only. It is a direct relay to systemd::service (compare above statement).

  • allowed values: 'absent', 'present'

  • default: 'present'


hostname
  • abstract: corresponds to --hostname in docker-run(1)

  • allowed values: an ASCII word, or undef

  • example: 'testmachine'

  • default: undef


user
  • abstract: see --user in docker-run(1)

  • allowed values: undef or a hash with the keys 'user' and optionally 'group'. The value for 'user' and 'group' have to be either an ASCII word or a non-negative integer.

  • example: {'user' => 1000, 'group' => 'docker'}

  • default: undef


attach_stdin
  • abstract: corresponds to --attach stdin in docker-run(1)

  • allowed values: true, false, and undef

  • default: undef


attach_stdout
  • abstract: corresponds to --attach stdout in docker-run(1)

  • allowed values: true, false, and undef

  • default: undef


attach_stderr
  • abstract: corresponds to --attach stderr in docker-run(1)

  • allowed values: true, false, and undef

  • default: undef


tty
  • abstract: see --tty in docker-run(1)

  • allowed values: true, false, and undef

  • default: undef


env
  • abstract: see --env in docker-run(1)

labels
  • abstract: see --label in docker-run(1)

  • behavior

    • {'foo' => ''} results in --label abc=
  • allowed values: undef or a non-empty hash with a non-empty key string and some value string

  • default: undef


cmd
  • abstract: the trailing commands and arguments to docker-run(1)

  • behavior

    • elements of the array are joined with a space ' '
  • allowed values: undef or an array of strings

  • default: undef


entrypoint
  • abstract: see --entrypoint in docker-run(1)

  • allowed values: undef or a string

  • default: undef


image
  • abstract: corresponds to the image arguments in docker-run(1)

  • allowed values: a hash with 'name' and 'tag' as keys. 'name' has to be a non-empty string containing no blanks. 'tag' is optional and can be a non-empty string containing no blanks.

  • example: {'name' => 'registry', 'tag' => '2'}

  • default: undef


volumes
  • abstract: correpsonds to a VOLUME statement in a Dockerfile

  • allowed values: undef or a non-empty array of hashes. The hashes have to contain the keys 'volume_name' and 'container_dir'. The key 'options' is optional. The value for 'volume_name' has to be a valid volume name. The value for 'container_dir' has to be an absolute path without any blanks. The optional 'options' are a non-empty array of strings {'rw', 'ro', 'z', 'Z', 'shared', 'rshared', 'slave', 'rslave', 'private', 'rprivate', 'nocopy'}.

  • example: [{volume_name => 'foo', container_dir => '/tmp/', options => ['ro']}]

  • default: undef


working_dir
  • abstract: see --workdir in docker-run(1)

  • allowed values: undef or an absolute path to a directory without any blanks

  • example: '/'

  • default: undef


mac_address
  • abstract: see --mac-address in docker-run(1)

  • allowed values: undef or an array of six integers between 0 and 255.

  • example: [0x02, 0x42, 0xAC, 0x11, 0x00, 0x02]

  • default: undef


exposed_ports
  • abstract: see --expose in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. The hashes have port and transport_protocol as keys. port is a non-negative integer less than 65536. transport_protocol is either 'tcp', or 'udp'.

  • example: [{port => 80, transport_protocol => 'tcp'}]

  • default: undef


stop_signal
  • abstract: see --stop-signal in docker-run(1)

  • allowed values: undef or a string

  • example: 'SIGKILL'

  • default: undef


binds
  • abstract: see --volume in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. The hashes have the keys container_path and read_only. They have either host_path or volume_name as a key, too. read_only is an optional boolean. host_path, volume_name, and container_path are strings.

  • example: [{host_path => '/etc/timezone', container_path => '/etc/timezone', read_only => true}, [{host_path => '/etc/localtime', container_path => '/etc/localtime', read_only => true}]

  • default: undef


links
  • abstract: see --link in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. The hashes have the keys container_name and alias. Both are non-empty strings.

  • example: [{container_name => 'foobar2A', alias => 'foobar'}]

  • default: undef


memory
  • abstract: see --memory in docker-run(1)

  • allowed values: undef, or a non-negative integer

  • default: undef


memory_swap
  • abstract: see --memory-swap in docker-run(1)

  • allowed values: undef, or a non-negative integer, or -1 (negative one)

  • default: undef


memory_reservation
  • abstract: see --memory-reservation in docker-run(1)

  • allowed values: undef, or a non-negative integer

  • default: undef


kernel_memory
  • abstract: see --kernel-memory in docker-run(1)

  • allowed values: undef, or a non-negative integer

  • default: undef


cpu_shares
  • abstract: see --cpu-shares in docker-run(1)

  • allowed values: undef, or an integer

  • default: undef


cpu_period
  • abstract: see --cpu-period in docker-run(1)

  • allowed values: undef, or a non-negative integer

  • default: undef


cpu_quota
  • abstract: see --cpu-quota in docker-run(1)

  • allowed values: undef, or a non-negative integer

  • default: undef


cpuset_cpus
  • abstract: see --cpuset-cpus in docker-run(1)

  • allowed values: undef, or a non-empty array of non-empty integers

  • example: [0, 1]

  • default: undef


cpuset_mems
  • abstract: see --cpuset-mems in docker-run(1)

  • allowed values: undef, or a non-empty array of non-negative integer

  • example: [0, 1, 2, 3]

  • default: undef


io_maximum_bandwidth
  • abstract: see --io-maxbandwidth in docker-run(1)

  • allowed values: undef, or a non-negative integer

  • default: undef


io_maximum_iops
  • abstract: see --io-maxiops in docker-run(1)

  • acceptable values: undef, or a non-negative integer

  • default: undef


blkio_weight
  • abstract: see --blkio-weight in docker-run(1)

  • allowed values: undef, or an integer within 10 and 1000

  • default: undef


blkio_weight_device
  • abstract: see --blkio-weight-device in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes, with the keys device_path and weight, where device_path is an absolute path and weight an integer within 10 and 1000

  • example: [{device => '/dev/hdb', weight => 505}]

  • default: undef


blkio_weight_read_bps
  • abstract: see --device-read-bps in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes, with the keys device_path and rate, where device_path is an absolute path and rate a non-negative integer

  • example: [{device_path => '/dev/sda', rate => 1048576}]

  • default: undef


blkio_weight_write_bps
  • abstract: see --device-write-bps in docker-run(1)

  • allowed values: as for blkio_weight_read_bps

  • example: [{device_path => '/dev/sda', rate => 1048576}]

  • default: undef


blkio_weight_read_iops
  • abstract: see --device-read-iops in docker-run(1)

  • allowed values: as for blkio_weight_read_bps

  • example: [{device_path => '/dev/sda', rate => 1000}]

  • default: undef


blkio_weight_write_iops
  • abstract: see --device-write-iops in docker-run(1)

  • allowed values: as for blkio_weight_read_bps

  • example: [{device_path => '/dev/sda', rate => 1000}]

  • default: undef


memory_swappiness
  • abstract: see --memory-swappiness in docker-run(1)

  • allowed values: a non-negative integer up to and including 100, v or undef

  • default: undef


oom_kill_disable
  • abstract: see --oom-kill-disable in docker-run(1)

  • allowed values: false, true, and undef

  • default: undef


oom_score_adj
  • abstract: see --oom-score-adj in docker-run(1)

  • allowed values: an integer within [-1000, 1000], or undef

  • default: undef


pid_mode
  • abstract: see --pid in docker-run(1)

pids_limit
  • abstract: see --pids-limit in docker-run(1)

  • allowed values: a whole number, negative one, or undef

  • example: -1

  • default: undef


port_bindings
  • abstract: see --publish in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. Each hash has to have the keys port, protocol and host_port. port and host_port have to be non-negative integers up to and including 65535. protocol has to be either 'tcp' or 'udp'.

  • example: [{port => 80, protocol => 'tcp', host_port => 3110}]

  • default: undef


publish_all_ports
  • abstract: see --publish-all in docker-run(1)

  • behavior:

    • true: adds --publish-all to the standard docker-run(1) command

    • false, undef: nothing happens

  • allowed values: false, true, undef

  • default: undef


privileged
  • abstract: see --privileged in docker-run(1)

  • allowed values: false, true, undef

  • default: undef


readonly_rootfs
  • abstract: see --read-only in docker-run(1)

  • allowed values: true, undef, false

  • default: undef


dns
  • abstract: see --dns in docker-run(1)

  • allowed values: undef, or a non-empty array of arrays. Those arrays either contain four non-negative integers up to and including 255, or eight non-negative integers up to and including 0xFFFF.

  • example: [[0x2001, 0xe4860, 0x4860, 0, 0, 0, 0, 0x8888]]

  • default: undef


dns_options
  • abstract: see --dns-option in docker-run(1)

  • allowed values: undef, or a hash. The hash can contain the following optional flags (= their values can be undef, false, or true): debug, rotate, no_check_names, inet6, ip6_bytestring, ip6_dotint, edns0, single_request, single_request_reopen. Furthermore the optional keys ndots, timeout, attempts accept non-negative integers, where ndots' maximum is 15, the timeout maximum is 30, and attempts maximum is 5. (Limitations and available options taken from GNU/Linux resolver implementation)

  • example: {ndots => 1, timeout => 4, attempts => 9, rotate => true}

  • default: undef


dns_search
  • abstract: see --dns-search in docker-run(1)

  • allowed values: a non-empty array of non-empty strings, or undef

  • example: ['docker.cs.vniuersity.edu']

  • default: undef


extra_hosts
  • abstract: see --add-host in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. Those hashes have to have the keys hostname and ip, where hostname's value is a non-empty string, and ip's value is either an array of four non-negative integers up to and including 255, or an array of eight non-negative integers up to and including 0xFFFF.

  • example: [{hostname => 'puppet', ip => [10, 2, 4, 142]}]

  • default value: undef


volumes_from
  • abstract: see --volumes-from in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. Those hashes have to have the key container_name its value is a non-empty string. Another key read is optional and can take the values 'ro' and 'rw'.

  • example: [{container_name => 'foo', read => 'ro'}]

  • default: undef


cap_add
  • abstract: see --cap-add in docker-run(1)

cap_drop
  • abstract: see --cap-drop in docker-run(1)

group_add
  • abstract: see --group-add in docker-run(1)

  • acceptable values: a non-empty array of non-empty strings, or undef

  • example: ['audio', 'video']

  • default: undef


restart_policy
  • abstract: see --restart in docker-run(1)

  • allowed values: undef, or a hash. The hash to have the key name. Its values can be 'no', 'on-failure', 'always', or 'unless-stopped'. If name's value is 'on-failure' there is an additional key available named maximum_retry_count. It can be left undef, or can be assigned with a non-negative integer.

  • example: {name => 'on-failure', maximum_retry_count => 4}

  • default: undef


auto_remove
  • abstract: see --rm in docker-run(1)

  • allowed values: false, true, undef

  • default: undef


userns_mode
  • abstract: see --userns in docker-run(1)

  • allowed values: 'host', undef

  • default: undef


network_mode
  • abstract: see --network in docker-run(1)

  • allowed values: a non-empty string, or undef

  • default: undef


devices
  • abstract: see --device in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. Those hashes have to have the keys path_on_host, path_in_container, and cgroup_permissions. The former two have to be non-empty strings. The latter can be a string 'rwm' (in that order), where each character's optional but one, or may remain undef.

  • example: [{path_on_host => '/dev/sdc', path_in_container => '/dev/xvdc', cgroup_permissions => 'r'}]

  • default: undef


ulimits
  • abstract: see --ulimit in docker-run(1)

  • allowed values: undef, or a non-empty array of hashes. The hashes have to have the keys name, soft_limit and hard_limit. The former one has to be a non-empty string. The latter two have to be non-negative integers.

  • example: [{name => 'nofile', soft_limit => 32768, hard_limit => 65535}]

  • default: undef


sysctls
  • abstract: see --sysctl in docker-run(1)

  • allowed values: undef, or a non-empty hash its keys and values are non-empty strings.

  • example: {'net.ipv4.ip_forward' => '1', 'net.ipv6.conf.all.forwarding' => '1'}

  • default: undef


security_opt
  • abstract: see --security-opt in docker-run(1)

  • allowed values: undef, or a non-empty array of non-empty strings

  • example: ['apparmor=unconfined']

  • default: undef


storage_opt
  • abstract: reserved identifier, not implemented

log_config
  • abstract: reserved identifier, not implemented

cgroup_parent
  • abstract: see --cgroup-parent in docker-run(1)

  • allowed values: undef, or a non-empty string

  • default: undef


volume_driver
  • abstract: see --volume-driver in docker-run(1)

  • allowed values: undef, or a non-empty string

  • default: undef


shm_size
  • abstract: see --shm-size in docker-run(1)

  • allowed values: undef, or a positive integer

  • default: undef

limitations