How to Install and Configure Prometheus Proxmox VE Exporter for Proxmox monitoring

howto Oct 5, 2024

The Prometheus Proxmox VE Exporter is a tool that helps you monitor your Proxmox Virtual Environment (VE). Proxmox VE is a platform for running virtual machines and containers. This exporter collects important information about your system, like CPU usage, memory, disk space, and the health of your virtual machines.

In this guide, I'll walk you through the steps to set up the Prometheus Proxmox VE Exporter and use Grafana to display the dashboard.

Prerequisites

Before you begin, ensure you have the following:

Proxmox VE is installed and accessible. I'm using version 8.2.4 as of now
Prometheus and Grafana are already set up and running (e.g., using Docker Compose). Will create a guide for this soon
You have sudo/root access to your Proxmox VE instance.
Familiarity with basic Linux commands and Proxmox VE API.

Assumptions

A basic understanding of Proxmox VE and its API is assumed.
Prometheus is ready to scrape the metrics from the exporter once set up.
The Docker Compose files used to set up Prometheus and Grafana are not included here, but it is assumed you've already created and launched containers for both.

Create a Proxmox VE API User

First, log into your Proxmox shell and create a user that Prometheus will use to access the API.

Create the API user and set up a dummy password. We'll be creating a token instead

pveum user add pve-exporter@pve -password "password"

Assign API permissions:

This command gives the user read-only permissions, which is sufficient for exporting metrics.

pveum acl modify / -user pve-exporter@pve -role PVEAuditor

Validate Permissions

As an additional step, please validate permissions through the GUI. It should look like the screenshot below. I had some issues with permissions when trying to start the service initially and had to re-check this. You may have to assign it manually.

Create a Linux User for Exporter

Next, we'll create a local Linux user without login privileges, specifically for running the exporter service. This step creates a local Linux user called pve-exporter to run the exporter service on your Proxmox VE machine.

useradd -s /bin/false pve-exporter

The -s /bin/false option ensures that this user cannot log in interactively.

Set Up Python Virtual Environment

Before installing the exporter, you need a Python virtual environment to manage its dependencies.

A Python virtual environment is being created to isolate the Python dependencies needed to run the Prometheus Proxmox VE Exporter.

This ensures that other Python packages installed on the server do not conflict with the exporter’s dependencies.

Update your package list:

apt update

Install the required Python package

apt install -y python3-venv

Create a virtual environment

python3 -m venv /opt/prometheus-pve-exporter

This command sets up a virtual environment at /opt/prometheus-pve-exporter, where Prometheus exporter will be installed.

Itcreates an isolated environment where:

Specific versions of Python packages can be installed.
The system's global Python installation and packages remain unaffected.

Install Prometheus Proxmox VE Exporter

Activate the virtual environment:

source /opt/prometheus-pve-exporter/bin/activate

Install the exporter:

The exporter is a Python package that knows how to fetch metrics from the Proxmox VE API and expose them in a format Prometheus understands.

pip install prometheus-pve-exporter

Deactivate the virtual environment (once the installation is done):

deactivate

Create API token

Create the token through GUI or Shell

GUI:

Navigate to Proxmox GUI > Permissions > API Tokens > Add

Type in exporter in Token ID and click Add. Copy the Secret and save it

Shell:

pveum user token add pve-exporter@pve exporter --comment "Token for monitoring"

Create Configuration Files

Exporter Configuration File

We need to configure the exporter with the API user details created earlier.

Create the config directory:

mkdir /etc/pve_exporter

Create the configuration file:

cat< /etc/pve_exporter/config.yaml
default:
  user: pve-exporter@pve
  token_name: exporter   # Token name created in the first step
  token_value: d95f76a3-07c3-4a7c-a # Secret Token created in the first step
  verify_ssl: false 
EOF

Make sure to replace token_value with your actual token value from the Create API Token Step.

PVE Exporter Environment Configuration

Next, configure the exporter service to bind to a specific IP address and port.

Create the environment configuration file:

cat< /etc/default/pve_exporter
CONFIG_FILE=/etc/pve_exporter/config.yaml
LISTEN_ADDR=192.168.0.46 # Replace with your PVE exporter's IP address
LISTEN_PORT=9221
EOF

Create Systemd Service

We’ll now set up a systemd service to manage the exporter. A systemd service is created to ensure that the exporter runs as a background service on the server. This service will use the previously created environment file and config files to run the exporter on port 9221.

Create the systemd service file:

cat< /etc/systemd/system/pve_exporter.service
[Unit]
Description=PVE Exporter
Wants=network-online.target
After=network-online.target

[Service]
User=pve-exporter
Type=simple
EnvironmentFile=/etc/default/pve_exporter
ExecStart=/opt/prometheus-pve-exporter/bin/pve_exporter --config.file=/etc/pve_exporter/config.yaml --web.listen-address=192.168.0.46:9221

[Install]
WantedBy=multi-user.target
EOF

Enable and start the service:

systemctl daemon-reload
  systemctl enable --now pve_exporter

Check the service status:

systemctl status pve_exporter.service

Testing the Exporter

Finally, you can test if the Prometheus Proxmox VE Exporter is running correctly by navigating to http://<LISTEN_ADDR>:9221/metrics in your browser or using

curl http://192.168.0.46:9221/metrics

You should see a list of metrics in plain text format. If everything is working, you’re ready to start monitoring your Proxmox VE with Prometheus!

curl --silent http://192.168.0.46:9221/pve | grep pve_version_info

Import Grafana Dashboard

Log in to your Grafana instance, navigate to Dashboards, click on the Import button, and enter the dashboard ID 10347. Then, click Load.

You can find the dashboard at: https://grafana.com/grafana/dashboards/10347.

Once imported, you should start seeing data in Grafana. Keep in mind that it may take a little time for Prometheus to collect and display the metrics.