This repository contains the Monitor Docker component I developed for monitoring my Docker environment from Home-Assistant. It is inspired by the Sander Huisman Docker Monitor, where I switched mainly from threads to asyncio and put my own wishes/functionality in. Feel free to use the component and report bugs if you find them. If you want to contribute, please report a bug or pull request and I will reply as soon as possible.
The Monitor Docker allows you to monitor Docker and container statistics and turn on/off containers. It can connect to the Docker daemon locally or remotely. When Home Assistant is used within a Docker container, the Docker daemon should be mounted as follows -v /var/run/docker.sock:/var/run/docker.sock
.
Docker run Example
docker run -d \
... \
-v /var/run/docker.sock:/var/run/docker.sock \
homeassistant/home-assistant
docker-compose.yaml Example
services:
hass:
image: homeassistant/home-assistant
...
volumes:
- /var/run/docker.sock:/var/run/docker.sock
...
NOTE: Making /var/run/docker.sock
read-only has no effect, because it is a socket (and not file).
Raspberry Pi (Raspbian)
Using a Raspberry Pi with Raspbian it could happen no memory is reported. In such case the Docker API does not report it to Monitor Docker. Making the following changes, normally fixes the problem:
/boot/cmdline.txt
cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory
NOTE: Add the line to the existing line, do not replace it
Ubuntu / Debian
Also on Ubuntu/Debian it is possible no memory is shown, the following changes could solve your problem:
/etc/default/grub
GRUB_CMDLINE_LINUX_DEFAULT=""
to GRUB_CMDLINE_LINUX_DEFAULT="quiet cgroup_enable=memory swapaccount=1"
sudo update-grub
NOTE: This is untested, use at your risk
/var/run/docker.sock
to your Home Assistant container.custom_components/monitor_docker
to your <config dir>/custom_components
directory./var/run/docker.sock
to your Home Assistant container.To use the monitor_docker
in your installation, add the following to your configuration.yaml
file:
# Example configuration.yaml entry
monitor_docker:
- name: Docker
containers:
- appdaemon
- db-dsmr
- db-hass
- deconz
- dsmr
- hass
- influxdb
- mosquitto
- nodered
- unifi
rename:
appdaemon: AppDaemon
db-dsmr: "Database DSMR-Reader"
db-hass: Database Home Assistant
deconz: DeCONZ
dsmr: "DSMR-Reader"
hass: Home Assistant
influxdb: InfluxDB
mosquitto: Mosquitto
nodered: "Node-RED"
unifi: UniFi
monitored_conditions:
- version
- containers_running
- containers_total
- state
- status
- memory
Parameter | Type | Description |
---|---|---|
name | string (Required) | Client name of Docker daemon. Defaults to Docker . |
url | string (Optional) | Host URL of Docker daemon. Defaults to unix://var/run/docker.sock . Remote Docker daemon via TCP socket is also supported, use e.g. tcp://ip:2376 . Do NOT add a slash add the end, this will invalid the URL. For TLS support see Q&A section. SSH is not supported. |
scan_interval | time_period (Optional) | Update interval. Defaults to 10 seconds. |
certpath | string (Optional) | If TCP socket is used, you can define your Docker certificate path, forcing Monitor Docker to enable TLS. The filenames must be cert.pem and key.pem |
containers | list (Optional) | Array of containers to monitor. Defaults to all containers. |
containers_exclude | list (Optional) | Array of containers to be excluded from monitoring, when all containers are included. |
monitored_conditions | list (Optional) | Array of conditions to be monitored. Defaults to all conditions. |
rename | dictionary (Optional) | Dictionary of containers to rename. Renaming is done on the name in HA Lovelove, not the entity name (see rename_entity ). Default no renaming. |
rename_entity | boolean (Optional) | If rename is enabled, it changes the name in HA Loveloce, not the entity name. Enable this setting to also rename the entitu name (Default: False) |
sensorname | string (Optional) | Sensor string to format the name used in Home Assistant. Defaults to {name} {sensor} , where {name} is the container name and {sensor} is e.g. Memory, Status, Network speed Up |
switchname | string (Optional) | Switch string to format the name used in Home Assistant. Defaults to {name} , where {name} is the container name. |
switchenabled | boolean / list (Optional) | Enable/Disable the switch entity for containers (Default: True Enabled switch for all containers, False : Disabled switch for all containers). Or specify a list of containers for which to enable switch entities. |
buttonenabled | boolean (Optional) | Enable/Disable the button entity for containers (Default: False Enabled button for all containers, False : Disabled button for all containers). Or specify a list of containers for which to enable button entities. |
precision_cpu | integer (Optional) | Precision of CPU usage percentage (Default: 2) |
precision_memory_mb | integer (Optional) | Precision of memory usage in MB (Default: 2) |
precision_memory_percentage | integer (Optional) | Precision of memory usage in percentage (Default: 2) |
precision_network_kb | integer (Optional) | Precision of network bandwidth in kB (Default: 2) |
precision_network_mb | integer (Optional) | Precision of network usage in MB (Default: 2) |
Monitored Conditions | Description | Unit |
---|---|---|
version | Docker version | - |
containers_total | Total number of containers | - |
containers_running | Number of running containers | - |
containers_paused | Number of paused containers | - |
containers_stopped | Number of stopped containers | - |
containers_cpu_percentage | CPU Usage. The CPU usage depends on the number of CPU cores, e.g. if you have 8 cores, this value can have a maximum of 800% | % |
containers_1cpu_percentage | CPU Usage, between 0-100% | % |
containers_memory | Memory usage | MB |
containers_memory_percentage | Memory usage | % |
images | Number of images | - |
state | Container state. This is created, restarting, running, removing, paused, exited or dead | - |
status | Container status. E.g. Up 13 days, Up 5 hours, Exited (0) 11 hours ago | - |
health | Container health if available | - |
uptime | Container start time | - |
image | Container image | - |
cpu_percentage | CPU usage. The CPU usage depends on the number of CPU cores, e.g. if you have 8 cores, this value can have a maximum of 800% | % |
1cpu_percentage | CPU Usage, between 0-100% | % |
memory | Memory usage | MB |
memory_percentage | Memory usage | % |
network_speed_up | Network speed upstream | kB/s |
network_speed_down | Network speed downstream | kB/s |
network_total_up | Network total upstream | MB |
network_total_down | Network total downstream | MB |
allinone | This is a special condition and when used, it will only create 1 sensor per container with all the monitored conditions as attribute value. NOTE: If you use this sensor, all other sensors are NOT created, just 1 sensor | - |
It is possible to debug the Monitor Docker component, this can be done by adding the following lines to the configuration.yaml
file:
logger:
logs:
custom_components.monitor_docker: debug
Here are some possible questions/errors with their answers.
docker-socket-proxy
. Start this docker with the following docker-compose code. It exposes the socket over TCP and monitor_docker
can listen to it.
# Proxy the Docker sock so that we can pick up stats for HomeAssistant
services:
dockerproxy:
image: tecnativa/docker-socket-proxy
container_name: dockerproxy
privileged: true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
ports:
- 2375:2375
environment:
- BUILD=1
- COMMIT=1
- CONFIGS=1
- CONTAINERS=1
- DISTRIBUTION=1
- EXEC=1
- IMAGES=1
- INFO=1
- NETWORKS=1
- NODES=1
- PLUGINS=1
- SERVICES=1
- SESSSION=1
- SWARM=1
- POST=1
Add the following to your configuration.yaml
:
monitor_docker:
- name: Docker
url: tcp://<host_ip>:2375
Missing valid docker_host.Either DOCKER_HOST or local sockets are not available.
/var/run/docker.sock
aiodocker.exceptions.DockerError: DockerError(900, "Cannot connect to Docker Engine via tcp://10.0.0.1:2376...)
.docker -H tcp://10.0.0.1:2376 ps
if it works (replace 10.0.0.1
with your IP address). Also you can consult the following URL for more help: https://docs.docker.com/config/daemon/remote-access/tcp://ip:2376
and the environment variables DOCKER_TLS_VERIFY=1
and DOCKER_CERT_PATH=<path to your certificates>
need to be setservices:
hass:
image: homeassistant/home-assistant
...
volumes:
- /var/run/docker.sock:/var/run/docker.sock
# The files need to be named "cert.pem" and "key.pem"
- ./certs:/certs
environment:
- DOCKER_TLS_VERIFY=1
- DOCKER_CERT_PATH=/certs
...
# Example configuration.yaml entry
monitor_docker:
- name: Docker
containers:
...
- name: RemoteDocker
url: tcp://10.0.0.1:2376
containers:
...
NOTE: The integration supports multiple Docker instances, but you can only define 1 TLS configuration which is applied to all (thus you cannot mix TCP with and without TLS).
$ sudo usermod -a -G docker <user>
$ sudo reboot
socat
. The following URL may help you: https://serverfault.com/questions/127794/forward-local-port-or-socket-file-to-remote-socket-file/362833#362833Apache License 2.0