Waldur Site Agent
A stateless Python application that synchronizes data between Waldur Mastermind and service provider backends. Manages account creation, usage reporting, and membership synchronization across different cluster management systems.
Architecture
The agent uses a uv workspace architecture with pluggable backends:
- Core Package:
waldur-site-agent(base classes, common utilities) - Plugin Packages: Standalone backend implementations under
plugins/(see table below)
Agent Modes
order_process: Fetches orders from Waldur and manages backend resourcesreport: Reports usage data from backend to Waldurmembership_sync: Synchronizes user membershipsevent_process: Event-based processing using STOMP
Installation
The core agent and every plugin are published to PyPI. Install the core package plus the plugins you need — all packages share the same version number, so keep them in sync:
pip install waldur-site-agent waldur-site-agent-slurm
See the plugin table below for the full list of published packages.
For Kubernetes, released Helm charts are published to a chart repository hosted on GitHub Pages:
helm repo add waldur https://waldur.github.io/waldur-site-agent
helm repo update
helm search repo waldur/waldur-site-agent --versions
helm install waldur-site-agent waldur/waldur-site-agent
Release candidates are pre-release versions — add --devel to see and install
them. Configurable values are documented in the
chart README.
Usage
waldur_site_agent -m <mode> -c <config-file>
Logging
The agent emits structured logs in JSON format to stdout. This applies to both the core agent and CLI tools.
Example log entry:
{"event": "Running agent in order_process mode", "level": "info", "logger": "waldur_site_agent.backend", "timestamp": "2026-02-03T14:02:35.551020+00:00"}
CLI Arguments
-m,--mode: Agent mode (order_process,report,membership_sync,event_process)-c,--config-file: Path to configuration file
Environment Variables
WALDUR_SITE_AGENT_ORDER_PROCESS_PERIOD_MINUTES: Order processing period (default: 5)WALDUR_SITE_AGENT_REPORT_PERIOD_MINUTES: Reporting period (default: 30)WALDUR_SITE_AGENT_MEMBERSHIP_SYNC_PERIOD_MINUTES: Membership sync period (default: 5)SENTRY_ENVIRONMENT: Sentry environment name
Development
# Install dependencies
uv sync --all-packages
# Run tests
uv run pytest
# Format and lint code
uvx prek run --all-files
# Load components into Waldur
waldur_site_load_components -c <config-file>
Releasing
./scripts/release.sh 0.10.0
# Review the commit, then push:
git push origin main --tags
See the Releasing Guide for details on version bumping, changelog generation, and what CI does after you push.
Documentation
For operators deploying the agent:
- Quickstart - the fastest path from a fresh install to a running, verified agent
- Installation Guide
- Configuration Reference
- Configuration Validation - how config errors are reported, and how to read them
- Deployment Guide
- Upgrading Guide
- Username Management
- SLURM Usage Reporting Setup
For contributors:
Plugins
License
MIT License - see LICENCE file for details.
1 maintainer
Metadata
1 maintainer
Release files for waldur-site-agent 1.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| waldur_site_agent-1.0.7.tar.gz | 133.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| waldur_site_agent-1.0.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 290.4 kB
Release files / waldur_site_agent-1.0.7.tar.gz
| Download URL | waldur_site_agent-1.0.7.tar.gz |
|---|---|
| Size | 133.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4403d5410cebf9579764b78c5fb80d34634e6462e8aec5c06715cb1c649dab6
|
|
BLAKE2b-256 checksum How to use checksums |
bf75acfa6f7748c563b58c52e4cb4b2fbbd5c549ba9d9aa0c7f4b4c081dbacb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / waldur_site_agent-1.0.7-py3-none-any.whl
| Download URL | waldur_site_agent-1.0.7-py3-none-any.whl |
|---|---|
| Size | 157.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ac2c2051b9f2ca799567bf4c4792d045e01c9eb84558c76527199e2efc49634
|
|
BLAKE2b-256 checksum How to use checksums |
786261fd46b8b020d3fb6e25ad17cd9ab466e53927d9f4c37d57dc5a7a4f4ff9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
