salt.modules.dockercompose

Module to import docker-compose via saltstack

New in version 2016.3.0.

maintainer:

Jean Praloran <jeanpralo@gmail.com>

maturity:

new

depends:

docker-compose>=1.5 or python_on_whales

platform:

all

Introduction

This module allows one to deal with docker-compose file in a directory.

This is a first version only, the following commands are missing at the moment but will be built later on if the community is interested in this module:

• run

• logs

• port

• scale

Installation Prerequisites

The module supports two backends:

• The legacy compose (docker-compose v1) Python library. This is the default backend on 3006.x/3007.x/3008.x for backwards compatibility.

• The python_on_whales library which drives docker compose (v2, the Docker CLI plugin). This backend is opt-in and is selected only when the minion configuration sets dockercompose:use_python_on_whales: True and the python_on_whales package is importable.

Example minion config to enable the v2 backend:

dockercompose:
  use_python_on_whales: True

If the flag is set but python_on_whales is not installed, a warning is logged and the module falls back to the legacy compose library so the minion continues to function.

Changed in version 3009.0: The default backend flips to python_on_whales (docker compose v2). dockercompose:use_python_on_whales becomes a deprecated no-op and will be removed in a subsequent release.

The legacy backend requires at least version 1.4.0 of both docker-compose and Docker. docker-compose can easily be installed using pip.install:

salt myminion pip.install docker-compose>=1.5.0

How to use this module?

In order to use the module if you have no docker-compose file on the server you can issue the command create, it takes two arguments the path where the docker-compose.yml will be stored and the content of this latter:

# salt-call -l debug dockercompose.create /tmp/toto '
database:
image: mongo:3.0
command: mongod --smallfiles --quiet --logpath=/dev/null
'

Then you can execute a list of method defined at the bottom with at least one argument (the path where the docker-compose.yml will be read) and an optional python list which corresponds to the services names:

# salt-call -l debug dockercompose.up /tmp/toto
# salt-call -l debug dockercompose.restart /tmp/toto '[database]'
# salt-call -l debug dockercompose.stop /tmp/toto
# salt-call -l debug dockercompose.rm /tmp/toto

Docker-compose method supported

• up

• restart

• stop

• start

• pause

• unpause

• kill

• rm

• ps

• pull

• build

Functions

• docker-compose.yml management

  • dockercompose.create

  • dockercompose.get

• Manage containers

  • dockercompose.restart

  • dockercompose.stop

  • dockercompose.pause

  • dockercompose.unpause

  • dockercompose.start

  • dockercompose.kill

  • dockercompose.rm

  • dockercompose.up

• Manage containers image:

  • dockercompose.pull

  • dockercompose.build

• Gather information about containers:

  • dockercompose.ps

• Manage service definitions:

  • dockercompose.service_create

  • dockercompose.service_upsert

  • dockercompose.service_remove

  • dockercompose.service_set_tag

Detailed Function Documentation

salt.modules.dockercompose.build(path, service_names=None)

Build image for containers in the docker-compose file, service_names is a python list, if omitted build images for all containers. Please note that at the moment the module does not allow you to upload your Dockerfile, nor any other file you could need with your docker-compose.yml, you will have to make sure the files you need are actually in the directory specified in the build keyword

path

Path where the docker-compose file is stored on the server

service_names

If specified will pull only the image for the specified services

CLI Example:

salt myminion dockercompose.build /path/where/docker-compose/stored
salt myminion dockercompose.build /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.create(path, docker_compose)

Create and validate a docker-compose file into a directory

path

Path where the docker-compose file will be stored on the server

docker_compose

docker_compose file

CLI Example:

salt myminion dockercompose.create /path/where/docker-compose/stored content

salt.modules.dockercompose.create_command(path, service_names=None)

Create (but does not start) containers, networks, volumes from the docker-compose file, service_names is a python list, if omitted creates all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will create only the containers for the specified services

CLI Example:

salt myminion dockercompose.pull /path/where/docker-compose/stored
salt myminion dockercompose.pull /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.get(path)

Get the content of the docker-compose file into a directory

path

Path where the docker-compose file is stored on the server

CLI Example:

salt myminion dockercompose.get /path/where/docker-compose/stored

salt.modules.dockercompose.kill(path, service_names=None)

Kill containers in the docker-compose file, service_names is a python list, if omitted kill all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will kill only the specified services

CLI Example:

salt myminion dockercompose.kill /path/where/docker-compose/stored
salt myminion dockercompose.kill /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.pause(path, service_names=None)

Pause running containers in the docker-compose file, service_names is a python list, if omitted pause all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will pause only the specified services

CLI Example:

salt myminion dockercompose.pause /path/where/docker-compose/stored
salt myminion dockercompose.pause /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.ps(path)

List all running containers and report some information about them

path

Path where the docker-compose file is stored on the server

CLI Example:

salt myminion dockercompose.ps /path/where/docker-compose/stored

salt.modules.dockercompose.pull(path, service_names=None)

Pull image for containers in the docker-compose file, service_names is a python list, if omitted pull all images

path

Path where the docker-compose file is stored on the server

service_names

If specified will pull only the image for the specified services

CLI Example:

salt myminion dockercompose.pull /path/where/docker-compose/stored
salt myminion dockercompose.pull /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.restart(path, service_names=None)

Restart container(s) in the docker-compose file, service_names is a python list, if omitted restart all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will restart only the specified services

CLI Example:

salt myminion dockercompose.restart /path/where/docker-compose/stored
salt myminion dockercompose.restart /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.rm(path, service_names=None)

Remove stopped containers in the docker-compose file, service_names is a python list, if omitted remove all stopped containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will remove only the specified stopped services

CLI Example:

salt myminion dockercompose.rm /path/where/docker-compose/stored
salt myminion dockercompose.rm /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.service_create(path, service_name, definition)

Create the definition of a docker-compose service This fails when the service already exists This does not pull or up the service This wil re-write your yaml file. Comments will be lost. Indentation is set to 2 spaces

path

Path where the docker-compose file is stored on the server

service_name

Name of the service to create

definition

Service definition as yaml or json string

CLI Example:

salt myminion dockercompose.service_create /path/where/docker-compose/stored service_name definition

salt.modules.dockercompose.service_remove(path, service_name)

Remove the definition of a docker-compose service This does not rm the container This wil re-write your yaml file. Comments will be lost. Indentation is set to 2 spaces

path

Path where the docker-compose file is stored on the server

service_name

Name of the service to remove

CLI Example:

salt myminion dockercompose.service_remove /path/where/docker-compose/stored service_name

salt.modules.dockercompose.service_set_tag(path, service_name, tag)

Change the tag of a docker-compose service This does not pull or up the service This wil re-write your yaml file. Comments will be lost. Indentation is set to 2 spaces

path

Path where the docker-compose file is stored on the server

service_name

Name of the service to remove

tag

Name of the tag (often used as version) that the service image should have

CLI Example:

salt myminion dockercompose.service_create /path/where/docker-compose/stored service_name tag

salt.modules.dockercompose.service_upsert(path, service_name, definition)

Create or update the definition of a docker-compose service This does not pull or up the service This wil re-write your yaml file. Comments will be lost. Indentation is set to 2 spaces

path

Path where the docker-compose file is stored on the server

service_name

Name of the service to create

definition

Service definition as yaml or json string

CLI Example:

salt myminion dockercompose.service_upsert /path/where/docker-compose/stored service_name definition

salt.modules.dockercompose.start(path, service_names=None)

Start containers in the docker-compose file, service_names is a python list, if omitted start all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will start only the specified services

CLI Example:

salt myminion dockercompose.start /path/where/docker-compose/stored
salt myminion dockercompose.start /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.stop(path, service_names=None)

Stop running containers in the docker-compose file, service_names is a python list, if omitted stop all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will stop only the specified services

CLI Example:

salt myminion dockercompose.stop /path/where/docker-compose/stored
salt myminion dockercompose.stop  /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.unpause(path, service_names=None)

Un-Pause containers in the docker-compose file, service_names is a python list, if omitted unpause all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will un-pause only the specified services

CLI Example:

salt myminion dockercompose.pause /path/where/docker-compose/stored
salt myminion dockercompose.pause /path/where/docker-compose/stored '[janus]'

salt.modules.dockercompose.up(path, service_names=None)

Create and start containers defined in the docker-compose.yml file located in path, service_names is a python list, if omitted create and start all containers

path

Path where the docker-compose file is stored on the server

service_names

If specified will create and start only the specified services

CLI Example:

salt myminion dockercompose.up /path/where/docker-compose/stored
salt myminion dockercompose.up /path/where/docker-compose/stored '[janus]'