proxmox-resource-distributor 2.0
Program to distribute resources over Proxmox nodes.
License: MIT
Requires Python: >=3.6
Keywords: cyberfusion,proxmox

# Wish

* At Cyberfusion, we provide customers with services such as IMAP, POP, DNS and web hosting.
* Services run on multiple resources. That way, an outage on a single resource doesn't impact availability of the service.
* To ensure services stay available in case of physical component failure, resources belonging to the services should be spread over zones.

## Terminology

* Resources: Virtual Machines and Containers.

# Solution

Proxmox Resource Distributor expects three things to be done:

* Group Proxmox cluster nodes into zones. Zones are failure domains (e.g. a datacenter).
* Group service resources into pools. E.g. in case of a DNS cluster consisting of Virtual Machines `dns0`, `dns1` and `dns2`, add these Virtual Machines to the pool `dns`. Pools may be named anything.
* Add zones and pools to database (more information below).

Proxmox Resource Distributor makes sure resources in a pool run:

* On as many different nodes as possible.
* In as many different zones as possible.

... depending on the amount of nodes, resources and zones.

# What it does and does not do

## What it does

When Proxmox Resource Distributor determines resources should be migrated, two things happen:

* The program exits with [status code 78](https://www.freebsd.org/cgi/man.cgi?query=sysexits).
* The program outputs the names of pools with resources to migrate.

### Running in cron

Running Proxmox Resource Distributor in cron yields the following results:

* If no resources have to be migrated, nothing happens.
* If resources have to be migrated, `cron` should send mail.

## What it does not do

Proxmox Resource Distributor does not migrate resources automatically. Migrating resources automatically causes more problems than it solves. When running in cron, the administrator should monitor mail sent by `cron` and migrate resources manually.

# Usage

## Install

Install the package from PyPI:

    pip3 install proxmox-resource-distributor

## Configuration

### Environment

Add the following settings to the `.env` file. This file is relative to your working directory.

* `DATABASE_PATH`. Type: string. Default: `/var/lib/proxmox-resource-distributor.sqlite3`
* `PROXMOX_HOST`. Type: string. Default: `pve-test:8006`. If the port is omitted, it defaults to 8006. The port must be set to run the tests.
* `PROXMOX_USERNAME`. Type: string. Default: `guest`
* `PROXMOX_REALM`. Tyoe: string. Default: `pve`
* `PROXMOX_VERIFY_SSL`. Type: boolean. Default: `True`
* `EXCLUDE_POOLS_NAMES`. Type: JSON (e.g. `'["pool1", "pool2"]'`). Default: empty list, all pools are included.

These settings can be overridden by specifying them as environment variables.

### Secrets

* Create the directory `/etc/proxmox-resource-distributor` with secure permissions.
* Create the file `proxmox_password` with secure permissions.
* Place the password for the Proxmox user in it.

#### Permissions

The Proxmox user specified in the configuration should have the following privileges:

* `Pool.Allocate` on path `/pool`

## Create database

* Create the file specified in `DATABASE_PATH` with secure permissions.
* Copy `proxmox-resource-distributor.sqlite3` (can be found in the Git repository) to the path specified in `DATABASE_PATH`.

## Manage zones and nodes

Add zones with:

    proxmox-resource-distributor create-node --name=<name> --zone-name=<zone-name>

Add nodes with:

    proxmox-resource-distributor create-zone --name=<name>

Delete nodes with:

    proxmox-resource-distributor delete-node --name=<name>

Delete zones with:

    proxmox-resource-distributor delete-zone --name=<name>

# Tests

Unit tests are located in `tests/unit_tests`. Run them with pytest. The tests must be run from the project root.

**The database (at `DATABASE_PATH`) is removed after the tests were run. Set it to a volatile file.**