docker-mon
Docker container monitor and micro-orchestrator π©Ίπ¦
Docker-mon (or mon
for short) was built to solve two problems, when working with containers outside of an orchestration platform (e.g. kubernetes or swarm):
- Restart containers that are failing their
HEALTHCHECK
- Remove un-needed containers and their resources when they're safely stopped
To do this, mon
runs in it's own docker container and queries the docker daemon API to inspect the state of other containers. As such, mon
requires the docker control socket be mounted with -v /var/run/docker.sock:/var/run/docker.sock
. There's also some additional metadata that can be attached to containers, to control what mon
will do to them.
Getting Started π
# Grab the latest version from dockerhub
docker pull bengreenier/mon:latest
- π Configure containers
# Start nginx, configuring it for cleanup
# mon will remove the container completely, if it stops with exit code '0'
# mon will restart the container, if it has a healthcheck, and it's failing
docker run --label mon.observe=1 mon.checks.cleanup=1 mon.checks.health=1 nginx:latest
# Run mon, forwarding the docker control socket
docker run -v /var/run/docker.sock:/var/run/docker.sock bengreenier/mon:latest
Modes π
Detailed descriptions of the mon
operation modes.
Health Monitoring π©ββοΈ
Health monitoring is an extension to HEALTHCHECK
functionality, to restart containers that are failing. This was originally planned, but never landed in docker itself. There are some other great containers (like autoheal) that provide this functionality as well.
mon
observes the container metadata, and if State.Health.Status
is Unhealthy
, it will restart the container.
Cleanup Monitoring π§Ό
Cleanup monitoring helps keep the host os from becoming cluttered with content from stopped containers. It will remove containers, links, and volumes that are no longer needed.
mon
does this by observing the container metadata, and if State.Running
, state.Restarting
, are false, and state.ExitCode
matches the expected value (default is 0
), it will remove the container.
Arguments πββοΈ
mon
supports some command-line arguments to control it's behavior. Here they are:
control
- Docker control socket. Default is unix:///var/run/docker.sock
.
prefix
- Docker container prefix to limit observation to. Default is empty, meaning no prefix is required, all containers will be observed.
interval
- Interval to poll at (in ms). Default is 10000
(10s).
retries
- Max retry count for failed docker commands. Default is 10
.
quiet
- Only log when action is taken. Default is false
.
Environment Variables π
The same Arguments that are supported above, can be used as environment variables, prefixed with MON_
. Here they are:
MON_CONTROL
- Docker control socket. Default is unix:///var/run/docker.sock
.
MON_PREFIX
- Docker container prefix to limit observation to. Default is empty, meaning no prefix is required, all containers will be observed.
MON_INTERVAL
- Interval to poll at (in ms). Default is 10000
(10s).
MON_RETRIES
- Max retry count for failed docker commands. Default is 10
.
MON_QUIET
- Only log when action is taken. Default is false
.
mon
supports some additional metadata on containers, that inform it's actions. Here they are:
mon.observe
includes the container in mon observations, when set to 1
.
mon.checks.health
includes the container in HEALTHCHECK
observations, when set to 1
.
mon.checks.health.timeout
overrides the expected restart interval (in ms), that a container has to restart. Default is 10000
(10ms).
mon.checks.cleanup
includes the container in cleanup observations, when set to 1
.
mon.checks.cleanup.code
overrides the expected exit code for the container, which if returned will lead to cleanup. Default is 0
.
Contributing π©βπ»
Thanks for your interest! To participate, you'll need VSCode, as development occurs in a DevContainer. Other than that, I don't have much advice at this point. We'll update this section as needed.
This project follows the same guidelines as the Microsoft Code Of Conduct, but to escalate issues, please use GitHub Issues, as this project isn't affiliated directly with Microsoft, and issues shouldn't be raised through Microsoft's line of support.
Cutting a Release
To create a release, create a tag locally, and push it to GitHub. Actions and Dockerhub will do the rest! β¨
git tag vx.x.x
git push --tags
Generating Mocks
We use mockgen to generate mocks, that are then checked in. To re-generate them:
cd internal/app/mon && mockgen -destination ./mocks/dockerd.go . DockerAPI