Skip to content

Commit ca18334

Browse files
gyptazygyptazy
authored
Merge pull request #1 from gyptazy/release/0.9.0
release(0.9.9): Create initial test release
2 parents b1f8dcd + e3d0005 commit ca18334

20 files changed

+882
-2
lines changed

‎.changelogs/0.9.0/1_initial_release.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
added:
2+
- Development release of Proxmox Rebalancing Service

‎.changelogs/0.9.0/release_meta.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
date: 2024-02-01

‎.changelogs/0.9.9/1_initial_release.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
added:
2+
- Initial public development release of Proxmox Rebalancing Service

‎.changelogs/0.9.9/release_meta.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
date: 2024-07-06

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
dev/

‎README.md

Lines changed: 169 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,169 @@
1-
# proxmox-rebalancing-service
2-
Rebalancing VM workloads across nodes within a Proxmox cluster.
1+
# Proxmox Rebalancing Service
2+
<img align="left" src="https://cdn.gyptazy.ch/images/proxmox-rebalancing-service-gyptazy-text.jpg"/>
3+
<br>
4+
5+
<p float="center"><img src="https://img.shields.io/github/license/gyptazy/proxmox-rebalancing-service"/><img src="https://img.shields.io/github/contributors/gyptazy/proxmox-rebalancing-service"/><img src="https://img.shields.io/github/last-commit/gyptazy/proxmox-rebalancing-service/main"/><img src="https://img.shields.io/github/issues-raw/gyptazy/proxmox-rebalancing-service"/><img src="https://img.shields.io/github/issues-pr/gyptazy/proxmox-rebalancing-service"/></p>
6+
7+
8+
## Table of Content
9+
* Introduction
10+
* Video of Migration
11+
* Features
12+
* Usage
13+
* Dependencies
14+
* Options
15+
* Parameters
16+
* Systemd
17+
* Manuel
18+
* Proxmox GUI Integration
19+
* Quick Start
20+
* Motivation
21+
* References
22+
* Packages
23+
* Misc
24+
* Bugs
25+
* Contributing
26+
* Author(s)
27+
28+
## Introduction
29+
The `Proxmox Rebalancing Service` (PRS) is an advanced tool designed to enhance the efficiency and performance of Proxmox clusters by optimizing the distribution of virtual machines (VMs) across the cluster nodes by using the Proxmox API. PRS meticulously gathers and analyzes a comprehensive set of resource metrics from both the cluster nodes and the running VMs. These metrics include CPU usage, memory consumption, and disk utilization, specifically focusing on local disk resources.
30+
31+
PRS collects resource usage data from each node in the Proxmox cluster, including CPU, (local) disk and memory utilization. Additionally, it gathers resource usage statistics from all running VMs, ensuring a granular understanding of the cluster's workload distribution.
32+
33+
Intelligent rebalancing is a key feature of PRS where it re-balances VMs based on their memory, disk or cpu usage, ensuring that no node is overburdened while others remain underutilized. The rebalancing capabilities of PRS significantly enhance cluster performance and reliability. By ensuring that resources are evenly distributed, PRS helps prevent any single node from becoming a performance bottleneck, improving the reliability and stability of the cluster. Efficient rebalancing leads to better utilization of available resources, potentially reducing the need for additional hardware investments and lowering operational costs.
34+
35+
Automated rebalancing reduces the need for manual actions, allowing operators to focus on other critical tasks, thereby increasing operational efficiency.
36+
37+
### Video of Migration
38+
<img src="https://cdn.gyptazy.ch/images/proxmox-rebalancing-service-gyptazy-video.gif"/>
39+
40+
## Features
41+
* Rebalance the cluster by:
42+
* Memory
43+
* Disk (only local storage)
44+
* CPU
45+
* Performing
46+
* Periodically
47+
* One-shot solution
48+
* Filter
49+
* Exclude nodes
50+
* Exclude virtual machines
51+
* Migrate VM workloads away (e.g. maintenance preparation)
52+
* Usage
53+
* One-Shot (one-shot)
54+
* Periodically (daemon)
55+
* Proxmox Web GUI Integration (optional)
56+
57+
## Usage
58+
Running PRS is easy and it runs almost everywhere since it just depends on Python3 and the proxmoxer library. Therefore, it can directly run on a Proxmox node, dedicated systems like Debian, RedHat, or even FreeBSD, as long as the API is reachable by the client running PRS.
59+
60+
### Dependencies
61+
* Python3
62+
* proxmoxer (Python module)
63+
64+
### Options
65+
The following options can be set in the `prs.conf` file:
66+
67+
| Option | Example | Description |
68+
|------|:------:|:------:|
69+
| api_host | hypervisor01.gyptazy.ch | Host or IP address of the remote Proxmox API. |
70+
| api_user | root@pam | Username for the API. |
71+
| api_pass | FooBar | Password for the API. |
72+
| verify_ssl | 1 | Validate SSL certificates (1) or ignore (0). (default: 1) |
73+
| method | memory | Defines the balancing method (default: memory) where you can use `memory`, `disk` or `cpu`. |
74+
| ignore_nodes | dummynode01,dummynode02 | Defines a comma separated list of nodes to exclude. |
75+
| ignore_vms | testvm01,testvm02 | Defines a comma separated list of VMs to exclude. |
76+
| daemon | 1 | Run as a daemon (1) or one-shot (0). (default: 1) |
77+
| schedule | 24 | Hours to rebalance in hours. (default: 24) |
78+
79+
An example of the configuration file looks like:
80+
```
81+
[proxmox]
82+
api_host: hypervisor01.gyptazy.ch
83+
api_user: root@pam
84+
api_pass: FooBar
85+
verify_ssl: 1
86+
[balancing]
87+
method: memory
88+
ignore_nodes: dummynode01,dummynode02
89+
ignore_vms: testvm01,testvm02
90+
[service]
91+
daemon: 1
92+
```
93+
94+
### Parameters
95+
The following options and parameters are currently supported:
96+
97+
| Option | Long Option | Description | Default |
98+
|------|:------:|------:|------:|
99+
| -c | --config | Path to a config file. | /etc/proxmox-rebalancing-service/prs.conf (default) |
100+
101+
### Systemd
102+
When installing a Linux distribution (such as .deb or .rpm) file, this will be shipped with a systemd unit file. The default configuration file will be sourced from `/etc/proxmox-rebalancing-service/prs.conf`.
103+
104+
| Unit Name | Options |
105+
|------|:------:|
106+
| proxmox-rebalancing-service | start, stop, status, restart |
107+
108+
### Manual
109+
A manual installation is possible and also supports BSD based systems. Proxmox Rebalancing Service relies on mainly two important files:
110+
* proxmox-rebalancing-service (Python Executable)
111+
* prs.conf (Config file)
112+
113+
The executable must be able to read the config file, if no dedicated config file is given by the `-c` argument, PRS tries to read it from `/etc/proxmox-rebalancing-service/prs.conf`.
114+
115+
### Proxmox GUI Integration
116+
<img align="left" src="https://cdn.gyptazy.ch/images/proxmox-rebalancing-service-GUI-integration.jpg"/> PRS can also be directly be used from the Proxmox Web UI by installing the optional package `pve-proxmox-rebalancing-service-ui` package which has a dependency on the `proxmox-rebalancing-service` package. For the Web UI integration, it requires to be installed (in addition) on the nodes on the cluster. Afterwards, a new menu item is present in the HA chapter called `Rebalancing`. This chapter provides two possibilities:
117+
* Rebalancing VM workloads
118+
* Migrate VM workloads away from a defined node (e.g. maintenance preparation)
119+
120+
### Quick Start
121+
The easiest way to get started is by using the ready-to-use packages that I provide on my CDN and to run it on a Linux Debian based system. This can also be one of the Proxmox nodes itself.
122+
123+
```
124+
wget https://cdn.gyptazy.ch/files/amd64/debian/proxmox-rebalancing-service/proxmox-rebalancing-service_0.9.9_amd64.deb
125+
dpkg -i proxmox-rebalancing-service-0.9.9.deb
126+
# Adjust your config
127+
vi /etc/proxmox-rebalancing-service/prs.conf
128+
systemctl restart proxmox-rebalancing-service
129+
systemctl status proxmox-rebalancing-service
130+
```
131+
132+
### Logging
133+
PRS uses the `SystemdHandler` for logging. You can find all your logs in your systemd unit log or in the journalctl.
134+
135+
## Motivation
136+
As a developer managing a cluster of virtual machines for my projects, I often encountered the challenge of resource imbalance. Nodes within the cluster would become unevenly loaded, with some nodes being overburdened while others remained underutilized. This imbalance led to inefficiencies, performance bottlenecks, and increased operational costs. Frustrated by the lack of an adequate solution to address this issue, I decided to develop the Proxmox Rebalancing Service (PRS) to ensure better resource distribution across my clusters.
137+
138+
My primary motivation for creating PRS stemmed from my work on my BoxyBSD project, where I consistently faced the difficulty of maintaining balanced nodes while running various VM workloads but also on my personal clusters. The absence of an efficient rebalancing mechanism made it challenging to achieve optimal performance and stability. Recognizing the necessity for a tool that could gather and analyze resource metrics from both the cluster nodes and the running VMs, I embarked on developing PRS.
139+
140+
PRS meticulously collects detailed resource usage data from each node in a Proxmox cluster, including CPU load, memory usage, and local disk space utilization. It also gathers comprehensive statistics from all running VMs, providing a granular understanding of the workload distribution. With this data, PRS intelligently redistributes VMs based on memory usage, local disk usage, and CPU usage. This ensures that no single node is overburdened, storage resources are evenly distributed, and the computational load is balanced, enhancing overall cluster performance.
141+
142+
As an advocate of the open-source philosophy, I believe in the power of community and collaboration. By sharing solutions like PRS, I aim to contribute to the collective knowledge and tools available to developers facing similar challenges. Open source fosters innovation, transparency, and mutual support, enabling developers to build on each other's work and create better solutions together.
143+
144+
Developing PRS was driven by a desire to solve a real problem I faced in my projects. However, the spirit behind this effort was to provide a valuable resource to the community. By open-sourcing PRS, I hope to help other developers manage their clusters more efficiently, optimize their resource usage, and reduce operational costs. Sharing this solution aligns with the core principles of open source, where the goal is not only to solve individual problems but also to contribute to the broader ecosystem.
145+
146+
## References
147+
Here you can find some overviews of references for and about the Proxmox Rebalancing Service.
148+
149+
| Description | Link |
150+
|------|:------:|
151+
| General introduction post to Proxmox Rebalancing Service | https://gyptazy.ch/blog/proxmox-rebalancing-service-rebalance-virtual-machines-across-nodes-in-a-cluster/ |
152+
| Howto install and use the Proxmox Rebalancing Service | https://gyptazy.ch/howtos/howto-install-and-use-the-proxmox-rebalancing-service-to-rebalance-resources-in-a-proxmox-cluster/ |
153+
154+
## Packages
155+
Ready to use packages can be found at:
156+
* https://cdn.gyptazy.ch/files/amd64/debian/proxmox-rebalancing-service/
157+
* https://cdn.gyptazy.ch/files/amd64/ubuntu/proxmox-rebalancing-service/
158+
* https://cdn.gyptazy.ch/files/amd64/redhat/proxmox-rebalancing-service/
159+
* https://cdn.gyptazy.ch/files/amd64/freebsd/proxmox-rebalancing-service/
160+
161+
## Misc
162+
### Bugs
163+
Bugs can be reported via the GitHub issue tracker [here](https://github.com/gyptazy/proxmox-rebalancing-service/issues). You may also report bugs via email or deliver PRs to fix them on your own. Therefore, you might also see the contributing chapter.
164+
165+
### Contributing
166+
Feel free to add further documentation, to adjust already existing one or to contribute with code. Please take care about the style guide and naming conventions.
167+
168+
### Author(s)
169+
* Florian Paul Azim Hoberg @gyptazy (https://gyptazy.ch)

‎docs/01_Installation.md

Whitespace-only changes.

‎docs/02_Configuration.md

Whitespace-only changes.

‎docs/03_FAQ.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## FAQ
2+
3+
### Could not import all dependencies
4+
PRS requires the Python library `proxmoxer`. This can simply be installed by the most
5+
system repositories. If you encounter this error message you simply need to install it.
6+
7+
8+
```
9+
# systemctl status proxmox-rebalancing-service
10+
x proxmox-rebalancing-service.service - Proxmox Rebalancing Service
11+
Loaded: loaded (/etc/systemd/system/proxmox-rebalancing-service.service; static)
12+
Active: failed (Result: exit-code) since Sat 2024-07-06 10:25:16 UTC; 1s ago
13+
Duration: 239ms
14+
Process: 7285 ExecStart=/usr/bin/proxmox-rebalancing-service -c /etc/proxmox-rebalancing-service/prs.conf (code=exited, status=2)
15+
Main PID: 7285 (code=exited, status=2)
16+
CPU: 129ms
17+
18+
Jul 06 10:25:16 build01 systemd[1]: Started proxmox-rebalancing-service.service - Proxmox Rebalancing Service.
19+
Jul 06 10:25:16 build01 proxmox-rebalancing-service[7285]: proxmox-rebalancing-service: Error: [python-imports]: Could not import all dependencies. Please install "proxmoxer".
20+
```
21+
22+
Debian/Ubuntu: apt-get install python3-proxmoxer
23+
If the package is not provided by your systems repository, you can also install it by running `pip3 install proxmoxer`.

‎packaging/01_package.sh

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/bin/bash
2+
apt-get install rpm cmake make
3+
4+
mkdir packages
5+
mkdir build
6+
cd build
7+
cmake ..
8+
cpack -G DEB .
9+
cpack -G RPM .
10+
cp *.deb ../packages
11+
cp *.rpm ../packages
12+
cd ..
13+
rm -rf build
14+
echo "Packages created. Packages can be found in directory: packages"

‎packaging/CMakeLists.txt

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
cmake_minimum_required(VERSION 3.16)
2+
project(proxmox-rebalancing-service VERSION 0.9.9)
3+
4+
install(PROGRAMS ../proxmox-rebalancing-service DESTINATION /bin)
5+
install(FILES ../prs.conf DESTINATION /etc/proxmox-rebalancing-service)
6+
install(FILES proxmox-rebalancing-service.service DESTINATION /etc/systemd/system)
7+
8+
# General
9+
set(CPACK_PACKAGE_NAME "proxmox-rebalancing-service")
10+
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/../LICENSE")
11+
set(CPACK_RESOURCE_FILE_README "${CMAKE_CURRENT_SOURCE_DIR}/../README.md")
12+
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Florian Paul Azim <gyptazy> Hoberg <gyptazy@gyptazy.ch>")
13+
set(CPACK_PACKAGE_CONTACT "Florian Paul Azim Hoberg <gyptazy@gyptazy.ch>")
14+
set(CPACK_PACKAGE_VENDOR "gyptazy")
15+
16+
# RPM packaging
17+
set(CPACK_PACKAGE_VERSION ${CMAKE_PROJECT_VERSION})
18+
set(CPACK_GENERATOR "RPM")
19+
set(CPACK_RPM_PACKAGE_ARCHITECTURE "amd64")
20+
set(CPACK_RPM_PACKAGE_SUMMARY "Proxmox Rebalancing Service - Rebalance VMs within a Proxmox cluster.")
21+
set(CPACK_RPM_PACKAGE_DESCRIPTION "Proxmox Rebalancing Service - Rebalance VMs within a Proxmox cluster.")
22+
set(CPACK_RPM_CHANGELOG_FILE "${CMAKE_CURRENT_SOURCE_DIR}/changelog_redhat")
23+
set(CPACK_PACKAGE_RELEASE 1)
24+
set(CPACK_RPM_PACKAGE_LICENSE "GPL 3.0")
25+
set(CPACK_RPM_PACKAGE_REQUIRES "python >= 3.2.0")
26+
27+
# DEB packaging
28+
set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
29+
set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE "amd64")
30+
set(CPACK_DEBIAN_PACKAGE_SUMMARY "Proxmox Rebalancing Service - Rebalance VMs within a Proxmox cluster.")
31+
set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "Proxmox Rebalancing Service - Rebalance VMs within a Proxmox cluster.")
32+
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/changelog_debian")
33+
set(CPACK_DEBIAN_PACKAGE_DEPENDS "python3")
34+
set(CPACK_DEBIAN_PACKAGE_LICENSE "GPL 3.0")
35+
36+
37+
# Install
38+
set(CPACK_PACKAGING_INSTALL_PREFIX ${CMAKE_INSTALL_PREFIX})
39+
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA "${CMAKE_CURRENT_SOURCE_DIR}/postinst")
40+
set(CPACK_RPM_POST_INSTALL_SCRIPT_FILE "${CMAKE_CURRENT_SOURCE_DIR}/postinst")
41+
include(CPack)

‎packaging/README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## Build packages
2+
Building the packages requires cmake, deb and rpm.
3+
For building packages, simly run the following commands:
4+
5+
```
6+
mkdir build
7+
cd build
8+
cmake ..
9+
cpack -G RPM .
10+
cpack -G DEB .
11+
```
12+
13+
When running on Debian/Ubuntu you can directly call `01_package.sh`
14+
to create your own packages.

‎packaging/changelog_debian

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
proxmox-rebalancing-service (0.9.0) unstable; urgency=low
2+
3+
* Initial release of Proxmox Rebalancing Service.
4+
5+
-- Florian Paul Azim Hoberg <gyptazy@gyptazy.ch> Sun, 07 Jul 2024 05:38:41 -0200

‎packaging/changelog_redhat

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
* Sun Jul 07 2024 Florian Paul Azim Hoberg <gyptazy@gyptazy.ch>
2+
- Initial release of Proxmox Rebalancing Service.

‎packaging/postinst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/bin/bash
2+
useradd -m prs
3+
chown prs:prs /etc/proxmox-rebalancing-service/prs.conf
4+
chmod 600 /etc/proxmox-rebalancing-service/prs.conf
5+
systemctl daemon-reload

‎packaging/proxmox-rebalancing-service.service

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[Unit]
2+
Description=Proxmox Rebalancing Service
3+
4+
[Service]
5+
ExecStart=/usr/bin/proxmox-rebalancing-service -c /etc/proxmox-rebalancing-service/prs.conf
6+
User=prs

0 commit comments

Comments
 (0)