dannysauer / ouroboros

Automatically update running docker containers with latest image

Automatically update your running Docker containers to the latest available image.

A python-based alternative to watchtower

Table of Contents

• Overview
• Usage
  • Docker
  • Pip
  • Options
  • Config File
  • Private Registries
• Examples
  • Monitor for updates for original tag
  • Update containers on a remote host
  • Change update frequency
  • Change loglevel
  • Update all containers and quit ouroboros
  • Remove old docker images
• Prometheus metrics
• Execute Tests
• Contributing

Overview

Ouroboros will monitor all running docker containers or those you specify and update said containers to the latest available image in the remote registry using the latest tag with the same parameters that were used when the container was first created such as volume/bind mounts, docker network connections, environment variables, restart policies, entrypoints, commands, etc. While ouroboros updates images to latest by default, that can be overridden to only monitor updates of a specific tag. Similar to watchtower.

• Push your image to your registry and simply wait a couple of minutes for ouroboros to find the new image and redeploy your container autonomously.
• Limit your server ssh access
• ssh -i key server.domainname "docker pull ... && docker run ..." is for scrubs

Usage

Docker

Ouroboros is deployed via docker image like so:

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros

or via docker-compose:

version: '3'
services:
  nginx:
    image: nginx:1.14-alpine
    ports:
     - 80:80
  ouroboros:
    image: circa10a/ouroboros
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 60 --loglevel debug

Pip

Ouroboros can also be installed via pip:

pip install ouroboros-cli

And can then be invoked using the ouroboros command:

$ ouroboros --interval 5 --loglevel debug

This can be useful if you would like to create a systemd service or similar daemon that doesn't run in a container

Options

All arguments can be ran together without conflication

All arguments can be supplemented with environment variables, but command line arguments will take priority

docker run --rm circa10a/ouroboros --help

• --url, -u Monitor and update containers on a remote system by providing the url argument.
  • Default is unix://var/run/docker.sock.
  • Environment variable: URL=tcp://localhost:2375.
• --interval, -i Change how often ouroboros checks the remote docker registry for image updates (in seconds).
  • Default is 300.
  • Environment variable: INTERVAL=60.
• --monitor, -m Only monitor select containers which supports an infinite amount of container names.
  • Default is all containers.
  • Environment variable: MONITOR=test_container
• --ignore, -n Ignore the listed container names.
  • Default is none.
  • Environment variable: IGNORE=test_container
  • If a container name is specified to monitor and ignore, ignore takes precedent.
• --loglevel, -l The amount of logging details can be supressed or increased.
  • Default is info.
  • Environment variable: LOGLEVEL=debug.
• --runonce, -r Update all your running containers in one go and terminate ouroboros.
  • Default is False.
  • Environment variable: RUNONCE=true.
• --cleanup, -c Remove the older docker image if a new one is found and updated.
  • Default is False.
  • Environment variable: CLEANUP=true
• --keep-tag, -k Only monitor if updates are made to the tag of the image that the container was created with instead of using latest. This will enable watchtower-like functionality.
  • Default is False.
  • Environment variable: KEEPTAG=true
• --metrics-addr What address for the prometheus endpoint to bind to. This arg is best suited for ouroboros-cli.
  • Default is 0.0.0.0.
  • Environment variable: METRICS_ADDR=0.0.0.0
• --metrics-port What port to run prometheus endpoint on. Running on port 8000 by default if --metrics-port is not supplied.
  • Default is 8000.
  • Environment variable: METRICS_PORT=8000

Config File

You can provide a docker env file to supplement a config file with all the above listed arguments by utilizing the supported environment variables.

docker run -d --name ouroboros \
  --env-file env.list \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros

Sample env.list

URL=tcp://localhost:2375
INTERVAL=60
KEEPTAG=true

Private Registries

If your running containers' docker images are stored in a secure registry that requires a username and password, simply run ouroboros with 2 environment variables(REPO_USER and REPO_PASS).

docker run -d --name ouroboros \
  -e REPO_USER=myUser -e REPO_PASS=myPassword \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros

You can alternatively bind mount ~/.docker/config.json which won't require the above environment variables.

docker run -d --name ouroboros \
  -v $HOME/.docker/config.json:/root/.docker/config.json \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros

Examples

Monitor for updates for original tag

Instead of always updating to latest you can specify if you would like Ouroboros to only check for updates for your original container's image tag. e.g. If your container was started with nginx:1.14-alpine using --keep-tag will poll the docker registry and compare digests. If there is a new image for nginx:1.14-alpine, ouroboros will update your container using the newly patched version.

Default is False

docker run -d --name ouroboros \
 -v /var/run/docker.sock:/var/run/docker.sock \
 circa10a/ouroboros --keep-tag

Update containers on a remote host

Ouroboros can monitor things other than just local, pass the --url argument to update a system with the Docker API exposed.

Default is unix://var/run/docker.sock

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --url tcp://my-remote-docker-server:2375

Change update frequency

An interval argument can be supplied to change how often ouroboros checks the remote docker registry for image updates (in seconds).

Default is 300s

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --interval 600

Monitor select containers

By default, ouroboros will monitor all running docker containers, but can be overridden to only monitor select containers by passing a monitor argument which supports an infinite amount of container names.

Default is all

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --monitor containerA containerB containerC

Change loglevel

The amount of logging details can be supressed by providing a loglevel argument.

Default is info

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --loglevel debug

Update all containers and quit ouroboros

If you prefer ouroboros didn't run all the time and only update all of your running containers in one go, provide the runonce argument and ouroboros will terminate itself after updating all your containers one time.

Default is False

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --runonce

Remove old docker images

Ouroboros has the option to remove the older docker image if a new one is found and the container is then updated. To tidy up after updates, pass the cleanup argument.

Default is False

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --cleanup

Prometheus metrics

Ouroboros keeps track of containers being updated and how many are being monitored. Said metrics are exported using prometheus. Metrics are collected by ouroboros with or without this flag, it is up to you if you would like to expose the port or not. You can also bind the http server to a different interface for systems using multiple networks. --metrics-port and --metrics-addr can run independently of each other without issue.

Port

Default is 8000

docker run -d --name ouroboros \
  -p 5000:5000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --metrics-port 5000

You should then be able to see the metrics at http://localhost:5000/

Bind Address

Ouroboros allows you to bind the exporter to a different interface using the --metrics-addr argument. This works better for the CLI since docker networks always use 172.*.*.* addresses, unless you have a very specific config.

Default is 0.0.0.0

docker run -d --name ouroboros \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  circa10a/ouroboros --metrics-addr 10.0.0.1

Then access via http://10.0.0.1:8000/

Example text from endpoint:

# HELP containers_updated_total Count of containers updated
# TYPE containers_updated_total counter
containers_updated_total{container="all"} 2.0
containers_updated_total{container="alpine"} 1.0
containers_updated_total{container="busybox"} 1.0
# TYPE containers_updated_created gauge
containers_updated_created{container="all"} 1542152615.625264
containers_updated_created{container="alpine"} 1542152615.6252713
containers_updated_created{container="busybox"} 1542152627.7476819
# HELP containers_being_monitored Count of containers being monitored
# TYPE containers_being_monitored gauge
containers_being_monitored 2.0

Execute Tests

Script will install dependencies from requirements-dev.txt

All tests:

./run_tests.sh

Unit tests:

./run_tests.sh unit

Integration tests:

./run_tests.sh integration

Contributing

All welcome