docker-hostmetrics

Simple metrics from container's host.

0. Requirements

The host most be a Linux x64 and the Docker most be installed.

Install the Docker:

# Install Docker for the most common Linux distros
curl -sSL https://get.docker.com | sh

1. How to deploy

The hostmetrics need to access two directories from the host.

• /proc : Has information about the processes running in the related namespace and all childres.
• /sys : Has information about the devices managed by the kernel in the related namespace and all childres.

Environment Variables:

• ACCESS_KEY : If defined, turn this key required during the HTTP requests.
• ACCESS_IPS : If defined, restrict the source connections to those IPs. Each IP most my separated by one space.
• DEBUG : If defined, run server in development mode. If setted to true, enable verbose debug output.

1.1. Docker command

The easiest way to deploy the hostmetrics is creating a simple Docker container. Here is an example:

docker container run -d \
    --name hostmetrics \
    --restart unless-stopped \
    -p 80:5000 \
    -v /proc:/proc_host:ro \
    -v /sys:/sys_host:ro \
    -e ACCESS_KEY="myawesomepass" \ # OPTINAL
    -e ACCESS_IPS="127.0.0.1" \     # OPTINAL
    thenets/hostmetrics

1.2. Ansible Playbook

You can find an example of an Ansible Playbook at playbook-hostmetrics.yml.

2. Examples

2.1 Run without access control

This example run the hostmetrics without any access control. Pay attention that anyone with a route to the serve can access all API endpoints.

docker container run -d \
    --name hostmetrics \
    --restart unless-stopped \
    -p 80:5000 \
    -v /proc:/proc_host:ro \
    -v /sys:/sys_host:ro \
    thenets/hostmetrics

2.2 Run with access control

This example run the hostmetrics with two types of access control. The first one is the ACCESS_KEY, so you will need to pass this string to the HTTP method GET during the request (see more in "How to use"). The second one is the ACCESS_IPS that allows you the pass all the IPs that will access the server.

You can use only one access control method if you want.

docker container run -d \
    --name hostmetrics \
    --restart unless-stopped \
    -p 80:5000 \
    -v /proc:/proc_host:ro \
    -v /sys:/sys_host:ro \
    -e ACCESS_KEY="myawesomepass" \
    -e ACCESS_IPS="1.2.3.4 192.168.1.40 172.46.12.1" \
    thenets/hostmetrics

3. How to use

After deploy the server you can access thoses endpoints:

• http://myserver/metrics/cpu?key=myawesomepass
• http://myserver/metrics/ram?key=myawesomepass
• http://myserver/metrics/disk?key=myawesomepass
• http://myserver/metrics/network?key=myawesomepass
• http://myserver/metrics/services?key=myawesomepass

You don't need to pass the key if the ACCESS_KEY environment variable was not defined.

Development

To use the Makefile your Linux user id most be 1000 and your used most be part of the docker group.

Some commands for development:

# Add your user to the Docker group
# (most restart the computer)
usermod -aG docker MY_USER_HERE

# Build Docker image
make build

# Run unit tests
make unit-test

# Enter in the shell mode (inside the container)
make shell
#or
make shell-root

# Install the libs the dev mode
make shell
source ./venv/bin/activate
pip install -r requirements.txt

# Start servers binding the host files
make server-development
make server-production

# Start server reproducing production environment
make server-test

TODO

• Improve unit tests.
• Add Docker Compose file.
• Improve README file with more "How to use" examples.
• Add comments to the 'simplemetrics.py' lib.