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

• systemd-networkd and docker
• general compatibility
• It's somewhat likely you'd like to set up your container somehow different.