- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with docker_systemd
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
- Release Notes
This module creates systemd services to run Docker containers.
This module provides comprehensive systemd service configuration to manage the running of Docker containers. An important feature it provides is it can configure systemd dependencies so that Docker containers are started in the correct order, which is needed for sharing volumes or establishing links between containers. This is needed to support more sophisticated usage patterns, such as data volume containers.
This module generates systemd unit files in /etc/systemd/system
. These unit
files have a prefix of "docker-", followed by the name of the container.
When docker_systemd services are started, the resulting Docker containers will be stored using Docker's storage driver.
If any Docker images are pulled as a result of running a Docker container, those images will be stored using Docker's storage driver.
This module does not install Docker for you. Plenty of ways to install Docker already exist, so this module does not add yet another way to do it.
This module does not build Docker images. If you need to build images, the
puppetlabs/docker_platform
module does that just fine.
This module requires Docker to be installed and running before any systemd container services are run.
docker_systemd::container
configures a standalone Docker container to run
under systemd.
docker_systemd::container { "httpd":
image => "httpd",
publish => ["80:80/tcp"],
link => ["db:db"],
volume => ["/var/www/html:/var/www/html:ro"]
}
In the above example, a systemd service is configured to run the httpd container, and it publishes port 80 when it runs. The container starts immediately and is configured to start on boot. The container name is based on the title and is named "httpd". The systemd service is also based on the title and is named "docker-httpd.service".
The following options are available for docker_systemd::container
:
-
ensure
: Takes anyensure
value accepted by theService
resource type (Defaultrunning
). -
enable
: Takes anyenable
value accepted by theService
resource type (Defaulttrue
). -
hostname
: The hostname associated with the container. -
image
: The name of the docker image to use. -
privileged
: If set to 'true' give extended privileges to this container. -
pull_image
: Always pull image before starting the container. (Defaultfalse
) -
command
: Command and arguments to be run by the container. -
depends
: Dependencies on other systemd docker units which need to be started before this one. (List) -
volume
: Volumes to be used by this container. (List) -
volumes_from
: Containers which this container mounts volumes from. (List) -
link
: Containers which this container links to. (List) -
log_driver
: Set log driver to use. -
log_opt
: Set options for the log driver. (List) -
memory
: Memory limit. -
memory_reservation
: Memory soft limit. -
memory_swap
: Swap limit equal to memory plus swap: '-1' to enable unlimited swap. -
memory_swappiness
: Tune container memory swappiness (0 to 100). -
net
: Set network mode. -
publish
: Ports which should be published by this container. (List) -
entrypoint
: Run this container with a different entrypoint. -
env
: Set environment variables in the container. (List) -
env_file
: Use environment file in the container. (List) -
systemd_env_file
: Path to a systemd environment file to use. -
systemd_depends
: Dependencies on other systemd targets. (List)
docker_systemd::exec
allows a docker exec
command to be invoked within a
docker_systemd::container
. No additional containers are created for an
exec
service, and it depends on the container which it runs against.
docker_systemd::exec { "httpd":
command => "/bin/ls"
}
The above example configures /bin/ls
to be run from within the container of
the "docker-httpd" service. The systemd service for this is named
"docker-httpd-exec.service" and it depends on "docker-httpd.service".
The following options are available for docker_systemd::exec
:
-
command
: Command and arguments to be run by the container. -
container
: Identifier of the container if different than the title.
docker_systemd::data_volume_container
configures a systemd unit for a data
volume container. This type of container is only run once at system startup,
and is run using an entrypoint of /bin/true
. The main purpose of such a
container is to provide volume storage to other containers.
docker_systemd::data_volume_container { "httpd-data":
image => "httpd"
}
The above example creates a data volume container named "httpd-data" from the "httpd" image. The systemd service for this is named "docker-httpd-data.service".
The following options are available for
docker_systemd::data_volume_container
:
-
image
: The name of the docker image to use. -
pull_image
: Always pull image before starting the container. (Defaultfalse
) -
systemd_env_file
: Path to a systemd environment file to use. -
systemd_depends
: Dependencies on other systemd targets. (List)
For more information about the data volume container pattern, see the official Docker documentation for Creating and mounting a data volume container.
This module targets Red Hat Linux systems capable of running Docker:
- RHEL 7
- CentOS 7
- Fedora 20+
Issues and pull requests are welcome! Send those to: https://github.com/ajsmith/puppet-docker_systemd
- Add support for memory options on containers:
--memory
--memory-reservation
--memory-swap
--memory-swappiness
- Fix ordering issue introduced in v0.4.1.
- Re-release to fix a build issue in the last release.
- Notify container services after systemd unit configurations are reloaded.
- Add support for declaring general systemd dependencies.
- Add support for additional options on containers:
--hostname
--log-driver
--log-opt
--net
--privileged
- Add support for additional options on data volume containers:
--hostname
--privileged
- Improve error handling for data volume container services.
- Documentation updates.
- Automatically invoke 'systemctl daemon-reload' when unit files are updated.
- Add support for systemd environment files.
- Add option to always pull image before running containers.
- Add
--volume
option for containers.
- Add
--env
and--env-file
configuration options for containers.
- Add Puppet version compatibility to metadata.
- Fixed a bug that prevented a container image from being configured.
- Added rspec tests for defined resource types.
- OS support info fixes.
- Metadata updates.
- Initial release.