Ansible role: glances

Deploys the Glances web UI as a Docker container, using the official nicolargo/glances image and the community.docker collection.

What the role does

1. Installs the Docker SDK for Python (python3-docker) on the target, as required by community.docker.
2. Templates glances.conf to /etc/glances/ on the host.
3. Optionally installs a pre-generated password file to enable authentication.
4. Pulls the image and runs the glances container in web-server mode (-w) with a restart policy, host PID namespace, and (optionally) the Docker socket mounted read-only.
5. Optionally adds a ufw or firewalld rule.
6. Checks that the web UI answers on the published port.

Set glances_state: absent to remove the container.

Requirements

• Ansible 2.14+ on the control node

• Docker Engine already installed and running on the target. The role does not install Docker itself.

• A Debian/Ubuntu or RHEL-family target (for the python3-docker package; set glances_install_docker_sdk: false if you manage the SDK yourself)

• Root access on the target (become: true)

• Collections (install with the bundled requirements file):

  ansible-galaxy collection install -r examples/requirements.yml
  

Installation

Unzip the archive into your project's roles/ directory so the result is roles/glances/:

unzip glances-role.zip -d roles/

Quick start

- name: Deploy Glances web UI (Docker)
  hosts: monitored
  become: true
  roles:
    - role: glances

ansible-playbook -i inventory.ini playbook.yml

Then open http://<host>:61208/. A complete example is in examples/playbook.yml.

Role variables

All variables are in defaults/main.yml.

Variable	Default	Description
glances_image	nicolargo/glances	Container image.
glances_image_tag	latest-full	Image tag. Pin a release (e.g. 4.3.1-full) for reproducible deploys.
glances_pull_image	true	Pull the image on every run.
glances_container_name	glances	Container name.
glances_restart_policy	unless-stopped	Docker restart policy.
glances_install_docker_sdk	true	Install python3-docker on the target.
glances_bind_address	0.0.0.0	Host address the port is published on.
glances_port	61208	Host TCP port (maps to 61208 in the container).
glances_extra_args	[]	Extra Glances CLI arguments, e.g. ["--disable-plugin", "sensors"].
glances_timezone	UTC	IANA time zone for the container (e.g. America/Toronto).
glances_pid_host	true	Share the host PID namespace to see host processes.
glances_mount_docker_socket	true	Mount the Docker socket read-only to monitor containers.
glances_docker_socket	/var/run/docker.sock	Host path of the Docker socket.
glances_username	glances	Username when authentication is enabled.
glances_password_file	""	Control-node path to a pre-generated .pwd file. Empty means no auth.
glances_config_dir	/etc/glances	Host directory for glances.conf (and the .pwd file).
glances_refresh	2	Refresh interval in seconds.
glances_max_processes_display	30	Rows in the process list.
glances_extra_config	""	Raw INI appended to glances.conf.
glances_manage_firewall	false	Manage ufw/firewalld rules (see the caveat below).
glances_firewall_type	ufw	ufw or firewalld.
glances_firewall_allowed_sources	[]	Allowed source CIDRs. Empty means any source.
glances_state	present	present deploys, absent removes the container.
glances_verify_service	true	Wait for the UI to answer after deploy.

Security notes

Authentication. Without a password file the web UI is unauthenticated and exposes process lists and system details to anyone who can reach the port. To enable authentication, generate the hashed password file once on any machine with Glances installed:

glances -w --username glances --password
# enter and confirm the password, then Ctrl-C once the server starts

Copy ~/.config/glances/glances.pwd into your project (for example files/glances.pwd) and set:

glances_username: glances
glances_password_file: files/glances.pwd

The file is mounted into the container at /root/.config/glances/<user>.pwd. Encrypt it with ansible-vault if it lives in a repository.

Docker publishes ports around ufw/firewalld. Docker adds its own iptables/nftables rules ahead of those managed by ufw and firewalld, so glances_manage_firewall may not actually restrict access to a published port. For reliable restriction, set glances_bind_address to a specific interface address (or 127.0.0.1 behind a reverse proxy), or filter in the DOCKER-USER chain.

Docker socket and host PID. Mounting the Docker socket (even read-only) and sharing the host PID namespace give the container broad visibility into the host. Disable them with glances_mount_docker_socket: false and glances_pid_host: false if you do not need container or host-process monitoring.

Troubleshooting

docker ps --filter name=glances
docker logs -f glances
curl -I http://localhost:61208/

Config or password-file changes restart the container automatically; changes to the image tag, ports, environment, or mounts recreate it.

The REST API is served on the same port (for example /api/4/cpu); see the Glances documentation for the available endpoints.

Layout

glances/
├── README.md
├── defaults/main.yml
├── tasks/main.yml
├── meta/main.yml
├── templates/glances.conf.j2
└── examples/
    ├── playbook.yml
    └── requirements.yml

License

MIT