simp_docker

partner
A SIMP helper module for puppetlabs/docker

SIMP

simp

6,335 downloads

3,185 latest version

5.0 quality score

Version information

  • 0.2.1 (latest)
  • 0.2.0
  • 0.1.1
  • 0.1.0
released Mar 18th 2019
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.4 < 6.0.0
  • CentOS
    ,
    RedHat

Start using this module

Documentation

simp/simp_docker — version 0.2.1 Mar 18th 2019

License CII Best Practices Puppet Forge Puppet Forge Downloads Build Status

Table of Contents

  1. Description
  2. Setup - The basics of getting started with simp_docker
  3. Usage - Configuration options and additional functionality
  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

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:

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.