systemd_docker

Sets up Docker container via systemd service units.

Kai Burghardt

kb

27,513 downloads

27,513 latest version

3.1 quality score

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
  • Debian
    ,
    Ubuntu

Start using this module

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