import files
This commit is contained in:
Yann Autissier
@@ -0,0 +1,237 @@
|
||||
# Ansible role to run dockers
|
||||
|
||||
An ansible role to install the [docker](https://www.docker.com/) daemon and build and run dockers.
|
||||
|
||||
It installs the docker daemon and ensure it is up and running.
|
||||
It sets the STORAGE_DRIVER if the docker host uses systemd and it configures the MTU to 1450 if it is a VM running on OpenStack.
|
||||
It builds and runs docker images on the docker host.
|
||||
|
||||
## Requirements
|
||||
|
||||
This Ansible role requires at least Ansible version 1.9.
|
||||
|
||||
## Role Variables
|
||||
|
||||
* `docker_check_kernel` - The minimum kernel version allowed on hosts to run docker.
|
||||
|
||||
``` yaml
|
||||
# minimum kernel version
|
||||
docker_check_kernel: '3.10'
|
||||
```
|
||||
|
||||
* `docker_check_machine` - The hosts architecture needed to run docker.
|
||||
|
||||
``` yaml
|
||||
# architecture
|
||||
docker_check_machine: 'x86_64'
|
||||
```
|
||||
|
||||
* `docker_package` - The name of the docker package.
|
||||
|
||||
``` yaml
|
||||
# The docker package name
|
||||
docker_package: docker
|
||||
```
|
||||
|
||||
* `docker_packages` - A list of packages to install/remove before installing the docker package.
|
||||
|
||||
``` yaml
|
||||
# A list of package to install/remove
|
||||
# docker_packages:
|
||||
# - { "name": "docker", "state": "absent" }
|
||||
```
|
||||
|
||||
* `docker_init_config_directory` - The location of the configuration file of the docker daemon init script.
|
||||
|
||||
``` yaml
|
||||
# Location of configuration files loaded by the init script
|
||||
docker_init_config_directory: "/etc/sysconfig"
|
||||
```
|
||||
|
||||
* `docker_opts` - The name of the environment variable used to pass options to the docker daemon.
|
||||
|
||||
``` yaml
|
||||
# docker daemon options environment variable
|
||||
docker_opts: "OPTIONS"
|
||||
```
|
||||
|
||||
* `docker_services` - A list of system services to start
|
||||
|
||||
``` yaml
|
||||
# services
|
||||
docker_services:
|
||||
- docker
|
||||
```
|
||||
|
||||
* `dockers` - A list of docker images to build and run on the docker host with the docker-build and docker-run commands
|
||||
|
||||
``` yaml
|
||||
# dockers
|
||||
# dockers:
|
||||
# - nginx
|
||||
```
|
||||
|
||||
* `docker_cluster` - An optional cluster name to pass to the docker-build and docker-run commands
|
||||
|
||||
``` yaml
|
||||
# docker cluster
|
||||
# docker_cluster: ""
|
||||
```
|
||||
|
||||
* `docker_cluster` - Starts the dockers if set to true.
|
||||
|
||||
``` yaml
|
||||
# Start docker
|
||||
docker_start: true
|
||||
```
|
||||
|
||||
* `docker_restart` - Restarts dockers when their image has been updated. It removes current running dockers and start new ones.
|
||||
|
||||
``` yaml
|
||||
# Stop and remove running docker to start a new one when image has been updated
|
||||
docker_restart: true
|
||||
```
|
||||
|
||||
* `docker_force_restart` - Restart dockers, even if image has not been updated. It removes current running dockers and start new ones.
|
||||
|
||||
``` yaml
|
||||
# Stop and remove running docker to start a new one even if image has not been updated
|
||||
docker_force_restart: false
|
||||
```
|
||||
|
||||
## Helper scripts
|
||||
|
||||
This role comes with a few helper scripts. Here is a short description.
|
||||
|
||||
* `docker-build` - Build a docker image, reading options to pass to the `docker build` command from a Dockeropts file.
|
||||
|
||||
* `docker-cleanup` - Remove unused dockers.
|
||||
|
||||
* `docker-cleanup-images` - Remove unused docker images.
|
||||
|
||||
* `docker-cleanup-volumes` - Remove unused docker volumes.
|
||||
|
||||
* `docker-get-image` - Return sha256 of the image used by the docker.
|
||||
|
||||
* `docker-get-status` - Return the status of the docker.
|
||||
|
||||
* `docker-log-cleanup` - Empty the file logging the docker output on the docker host.
|
||||
|
||||
* `docker-log-truncate` - Truncate the file logging the docker output on the docker host.
|
||||
|
||||
* `docker-run` - Run a docker, reading options to pass to the `docker run` command from a Dockeropts file.
|
||||
|
||||
## Example
|
||||
|
||||
To launch this role on your `docker` hosts, run the default playbook.yml.
|
||||
|
||||
``` bash
|
||||
$ ansible-playbook playbook.yml
|
||||
```
|
||||
|
||||
### Build a docker image
|
||||
|
||||
On the docker hosts, you'll be able to build docker images and run dockers, based on Dockerfile and Dockeropts files located in the /etc/docker subdirectories.
|
||||
|
||||
To create an `nginx` docker image, create a directory /etc/docker/nginx with a Dockerfile and a Dockeropts files into.
|
||||
|
||||
``` bash
|
||||
# mkdir -p /etc/docker/nginx
|
||||
# cat << EOF > /etc/docker/nginx/Dockerfile
|
||||
FROM nginx:alpine
|
||||
EOF
|
||||
# cat << EOF > /etc/docker/nginx/Dockeropts
|
||||
DOCKER_ULIMIT="nofile=65536"
|
||||
DOCKER_PORT="80:80"
|
||||
EOF
|
||||
```
|
||||
|
||||
Build your `nginx` docker image, then run it ! The docker-run command will read the Dockeropts file to add the --ulimit and --port options to the docker run command.
|
||||
|
||||
``` bash
|
||||
# docker-build nginx && docker-run nginx
|
||||
```
|
||||
|
||||
### Override your files
|
||||
|
||||
If you want to copy a file in your Dockerfile, say the default nginx.conf, you can use the DOCKER_BUILD_PREFIX and DOCKER_BUILD_SUFFIX variables to get different versions of this file giving some context.
|
||||
|
||||
``` bash
|
||||
# cat << EOF > /etc/docker/nginx/Dockerfile
|
||||
FROM nginx:alpine
|
||||
ARG DOCKER_BUILD_PREFIX
|
||||
ARG DOCKER_BUILD_SUFFIX
|
||||
COPY ./\${DOCKER_BUILD_PREFIX}nginx.conf\${DOCKER_BUILD_SUFFIX} /etc/nginx/nginx.conf
|
||||
EOF
|
||||
```
|
||||
|
||||
You can now override the nginx configuration file when you build your image.
|
||||
|
||||
* Without option, the docker-build command will search for the file beside your Dockerfile.
|
||||
|
||||
``` bash
|
||||
# docker-build nginx && docker-run nginx
|
||||
```
|
||||
|
||||
Both DOCKER_BUILD_PREFIX and DOCKER_BUILD_SUFFIX variables are empty, the Dockerfile will search for a `./nginx.conf` file, ie the /etc/docker/nginx/nginx.conf file.
|
||||
|
||||
* With a -c|--cluster option, the docker-build command will search for the file in a subdirectory below your Dockerfile.
|
||||
|
||||
``` bash
|
||||
# docker-build -c custom nginx && docker-run -c custom nginx
|
||||
```
|
||||
|
||||
The DOCKER_BUILD_PREFIX variable is populated with 'custom/' to force the Dockerfile to search for a `./custom/nginx.conf` file, ie /etc/docker/nginx/custom/nginx.conf file.
|
||||
|
||||
* Whith an image name suffixed with a dash, the docker-build command will search for a suffixed file as well.
|
||||
|
||||
``` bash
|
||||
# docker-build -c custom nginx-develop && docker-run -c custom nginx-develop
|
||||
```
|
||||
|
||||
The DOCKER_BUILD_PREFIX variable is populated with 'custom/' and the DOCKER_BUILD_SUFFIX variable is populated with '-develop' to force the Dockerfile to search for a `./custom/nginx.conf-develop` file, ie /etc/docker/nginx/custom/nginx.conf-develop file.
|
||||
|
||||
### Override your options
|
||||
|
||||
The same override principle can be used for the Dockerfile and the Dockeropts file when using the docker-build and docker-run commands.
|
||||
You can create a /etc/docker/nginx/custom/Dockeropts file that would override your default Dockeropt file, and a /etc/docker/nginx/custom/Dockeropts-develop file overriding both other files too.
|
||||
The Dockeropts file accepts the following options.
|
||||
|
||||
* `SYSCTL` - values to set on the docker host via the sysctl command before running the docker
|
||||
* `DOCKER_ARGS` - values to pass to the docker build command with --build-arg options
|
||||
* `DOCKER_ENV` - values to pass to the docker run command with -e options
|
||||
* `DOCKER_LINK` - values to pass to the docker run command with --link options
|
||||
* `DOCKER_OPT` - values to pass to the docker run command with prefixed by --
|
||||
* `DOCKER_PORT` - values to pass to the docker run command with -p options
|
||||
* `DOCKER_ULIMIT` - values to pass to the docker run command with --ulimit options
|
||||
* `DOCKER_VOLUME` - values to pass to the docker run command with -v options
|
||||
* `HOST_VOLUME` - volumes to allow write access to from the docker on selinux enabled host
|
||||
|
||||
Overriding options is done several times, reading options from the more specific to the more generic file. In our example, files are read in this order :
|
||||
/etc/docker/nginx/custom/Dockeropts-develop
|
||||
/etc/docker/nginx/custom/Dockeropts
|
||||
/etc/docker/nginx/Dockeropts
|
||||
|
||||
## Common configuration
|
||||
|
||||
Following configuration builds and runs the docker image 'nginx-develop' for the 'custom' cluster described in our example.
|
||||
The Dockerfile and Dockeropts files needed in the /etc/docker/nginx directory should be present on the docker host, likely synchronised by an other ansible role.
|
||||
|
||||
``` yaml
|
||||
docker_cluster: "custom"
|
||||
docker:
|
||||
- nginx-develop
|
||||
```
|
||||
|
||||
## Tests
|
||||
|
||||
To test this role on your `docker` hosts, run the tests/playbook.yml playbook.
|
||||
|
||||
``` bash
|
||||
$ ansible-playbook tests/playbook.yml
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
This role is known to work on Ubuntu, Debian, CentOS and Alpine Linux.
|
||||
|
||||
Reference in New Issue
Block a user