mirror of
https://github.com/gyptazy/ProxLB.git
synced 2026-04-06 04:41:58 +02:00
release: Create release 1.1.0
- Create release 1.1.0 content - Add documentation for release 1.1.0 - Adjust changelog Fixes: #114 Fixes: #154 Sponsored-by: credativ GmbH (https://credativ.de)
This commit is contained in:
gyptazy
@@ -1,6 +1,5 @@
|
||||
fixed:
|
||||
- Refactored code base for ProxLB [#114]
|
||||
- Renamed package from `proxlb` to `python3-proxlb` to align with Debian packaging guidelines [#114]
|
||||
- Switched to `pycodestyle` for linting [#114]
|
||||
- Package building will be done within GitHub actions pipeline [#114]
|
||||
- ProxLB now only returns a warning when no guests for further balancing are not present (instead of quitting) [132#]
|
||||
@@ -9,4 +8,4 @@ fixed:
|
||||
- Stop balancing when movement would get worste (new force param to enfoce for affinity rules) [#128]
|
||||
- Added requested documentation regarding Proxmox HA groups [#127]
|
||||
- Rewrite of the whole affinity/anti-affinity rules evaluation and placement [#123]
|
||||
- Fixed the `ignore` parameter for nodes where the node and guests on the node will be untouched [#102]
|
||||
- Fixed the `ignore` parameter for nodes where the node and guests on the node will be untouched [#102]
|
||||
|
||||
@@ -1 +1 @@
|
||||
date: TBD
|
||||
date: 2025-04-01
|
||||
|
||||
140
CHANGELOG.md
Normal file
140
CHANGELOG.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
|
||||
## [1.1.0] - 2025-04-01
|
||||
|
||||
### Fixed
|
||||
|
||||
- Refactored code base for ProxLB [#114]
|
||||
- Switched to `pycodestyle` for linting [#114]
|
||||
- Package building will be done within GitHub actions pipeline [#114]
|
||||
- ProxLB now only returns a warning when no guests for further balancing are not present (instead of quitting) [132#]
|
||||
- All nodes (according to the free resources) will be used now [#130]
|
||||
- Fixed logging outputs where highest/lowest were mixed-up [#129]
|
||||
- Stop balancing when movement would get worste (new force param to enfoce for affinity rules) [#128]
|
||||
- Added requested documentation regarding Proxmox HA groups [#127]
|
||||
- Rewrite of the whole affinity/anti-affinity rules evaluation and placement [#123]
|
||||
- Fixed the `ignore` parameter for nodes where the node and guests on the node will be untouched [#102]
|
||||
|
||||
|
||||
## [1.0.6] - 2024-12-24
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix maintenance mode when using cli arg and config mode by using the merged list (by @CartCaved). [#119]
|
||||
- Fix that a scheduler time definition of 1 (int) gets wrongly interpreted as a bool (by @gyptazy). [#115]
|
||||
|
||||
|
||||
## [1.0.5] - 2024-10-30
|
||||
|
||||
### Changed
|
||||
|
||||
- Change docs to make bool usage in configs more clear (by @gyptazy). [#104]
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix node (and its objects) evaluation when not reachable, e.g., maintenance (by @gyptazy). [#107]
|
||||
- Fix migration from local disks (by @greenlogles). [#113]
|
||||
- Fix evaluation of maintenance mode where comparing list & string resulted in a crash (by @glitchvern). [#106]
|
||||
- Fix allowed values (add DEBUG, WARNING) for log verbosity (by @gyptazy). [#98]
|
||||
|
||||
|
||||
## [1.0.4] - 2024-10-11
|
||||
|
||||
### Added
|
||||
|
||||
- Add maintenance mode to evacuate a node and move workloads for other nodes in the cluster. [#58]
|
||||
- Add feature to make API timeout configureable. [#91]
|
||||
- Add version output cli arg. [#89]
|
||||
|
||||
### Changed
|
||||
|
||||
- Run storage balancing only on supported shared storages. [#79]
|
||||
- Run storage balancing only when needed to save time. [#79]
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix CPU balancing where calculations are done in float instead of int. (by @glitchvern) [#75]
|
||||
- Fix documentation for the underlying infrastructure. [#81]
|
||||
|
||||
|
||||
## [1.0.3] - 2024-09-12
|
||||
|
||||
### Added
|
||||
|
||||
- Add cli arg `-b` to return the next best node for next VM/CT placement. [#8]
|
||||
- Add a convert function to cast all bool alike options from configparser to bools. [#53]
|
||||
- Add a config parser options for future features. [#53]
|
||||
- Add a config versio schema that must be supported by ProxLB. [#53]
|
||||
- Add feature to allow the API hosts being provided as a comma separated list. [#60]
|
||||
- Add doc how to add dedicated user for authentication. (by @Dulux-Oz)
|
||||
- Add storage balancing function. [#51]
|
||||
|
||||
### Changed
|
||||
|
||||
- Provide a more reasonable output when HA services are not active in a Proxmox cluster. [#68]
|
||||
- Improve the underlying code base for future implementations. [#53]
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix anti-affinity rules not evaluating a new and different node. [#67]
|
||||
- Fixed `master_only` function by inverting the condition.
|
||||
- Fix documentation for the master_only parameter placed in the wrong config section. [#74]
|
||||
- Fix bug in the `proxlb.conf` in the vm_balancing section.
|
||||
- Fix handling of unset `ignore_nodes` and `ignore_vms` resulted in an attribute error. [#71]
|
||||
- Improved the overall validation and error handling. [#64]
|
||||
|
||||
|
||||
## [1.0.2] - 2024-08-13
|
||||
|
||||
### Added
|
||||
|
||||
- Add option to run ProxLB only on the Proxmox's master node in the cluster (reg. HA feature). [#40]
|
||||
- Add option to run migrations in parallel or sequentially. [#41]
|
||||
|
||||
### Changed
|
||||
|
||||
- Fix daemon timer to use hours instead of minutes. [#45]
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix CMake packaging for Debian package to avoid overwriting the config file. [#49]
|
||||
|
||||
|
||||
## [1.0.0] - 2024-08-01
|
||||
|
||||
### Added
|
||||
|
||||
- Add feature to prevent VMs from being relocated by defining the 'plb_ignore_vm' tag. [#7]
|
||||
- Add feature to prevent VMs from being relocated by defining a wildcard pattern. [#7]
|
||||
- Add Docker/Podman support. [#10 by @daanbosch]
|
||||
- Add option to rebalance by assigned VM resources to avoid overprovisioning. [#16]
|
||||
- Add feature to make log verbosity configurable [#17].
|
||||
- Add dry-run support to see what kind of rebalancing would be done. [#6]
|
||||
- Add LXC/Container integration. [#27]
|
||||
- Add exclude grouping feature to rebalance VMs from being located together to new nodes. [#4]
|
||||
- Add include grouping feature to rebalance VMs bundled to new nodes. [#3]
|
||||
- Add option_mode to rebalance by node's free resources in percent (instead of bytes). [#29]
|
||||
|
||||
### Changed
|
||||
|
||||
- Adjusted general logging and log more details.
|
||||
|
||||
|
||||
## [0.9.9] - 2024-07-06
|
||||
|
||||
### Added
|
||||
|
||||
- Initial public development release of ProxLB.
|
||||
|
||||
|
||||
## [0.9.0] - 2024-02-01
|
||||
|
||||
### Added
|
||||
|
||||
- Development release of ProxLB.
|
||||
151
README.md
151
README.md
@@ -4,10 +4,6 @@
|
||||
|
||||
<p float="center"><img src="https://img.shields.io/github/license/gyptazy/ProxLB"/><img src="https://img.shields.io/github/contributors/gyptazy/ProxLB"/><img src="https://img.shields.io/github/last-commit/gyptazy/ProxLB/main"/><img src="https://img.shields.io/github/issues-raw/gyptazy/ProxLB"/><img src="https://img.shields.io/github/issues-pr/gyptazy/ProxLB"/></p>
|
||||
|
||||
|
||||
# :warning: Important: ProxLB 1.1.x is coming
|
||||
This repository is currently under heavy work and changes. During that time it might come to issues, non working pipelines or wrong documentation. Please select a stable release tag for a suitable version during this time!
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Features](#features)
|
||||
@@ -15,26 +11,22 @@ This repository is currently under heavy work and changes. During that time it m
|
||||
4. [Installation](#installation)
|
||||
1. [Requirements / Dependencies](#requirements--dependencies)
|
||||
2. [Debian Package](#debian-package)
|
||||
3. [RedHat Package](#redhat-package)
|
||||
4. [Container / Docker](#container--docker)
|
||||
5. [Source](#source)
|
||||
5. [Upgrading](#upgrading)
|
||||
1. [Upgrading from < 1.1.0](#upgrading-from--110)
|
||||
2. [Upgrading from >= 1.1.0](#upgrading-from--110)
|
||||
6. [Usage / Configuration](#usage--configuration)
|
||||
5. [Usage / Configuration](#usage--configuration)
|
||||
1. [GUI Integration](#gui-integration)
|
||||
2. [Proxmox HA Integration](#proxmox-ha-integration)
|
||||
3. [Options](#options)
|
||||
7. [Affinity & Anti-Affinity Rules](#affinity--anti-affinity-rules)
|
||||
6. [Affinity & Anti-Affinity Rules](#affinity--anti-affinity-rules)
|
||||
1. [Affinity Rules](#affinity-rules)
|
||||
2. [Anti-Affinity Rules](#anti-affinity-rules)
|
||||
8. [Maintenance](#maintenance)
|
||||
9. [Misc](#misc)
|
||||
7. [Maintenance](#maintenance)
|
||||
8. [Misc](#misc)
|
||||
1. [Bugs](#bugs)
|
||||
2. [Contributing](#contributing)
|
||||
3. [Documentation](#documentation)
|
||||
4. [Support](#support)
|
||||
10. [Author(s)](#authors)
|
||||
9. [Author(s)](#authors)
|
||||
|
||||
|
||||
## Introduction
|
||||
@@ -94,23 +86,126 @@ The dependencies can simply be installed with `pip` by running the following com
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Distribution packages, such like the provided `.deb` package will automatically resolve and install all required dependencies by using already packaged version from the distribution's repository.
|
||||
*Note: Distribution packages, such like the provided `.deb` package will automatically resolve and install all required dependencies by using already packaged version from the distribution's repository. By using the Docker (container) image or Debian packages, you do not need to take any care of the requirements listed here.*
|
||||
|
||||
### Debian Package
|
||||
ProxLB is a powerful and flexible load balancer designed to work across various architectures, including `amd64`, `arm64`, `rv64` and many other ones that support Python. It runs independently of the underlying hardware, making it a versatile choice for different environments. This chapter covers the step-by-step process to install ProxLB on Debian-based systems, including Debian clones like Ubuntu.
|
||||
|
||||
### RedHat Package
|
||||
#### Quick-Start
|
||||
You can simply use this snippet to install the repository and to install ProxLB on your system.
|
||||
|
||||
### Container / Docker
|
||||
```bash
|
||||
echo "deb https://repo.gyptazy.com/stable /" > /etc/apt/sources.list.d/proxlb.list
|
||||
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
|
||||
apt-get update && apt-get -y install proxlb
|
||||
cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
|
||||
# Adjust the config to your needs
|
||||
vi /etc/proxlb/proxlb.yaml
|
||||
systemctl start proxlb
|
||||
```
|
||||
|
||||
Afterwards, ProxLB is running in the background and balances your cluster by your defined balancing method (default: memory).
|
||||
|
||||
#### Details
|
||||
ProxLB provides two different repositories:
|
||||
* https://repo.gyptazy.com/stable (only stable release)
|
||||
* https://repo.gyptazy.com/testing (bleeding edge - not recommended)
|
||||
|
||||
The repository is signed and the GPG key can be found at:
|
||||
* https://repo.gyptazy.com/repository.gpg
|
||||
|
||||
You can also simply import it by running:
|
||||
|
||||
```
|
||||
# KeyID: 17169F23F9F71A14AD49EDADDB51D3EB01824F4C
|
||||
# UID: gyptazy Solutions Repository <contact@gyptazy.com>
|
||||
# SHA256: 52c267e6f4ec799d40cdbdb29fa518533ac7942dab557fa4c217a76f90d6b0f3 repository.gpg
|
||||
|
||||
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
|
||||
```
|
||||
|
||||
*Note: The defined repositories `repo.gyptazy.com` and `repo.proxlb.de` are the same!*
|
||||
|
||||
#### Debian Packages (.deb files)
|
||||
If you do not want to use the repository you can also find the debian packages as a .deb file on gyptazy's CDN at:
|
||||
* https://cdn.gyptazy.com/files/os/debian/proxlb/
|
||||
|
||||
Afterwards, you can simply install the package by running:
|
||||
```bash
|
||||
dpkg -i proxlb_*.deb
|
||||
cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
|
||||
# Adjust the config to your needs
|
||||
vi /etc/proxlb/proxlb.yaml
|
||||
systemctl start proxlb
|
||||
```
|
||||
|
||||
### Container Images / Docker
|
||||
Using the ProxLB container images is straight forward and only requires you to mount the config file.
|
||||
|
||||
```bash
|
||||
# Pull the image
|
||||
docker pull cr.gyptazy.com/proxlb/proxlb:latest
|
||||
# Download the config
|
||||
wget -O proxlb.yaml https://raw.githubusercontent.com/gyptazy/ProxLB/refs/heads/main/config/proxlb_example.yaml
|
||||
# Adjust the config to your needs
|
||||
vi proxlb.yaml
|
||||
# Start the ProxLB container image with the ProxLB config
|
||||
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb
|
||||
```
|
||||
|
||||
*Note: ProxLB container images are officially only available at cr.proxlb.de and cr.gyptazy.com.*
|
||||
|
||||
#### Overview of Images
|
||||
| Version | Image |
|
||||
|------|:------:|
|
||||
| latest | cr.gyptazy.com/proxlb/proxlb:latest |
|
||||
| v1.1.0 | cr.gyptazy.com/proxlb/proxlb:v1.1.0 |
|
||||
| v1.0.6 | cr.gyptazy.com/proxlb/proxlb:v1.0.6 |
|
||||
| v1.0.5 | cr.gyptazy.com/proxlb/proxlb:v1.0.5 |
|
||||
| v1.0.4 | cr.gyptazy.com/proxlb/proxlb:v1.0.4 |
|
||||
| v1.0.3 | cr.gyptazy.com/proxlb/proxlb:v1.0.3 |
|
||||
| v1.0.2 | cr.gyptazy.com/proxlb/proxlb:v1.0.2 |
|
||||
| v1.0.0 | cr.gyptazy.com/proxlb/proxlb:v1.0.0 |
|
||||
| v0.9.9 | cr.gyptazy.com/proxlb/proxlb:v0.9.9 |
|
||||
|
||||
### Source
|
||||
ProxLB can also easily be used from the provided sources - for traditional systems but also as a Docker/Podman container image.
|
||||
|
||||
## Upgrading
|
||||
#### Traditional System
|
||||
Setting up and running ProxLB from the sources is simple and requires just a few commands. Ensure Python 3 and the Python dependencies are installed on your system, then run ProxLB using the following command:
|
||||
```bash
|
||||
git clone https://github.com/gyptazy/ProxLB.git
|
||||
cd ProxLB
|
||||
```
|
||||
|
||||
### Upgrading from < 1.1.0
|
||||
Upgrading ProxLB is not supported due to a fundamental redesign introduced in version 1.1.x. With this update, ProxLB transitioned from a monolithic application to a pure Python-style project, embracing a more modular and flexible architecture. This shift aimed to improve maintainability and extensibility while keeping up with modern development practices. Additionally, ProxLB moved away from traditional ini-style configuration files and adopted YAML for configuration management. This change simplifies configuration handling, reduces the need for extensive validation, and ensures better type casting, ultimately providing a more streamlined and user-friendly experience.
|
||||
Afterwards simply adjust the config file to your needs:
|
||||
```bash
|
||||
vi config/proxlb.yaml
|
||||
```
|
||||
|
||||
### Upgrading from >= 1.1.0
|
||||
Uprading within the current stable versions, starting from 1.1.0, will be possible in all supported ways.
|
||||
Start ProxLB by Python3 on the system:
|
||||
```bash
|
||||
python3 proxlb/main.py -c config/proxlb.yaml
|
||||
```
|
||||
|
||||
#### Container Image
|
||||
Creating a container image of ProxLB is straightforward using the provided Dockerfile. The Dockerfile simplifies the process by automating the setup and configuration required to get ProxLB running in an Alpine container. Simply follow the steps in the Dockerfile to build the image, ensuring all dependencies and configurations are correctly applied. For those looking for an even quicker setup, a ready-to-use ProxLB container image is also available, eliminating the need for manual building and allowing for immediate deployment.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/gyptazy/ProxLB.git
|
||||
cd ProxLB
|
||||
docker build -t proxlb .
|
||||
```
|
||||
|
||||
Afterwards simply adjust the config file to your needs:
|
||||
```bash
|
||||
vi config/proxlb.yaml
|
||||
```
|
||||
|
||||
Finally, start the created container.
|
||||
```bash
|
||||
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb
|
||||
```
|
||||
|
||||
## Usage / Configuration
|
||||
Running ProxLB is straightforward and versatile, as it only requires `Python3` and the `proxmoxer` library. This means ProxLB can be executed directly on a Proxmox node or on dedicated systems such as Debian, RedHat, or even FreeBSD, provided that the Proxmox API is accessible from the client running ProxLB. ProxLB can also run inside a Container - Docker or LXC - and is simply up to you.
|
||||
@@ -174,7 +269,7 @@ proxmox_api:
|
||||
#pass: crazyPassw0rd!
|
||||
token_id: proxlb
|
||||
token_secret: 430e308f-1337-1337-beef-1337beefcafe
|
||||
ssl_verification: False
|
||||
ssl_verification: True
|
||||
timeout: 10
|
||||
|
||||
proxmox_cluster:
|
||||
@@ -195,9 +290,9 @@ balancing:
|
||||
mode: assigned
|
||||
|
||||
service:
|
||||
daemon: False
|
||||
daemon: True
|
||||
schedule: 12
|
||||
log_level: DEBUG
|
||||
log_level: INFO
|
||||
```
|
||||
|
||||
### Parameters
|
||||
@@ -247,6 +342,14 @@ As a result, ProxLB will try to place the VMs with the `plb_anti_affinity_ntp` t
|
||||
|
||||
The `maintenance_nodes` option allows operators to designate one or more Proxmox nodes for maintenance mode. When a node is set to maintenance, no new guest workloads will be assigned to it, and all existing workloads will be migrated to other available nodes within the cluster. This process ensures that (anti)-affinity rules and resource availability are respected, preventing disruptions while maintaining optimal performance across the infrastructure.
|
||||
|
||||
### Adding / Removing Nodes from Maintenance
|
||||
Within the section `proxmox_cluster` you can define the key `maintenance_nodes` as a list object. Simply add/remove one or more nodes with their equal name in the cluster and restart the daemon.
|
||||
```
|
||||
proxmox_cluster:
|
||||
maintenance_nodes: ['virt66.example.com']
|
||||
```
|
||||
Afterwards, all guest objects will be moved to other nodes in the cluster by ensuring the best balancing.
|
||||
|
||||
## Misc
|
||||
### Bugs
|
||||
Bugs can be reported via the GitHub issue tracker [here](https://github.com/gyptazy/ProxLB/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.
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
# Table of Contents
|
||||
|
||||
- [Requirements](#requirements)
|
||||
- [Where To Run?](#where-to-run)
|
||||
|
||||
## Requirements
|
||||
ProxLB is a sophisticated load balancer designed to enhance the management and distribution of workloads within a Proxmox cluster. By fully utilizing the Proxmox API, ProxLB eliminates the need for additional SSH access, streamlining cluster management while maintaining robust security. This chapter outlines the general requirements necessary to deploy and operate ProxLB effectively.
|
||||
|
||||
### Proxmox Cluster Requirements
|
||||
To use ProxLB, you must have an existing Proxmox cluster consisting of at least two nodes. While traditional load balancers often struggle to manage minimal node configurations, ProxLB is optimized to provide efficient load distribution even in a two-node environment. The more nodes present in the cluster, the better ProxLB can optimize resource usage and manage workloads.
|
||||
|
||||
### ProxLB Package Requirements
|
||||
Next to the previously mentioned requirements, ProxLB also requires you to fit the following ones:
|
||||
* Python3.x
|
||||
* proxmoxer
|
||||
* requests
|
||||
* urllib3
|
||||
* pyyaml
|
||||
|
||||
### Seamless API Integration
|
||||
ProxLB relies exclusively on the Proxmox API for all management tasks. This eliminates the need for direct SSH access, ensuring a cleaner and more secure interaction with the cluster. The API integration allows ProxLB to:
|
||||
|
||||
- Monitor cluster health and node resource utilization
|
||||
- Migrate virtual machines (VMs) and containers as needed
|
||||
- Manage storage utilization and distribution
|
||||
- Implement load balancing policies
|
||||
|
||||
### Authentication and Security Standards
|
||||
ProxLB fully supports Proxmox’s integrated user management system, providing robust authentication and access control. Key features include:
|
||||
|
||||
- **Multi-Factor Authentication (MFA):** Enhances security by requiring multiple verification methods.
|
||||
- **API Key Support:** ProxLB can utilize API keys for authentication instead of traditional username/password combinations, minimizing exposure to credentials.
|
||||
- **Role-Based Access Control (RBAC):** Ensures administrators have fine-grained control over user permissions.
|
||||
|
||||
### Flexible Storage Support
|
||||
ProxLB offers versatile storage management options, supporting both local and shared storage types. It efficiently balances storage workloads across the cluster using the following storage systems:
|
||||
|
||||
- **Local Storage:** Direct-attached storage on each node.
|
||||
- **Shared Storage:** Includes options like iSCSI, NVMeOF, and NFS for centralized storage solutions.
|
||||
- **Ceph:** Integrated support for Ceph distributed storage, providing high availability and fault tolerance.
|
||||
|
||||
### Network Infrastructure Requirements
|
||||
For optimal performance, ProxLB requires a reliable and high-speed network connection between the nodes in the cluster. Ensure that the network infrastructure meets the following criteria:
|
||||
|
||||
- **Low Latency:** Essential for real-time load balancing and VM migration.
|
||||
- **Sufficient Bandwidth:** Adequate to handle storage access, data replication, and migration traffic.
|
||||
- **Redundant Network Paths:** Recommended for increased fault tolerance and uptime.
|
||||
|
||||
### System Resource Allocation
|
||||
ProxLB itself requires minimal system resources to operate. However, for managing larger clusters or high workloads, ensure the node running ProxLB has adequate resources available:
|
||||
|
||||
- **CPU:** A modern multi-core processor.
|
||||
- **Memory:** At least 2 GB of RAM.
|
||||
- **Storage:** Minimal disk space for configuration files and logs.
|
||||
|
||||
|
||||
## Where To Run?
|
||||
ProxLB can run on pretty anthing and only requires you to have a network connectivity to any of the Proxmox host's API (usually on tcp/8006).
|
||||
|
||||
Therefore, you can simply run ProxLB on:
|
||||
* Bare-metal Systems
|
||||
* VMs (even inside the Proxmox cluster)
|
||||
* Docker/Podman Container
|
||||
* LXC Container
|
||||
* On a Proxmox node
|
||||
@@ -0,0 +1,164 @@
|
||||
# Table of Contents
|
||||
|
||||
- [Installation](#installation)
|
||||
- [Requirements / Dependencies](#requirements--dependencies)
|
||||
- [Debian Package](#debian-package)
|
||||
- [Quick-Start](#quick-start)
|
||||
- [Details](#details)
|
||||
- [Debian Packages (.deb files)](#debian-packages-deb-files)
|
||||
- [RedHat Package](#redhat-package)
|
||||
- [Container Images / Docker](#container-images--docker)
|
||||
- [Overview of Images](#overview-of-images)
|
||||
- [Source](#source)
|
||||
- [Traditional System](#traditional-system)
|
||||
- [Container Image](#container-image)
|
||||
- [Upgrading](#upgrading)
|
||||
- [Upgrading from < 1.1.0](#upgrading-from--110)
|
||||
- [Upgrading from >= 1.1.0](#upgrading-from--110)
|
||||
|
||||
|
||||
## Installation
|
||||
### Requirements / Dependencies
|
||||
* Python3.x
|
||||
* proxmoxer
|
||||
* requests
|
||||
* urllib3
|
||||
* pyyaml
|
||||
|
||||
The dependencies can simply be installed with `pip` by running the following command:
|
||||
```
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
*Note: Distribution packages, such like the provided `.deb` package will automatically resolve and install all required dependencies by using already packaged version from the distribution's repository. By using the Docker (container) image or Debian packages, you do not need to take any care of the requirements listed here.*
|
||||
|
||||
### Debian Package
|
||||
ProxLB is a powerful and flexible load balancer designed to work across various architectures, including `amd64`, `arm64`, `rv64` and many other ones that support Python. It runs independently of the underlying hardware, making it a versatile choice for different environments. This chapter covers the step-by-step process to install ProxLB on Debian-based systems, including Debian clones like Ubuntu.
|
||||
|
||||
#### Quick-Start
|
||||
You can simply use this snippet to install the repository and to install ProxLB on your system.
|
||||
|
||||
```bash
|
||||
echo "deb https://repo.gyptazy.com/stable /" > /etc/apt/sources.list.d/proxlb.list
|
||||
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
|
||||
apt-get update && apt-get -y install proxlb
|
||||
cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
|
||||
# Adjust the config to your needs
|
||||
vi /etc/proxlb/proxlb.yaml
|
||||
systemctl start proxlb
|
||||
```
|
||||
|
||||
Afterwards, ProxLB is running in the background and balances your cluster by your defined balancing method (default: memory).
|
||||
|
||||
#### Details
|
||||
ProxLB provides two different repositories:
|
||||
* https://repo.gyptazy.com/stable (only stable release)
|
||||
* https://repo.gyptazy.com/testing (bleeding edge - not recommended)
|
||||
|
||||
The repository is signed and the GPG key can be found at:
|
||||
* https://repo.gyptazy.com/repository.gpg
|
||||
|
||||
You can also simply import it by running:
|
||||
|
||||
```
|
||||
# KeyID: 17169F23F9F71A14AD49EDADDB51D3EB01824F4C
|
||||
# UID: gyptazy Solutions Repository <contact@gyptazy.com>
|
||||
# SHA256: 52c267e6f4ec799d40cdbdb29fa518533ac7942dab557fa4c217a76f90d6b0f3 repository.gpg
|
||||
|
||||
wget -O /etc/apt/trusted.gpg.d/proxlb.asc https://repo.gyptazy.com/repository.gpg
|
||||
```
|
||||
|
||||
*Note: The defined repositories `repo.gyptazy.com` and `repo.proxlb.de` are the same!*
|
||||
|
||||
#### Debian Packages (.deb files)
|
||||
If you do not want to use the repository you can also find the debian packages as a .deb file on gyptazy's CDN at:
|
||||
* https://cdn.gyptazy.com/files/os/debian/proxlb/
|
||||
|
||||
Afterwards, you can simply install the package by running:
|
||||
```bash
|
||||
dpkg -i proxlb_*.deb
|
||||
cp /etc/proxlb/proxlb_example.yaml /etc/proxlb/proxlb.yaml
|
||||
# Adjust the config to your needs
|
||||
vi /etc/proxlb/proxlb.yaml
|
||||
systemctl start proxlb
|
||||
```
|
||||
|
||||
### RedHat Package
|
||||
There's currently no official support for RedHat based systems. However, there's a dummy .rpm package for such systems in the pipeline which can be found here:
|
||||
* https://github.com/gyptazy/ProxLB/actions/workflows/20-pipeline-build-rpm-package.yml
|
||||
|
||||
|
||||
### Container Images / Docker
|
||||
Using the ProxLB container images is straight forward and only requires you to mount the config file.
|
||||
|
||||
```bash
|
||||
# Pull the image
|
||||
docker pull cr.gyptazy.com/proxlb/proxlb:latest
|
||||
# Download the config
|
||||
wget -O proxlb.yaml https://raw.githubusercontent.com/gyptazy/ProxLB/refs/heads/main/config/proxlb_example.yaml
|
||||
# Adjust the config to your needs
|
||||
vi proxlb.yaml
|
||||
# Start the ProxLB container image with the ProxLB config
|
||||
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb
|
||||
```
|
||||
|
||||
*Note: ProxLB container images are officially only available at cr.proxlb.de and cr.gyptazy.com.*
|
||||
|
||||
#### Overview of Images
|
||||
| Version | Image |
|
||||
|------|:------:|
|
||||
| latest | cr.gyptazy.com/proxlb/proxlb:latest |
|
||||
| v1.1.0 | cr.gyptazy.com/proxlb/proxlb:v1.1.0 |
|
||||
| v1.0.6 | cr.gyptazy.com/proxlb/proxlb:v1.0.6 |
|
||||
| v1.0.5 | cr.gyptazy.com/proxlb/proxlb:v1.0.5 |
|
||||
| v1.0.4 | cr.gyptazy.com/proxlb/proxlb:v1.0.4 |
|
||||
| v1.0.3 | cr.gyptazy.com/proxlb/proxlb:v1.0.3 |
|
||||
| v1.0.2 | cr.gyptazy.com/proxlb/proxlb:v1.0.2 |
|
||||
| v1.0.0 | cr.gyptazy.com/proxlb/proxlb:v1.0.0 |
|
||||
| v0.9.9 | cr.gyptazy.com/proxlb/proxlb:v0.9.9 |
|
||||
|
||||
### Source
|
||||
ProxLB can also easily be used from the provided sources - for traditional systems but also as a Docker/Podman container image.
|
||||
|
||||
#### Traditional System
|
||||
Setting up and running ProxLB from the sources is simple and requires just a few commands. Ensure Python 3 and the Python dependencies are installed on your system, then run ProxLB using the following command:
|
||||
```bash
|
||||
git clone https://github.com/gyptazy/ProxLB.git
|
||||
cd ProxLB
|
||||
```
|
||||
|
||||
Afterwards simply adjust the config file to your needs:
|
||||
```bash
|
||||
vi config/proxlb.yaml
|
||||
```
|
||||
|
||||
Start ProxLB by Python3 on the system:
|
||||
```bash
|
||||
python3 proxlb/main.py -c config/proxlb.yaml
|
||||
```
|
||||
|
||||
#### Container Image
|
||||
Creating a container image of ProxLB is straightforward using the provided Dockerfile. The Dockerfile simplifies the process by automating the setup and configuration required to get ProxLB running in an Alpine container. Simply follow the steps in the Dockerfile to build the image, ensuring all dependencies and configurations are correctly applied. For those looking for an even quicker setup, a ready-to-use ProxLB container image is also available, eliminating the need for manual building and allowing for immediate deployment.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/gyptazy/ProxLB.git
|
||||
cd ProxLB
|
||||
docker build -t proxlb .
|
||||
```
|
||||
|
||||
Afterwards simply adjust the config file to your needs:
|
||||
```bash
|
||||
vi config/proxlb.yaml
|
||||
```
|
||||
|
||||
Finally, start the created container.
|
||||
```bash
|
||||
docker run -it --rm -v $(pwd)/proxlb.yaml:/etc/proxlb/proxlb.yaml proxlb
|
||||
```
|
||||
|
||||
## Upgrading
|
||||
### Upgrading from < 1.1.0
|
||||
Upgrading ProxLB is not supported due to a fundamental redesign introduced in version 1.1.x. With this update, ProxLB transitioned from a monolithic application to a pure Python-style project, embracing a more modular and flexible architecture. This shift aimed to improve maintainability and extensibility while keeping up with modern development practices. Additionally, ProxLB moved away from traditional ini-style configuration files and adopted YAML for configuration management. This change simplifies configuration handling, reduces the need for extensive validation, and ensures better type casting, ultimately providing a more streamlined and user-friendly experience.
|
||||
|
||||
### Upgrading from >= 1.1.0
|
||||
Uprading within the current stable versions, starting from 1.1.0, will be possible in all supported ways.
|
||||
@@ -1,6 +1,6 @@
|
||||
#!/usr/bin/env bash
|
||||
VERSION="1.1.0-alpha"
|
||||
VERSION="1.1.0"
|
||||
|
||||
sed -i "s/^__version__ = .*/__version__ = \"$VERSION\"/" "proxlb/utils/version.py"
|
||||
sed -i "s/version=\"[0-9]*\.[0-9]*\.[0-9]*\"/version=\"$VERSION\"/" setup.py
|
||||
echo "OK: Versions have been sucessfully set to $VERSION"
|
||||
echo "OK: Versions have been sucessfully set to $VERSION"
|
||||
|
||||
@@ -3,5 +3,5 @@ __app_desc__ = "A DRS alike loadbalancer for Proxmox clusters."
|
||||
__author__ = "Florian Paul Azim Hoberg <gyptazy>"
|
||||
__copyright__ = "Copyright (C) 2025 Florian Paul Azim Hoberg (@gyptazy)"
|
||||
__license__ = "GPL-3.0"
|
||||
__version__ = "1.1.0-alpha"
|
||||
__version__ = "1.1.0"
|
||||
__url__ = "https://github.com/gyptazy/ProxLB"
|
||||
|
||||
2
setup.py
2
setup.py
@@ -2,7 +2,7 @@ from setuptools import setup
|
||||
|
||||
setup(
|
||||
name="proxlb",
|
||||
version="1.1.0-alpha",
|
||||
version="1.1.0",
|
||||
description="A DRS alike loadbalancer for Proxmox clusters.",
|
||||
long_description="An advanced DRS alike loadbalancer for Proxmox clusters that also supports maintenance modes and affinity/anti-affinity rules.",
|
||||
author="Florian Paul Azim Hoberg",
|
||||
|
||||
Reference in New Issue
Block a user