Skip to content

Usage

Jump to bottom
Nicholas St. Germain edited this page Jan 22, 2019 · 37 revisions

Command line arguments can be viewed by running:

docker run --rm pyouroboros/ouroboros --help

All command line arguments can be substituted with an environment variable. command line options are kebab-case and environment variables are SCREAMING_CASE. E.g. --docker-sockets vs. DOCKER_SOCKETS. All examples will be given as environment variables for a docker run as --help will show command line examples

Help

Type: Boolean - Interrupting
Command Line: -h, --help

Shows the help message then exits

Core

Version

Type: Boolean - Interrupting
Command Line: -v, --version

Shows the current version number then exits

Docker Sockets

Type: List - Space separated
Command Line: -d, --docker-sockets
Environment Variable: DOCKER_SOCKETS
Default: unix://var/run/docker.sock
Example: -e DOCKER_SOCKETS="unix://var/run/docker.sock tcp://192.168.1.100:2376"

Allows you to define a list of docker sockets. If defined, it does not include the local socket by default.

Docker TLS Verify

Type: Boolean
Command Line: -t, --docker-tls-verify
Environment Variable: DOCKER_TLS_VERIFY
Default: False
Example: -e DOCKER_TLS_VERIFY=true -v $DOCKER_CERT_FOLDER:/root/.docker/

Enables docker TLS secure client connections by certificate

Interval

Type: Integer
Command Line: -i, --interval
Environment Variable: INTERVAL
Example: -e INTERVAL=300

The interval in seconds between checking for updates. There is a hard-coded 30 second minimum. Anything lower than that will set to 30.

Log Level

Type: String - Choice
Command Line: -l, --log-level
Environment Variable: LOG_LEVEL
Choices:

  • debug
  • info
  • warn
  • error
  • critical

Example: -e LOG_LEVEL=info

Sets your logging verbosity level.

Self Update

Type: Boolean
Command Line: -u, --self-update
Environment Variable: SELF_UPDATE
Default: False
Example: -e SELF_UPDATE=true

Let ouroboros update itself in addition to your other containers. Self updates require the the container to be named either ouroboros or ouroboros-updated and will alternate the former names for updates. Self updates will wipe update counters for notifications.

Run Once

Type: Boolean - Interrupting
Command Line: -o, --run-once
Default: False

Ouroboros will only do a single pass of all container checks, and then exit. This is a great way to granularly control scheduling with an outside scheduler like cron. If during the single pass ouroboros has to self-update, it will do another full pass after updating itself to ensure that all containers were checked.

Docker Specifics

Monitor

Type: List - Space separated
Command Line: -m, --monitor
Environment Variable: MONITOR
Default: All
Example: -e MONITOR="nginx telegraf portainer"

Define a list of containers you would like to monitor instead of all containers. If defined, labels then ignore take precedence. If a container is listed that does not match the name of currently running containers, it will be ignored.

Ignore

Type: List - Space separated
Command Line: -n, --ignore
Environment Variable: IGNORE
Default: None
Example: -e IGNORE="mariadb influxdb mongo postgres"

Define a list of containers you would like to ignore updates for. If a container is listed that does not match the name of currently running containers, it will be ignored.

Label Enable

Type: Boolean
Command Line: -k, --label-enable
Environment Variable: LABEL_ENABLE
Default: False
Example: -e LABEL_ENABLE=true

If a container has a com.ouroboros.enable label, only watch it if it is set to true. Supersedes monitor/ignore in precedence. This can be achieved by setting LABEL com.ouroboros.enable="false" in your Dockerfile or passing the label during creation of the container with docker run -d --label=com.ouroboros.enable="false" person/image:tag

Cleanup

Type: Boolean
Command Line: -c, --cleanup
Environment Variable: CLEANUP
Default: False
Example: -e CLEANUP=true

Remove the old images after updating. If you have multiple containers using the same image, it will ensure all containers are updated before successfully removing the image.

Latest

Type: Boolean
Command Line: -L, --latest
Environment Variable: LATEST
Default: False
Example: -e LATEST=true

Pull the :latest tags and update all containers to it, regardless of the current tag the container is running as.

Repository User

Type: String
Command Line: -r, --repo-user
Environment Variable: REPO_USER
Default: None
Example: -e REPO_USER=johndoe1970

Define a username for repository authentication. Will be ignored without defining a repository password.

Repository Password

Type: String
Command Line: -R, --repo-pass
Environment Variable: REPO_PASS
Default: None
Example: -e REPO_PASS=0791eodnhoj

Define a password for repository authentication. Will be ignored without defining a repository username.

Data Export

Log Level

Type: String - Choice
Command Line: -D, --data-export
Environment Variable: DATA_EXPORT
Choices:

  • prometheus
  • influxdb Example: -e DATA_EXPORT=influxdb

Enables exporting metric data to your chosen application. If you choose Prometheus, and self update, port bindings will not persist. It is recommended to reverse proxy your exporter through nginx. If you choose influxdb, you must set influx database at minimum.

Prometheus Address

Type: String
Command Line: -a, --prometheus-addr
Environment Variable: PROMETHEUS_ADDR
Default: 127.0.0.1
Example: -e PROMETHEUS_ADDR=0.0.0.0

Bind address for prometheus exporter to attach to.

Prometheus Port

Type: Integer
Command Line: -p, --prometheus-port
Environment Variable: PROMETHEUS_PORT
Default: 8000
Example: -e PROMETHEUS_PORT=3579

Bind port for prometheus exporter to attach to.

Influx URL

Type: String
Command Line: -I, --influx-url
Environment Variable: INFLUX_URL
Default: 127.0.0.1
Example: -e INFLUX_URL=192.168.1.100

URL influxdb is listening on

Influx Port

Type: Integer
Command Line: -P, --influx-port
Environment Variable: INFLUX_PORT
Default: 8086
Example: -e INFLUX_PORT=8123

Port influxdb is listening on

Influx Username

Type: String
Command Line: -U, --influx-username
Environment Variable: INFLUX_USERNAME
Default: root
Example: -e INFLUX_USERNAME=ouroboros

Username to authenticate to influx with.

Influx Password

Type: String
Command Line: -x, --influx-password
Environment Variable: INFLUX_PASSWORD
Default: root
Example: -e INFLUX_PASSWORD=soroboruo

Password to authenticate to influx with.

Influx Database

Type: String
Command Line: -X, --influx-database
Environment Variable: INFLUX_DATABASE
Default: None
Example: -e INFLUX_DATABASE=ouroboros

Database to save data points to. Not set and required if using influxdb.

Influx SSL

Type: Boolean
Command Line: -s, --influx-ssl
Environment Variable: INFLUX_SSL
Default: None
Example: -e INFLUX_SSL=true

Use SSL when connecting to influxdb. (mainly used when influxdb is behind an https reverse proxy)

Influx Verify SSL

Type: Boolean
Command Line: -V, --influx-verify-ssl
Environment Variable: INFLUX_VERIFY_SSL
Default: False
Example: -e INFLUX_VERIFY_SSL=true

Verify the ssl certificate used when connecting to influxdb. only used in conjunction with influx ssl

.env 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 \
  pyouroboros/ouroboros

Sample env.list:

DOCKER_SOCKETS=tcp://localhost:2375
INTERVAL=60
MONITOR="container_1 container_2"

Docker Compose

version: '3'
services:
  nginx:
    image: nginx:1.14-alpine
    ports:
     - 80:80
  ouroboros:
    image: pyouroboros/ouroboros
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 60 --log-level debug
    environment:
    - REPO_USER=user
    - REPO_PASS=password

Examples

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 \
  pyouroboros/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 \
  pyouroboros/ouroboros --monitor container_1 container_2 container_3

Ignore select containers

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --ignore container_1 container_2 container_3

Change loglevel

The amount of logging details can be suppressed by providing a log-level argument.

Default is info

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros --log-level 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 run-once 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 \
  pyouroboros/ouroboros --run-once

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 \
  pyouroboros/ouroboros --cleanup

Prometheus metrics

Ouroboros keeps track of containers being updated and how many are being monitored. Said metrics are exported using prometheus. You can also bind the http server to a different interface for systems using multiple networks. --prometheus-port and --prometheus-addr can run independently of each other without issue.

Prometheus exporter will not be reachable by default inside of a container. You will need to intentionally bind to 0.0.0.0 for docker network interfaces to be able to reach the exporter the host network. This was done intentionally for security reasons.

Bind Address & Port

Bind Address default is 127.0.0.1

Port Default is 8000

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8000:8000 pyouroboros/ouroboros --data-export prometheus --prometheus-addr 0.0.0.0

You should then be able to see the metrics at http://localhost: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

Webhook Notifications

See the notifications wiki for more details.

Default is None

docker run -d --name ouroboros \
 -v /var/run/docker.sock:/var/run/docker.sock \
 pyouroboros/ouroboros --webhook-urls https://hooks.slack.com/something https://discordapp.com/api/webhooks/something

Clone this wiki locally