simp_docker

Table of Contents

1. Description
2. Setup - The basics of getting started with simp_docker
   • What simp_docker affects
   • Setup requirements
   • Beginning with simp_docker
3. Usage - Configuration options and additional functionality
   • docker::run - Running containers as a systemd service
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module
   • Acceptance Tests - Beaker env variables

Description

simp_docker is a helper module to get Docker up and running on SIMP systems. The goal of this project is to not get in the way of anyone experienced with Docker, and to not set up Docker in a way that would not make sense to anyone using Docker on other platforms.

It currently supports installing Docker through the RedHat-provided docker package (recommended) or the Docker-provided docker-ce package.

The meat of this module is to provide SIMP-specific defaults for the very good upstream puppetlabs/docker module.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they may be submitted to our bug tracker.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
• If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the parameters in simp/simp_options for details.

Setup

What simp_docker affects

This module will:

• Install docker and related packages
• Manage the docker service

The puppetlabs/docker module can:

• Manage images available on the local machine
• Run containers as systemd services
• Manage registries available on the local machine
• A bunch of other cool stuff

NOTE: This module only supports EL7. It does not support EL6.

Known Issues

The RedHat docker executable uses dockerroot as the docker_group. In simp_docker, a class delaration is used to configure the puppetlabs docker module. This declaration sets the value for the docker::docker_group variable to dockerroot to work with RedHats implementation of docker. How ever, the puppetlabs docker::run module does not have access to this setting and does not allow the user to set the docker_group. It mistakenly sets the runtime group to docker.

To work around this issue the simp_docker profile module sets the local system groups docker and dockerroot to the same group id on RedHat family systems.

See https://github.com/puppetlabs/puppetlabs-docker/issues/321

Setup Requirements

If you are seeing networking issues with containers running on hosts using this module and SIMP's iptables module, set the following setting in hieradata:

---
iptables::ignore:
  - DOCKER
  - docker

This snippet tells the simp/iptables module to ignore rules written to iptables by the Docker daemon. Otherwise, the iptables module will remove them.

See the acceptance tests for this project for an example of how to set up this module for use in a full SIMP environment.

Beginning with simp_docker

To get started with simp_docker, include the class and choose the version of Docker that should be used.

For RedHat-provided Docker (docker from CentOS-Extras):

include 'simp_docker'

For Docker Community Edition or Docker-provided docker (docker-ce):

class { 'simp_docker':
  release_type => 'ce'
}

Usage

The default parameters for each release_type are kept in module data. If these are wrong or need to be updated, please file an issue.

If more advanced settings are required, all options set in the options hash will be passed to the puppetlabs/docker docker class. Here is an example setting up Docker using a TCP socket:

class { 'simp_docker':
  # TODO build this into the module using simp_options::pki :)
  options => {
    tcp_bind    => ['tcp://0.0.0.0:4243'],
    socket_bind => 'unix:///var/run/docker.sock',
    tls_enable  => true,
    tls_cacert  => '/etc/pki/simp/x509/cacerts/cacerts.pem',
    tls_cert    => '/etc/pki/simp/x509/private/<hostname>.pem',
    tls_key     => '/etc/pki/simp/x509/public/<hostname>.pub',
  }
}

docker::run

An example snippet that runs a container as a systemd service:

docker::run { 'stock_nginx':
  image => 'nginx',
  ports => ['80:80'],
}

This will create a service called docker-stock_nginx which contains a docker run command similar to the following:

docker run --net bridge -m 0b -p 80:80 --name stock_nginx nginx

Reference

Please refer to the inline documentation within each source file, or to the module's generated YARD documentation for reference material. The upstream puppetlabs/docker documentation is also a great resource.

Limitations

This module only supports EL7. It does not support EL6.

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the metadata.json file for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle install
bundle exec rake beaker:suites

Please refer to the SIMP Beaker Helpers documentation for more information.

• Thu Mar 07 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.2.1-0

• Update the upper bound of stdlib to < 6.0.0
• Update a URL in the README.md
• Update to puppetlabs-docker 3.4.0

• Fri Nov 09 2018 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.0-0

• Added a workaround to a long standing bug in puppetlabs/beaker that adds a 'docker' user with the same gid as 'dockerroot' if it doesn't exist.

• Mon Sep 10 2018 Liz Nemsick lnemsick.simp@gmail.com - 0.2.0-0

• Update Hiera 4 to Hiera 5.
• Update badges in README.md

• Wed May 09 2018 Nick Miller nick.miller@onyxpoint.com - 0.1.1

• Update to puppetlabs/docker 1.1.0
  • $selinux_enabled changed from taking string to only taking booleans, breaking the hiera interpolation trick that was used to set that parameter to the selinux status of the system.

• Wed Jan 31 2018 Nick Miller nick.miller@onyxpoint.com - 0.1.0

• Update to puppetlabs/docker 1.0.5
  • Remove deprecated manage_epel parameter
• Removed $iptables_docker_chain by default
  • The simp/iptables module has been updated so that this is not needed

• Fri Dec 29 2017 Trevor Vaughan tvaughan@onyxpoint.com - 0.1.0

• Ensure that the docker_group and socket_group options are the same by default for the 'redhat' release type

• Mon Nov 27 2017 Nick Miller nick.miller@onyxpoint.com - 0.1.0

• Wrap puppetlabs/docker to:
  • Provide SIMP defaults
  • Add ease-of-use for using different distributions of Docker
• Document how to set up simp/iptables to ignore docker-generated rules