shadowigor.docker_simple
docker_simple
This is a module for Ansible with the goal to simplify the handling of Docker images.
Wait, isn't there an official docker module already?
There is! But for me it was quite hard to use and very counterintuitive. For example, it doesn't check, whether an image has to be rebuilt because the Dockerfile changed, if 'something' is there, the module was happy. There was also no way to stop a container without knowing ALL of the parameters it was started with. Things like that made me develop this module.
What it does
It is basically a wrapper for the docker command. It does not use the docker API, because the docker-py module doesn't support all command line arguments that the docker command has.
With the module you are describing the state of a container. It can have the following states
running: Makes sure the image you are using is up to date, rebuilds/pulls it if needed and then starts a container with the given image and name. The container is recreated and restarted if the image or the run arguments change.stopped: Makes sure there is no container running with a given name.restarted: Same asrunning, but the container is definitely restarted, even if nothing changed.built: Makes sure the image is built, but doesn't start a container.
How to use it
Use it as a normal docker module with the following parameters:
state: See abovename: The name of the container.path: The path to the Dockerfile that describes the image of the container. If empty, it is assumed that the image should be pulled form the remote registry.image: Name of the image. You must not include a tag if you build a local image (pathis present). The image will automatically get the tag:localto more easily distinguish it from pulled images. You can also not use the tag:localfor images that are supposed to be pulled.command: The command to run inside the container.build_args: Command line arguments of thedocker buildcommand
All other parameters are directly translated to command line arguments of the docker run command
I'd like an example, please
- name: Build and start my container
docker_simple:
name: mycontainer
image: myimage
state: running
path: /path/to/Dockerfile/of/myimage/
network: mynetwork
hostname: thehost
network_alias: thehost
env:
- ENV_VARIABLE=very_useful
- SOME=thing
volume:
- /host/mnt1:/container/mnt1
- /host/mnt2:/container/mnt2
Do a man docker-run if you don't know what some of those parameters do that weren't explained above.
Note: A dash (-) in an argument name is replace by an underscore (_).
How to install
To make this module a dependency of your playbook, add the following to the requirements.yml file in the root directory of your playbook:
- src: shadowigor.docker_simple
Before running your playbook for the first time, run the following command:
ansible-galaxy install -r requirements.yml
You will also have to run the role before you can use it. For this you can add this to the top of your site.yml file:
- hosts: all
roles:
- shadowigor.docker_simple
Copyright (C) 2019 Alain Kohli
ansible-galaxy install shadowigor.docker_simple