This release is a pre-release and may not be stable for production use.
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 and pending resource API key commands 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.8rc6
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.8rc6.tar.gz | 157.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| waldur_site_agent-1.0.8rc6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 340.1 kB
Release files / waldur_site_agent-1.0.8rc6.tar.gz
| Download URL | waldur_site_agent-1.0.8rc6.tar.gz |
|---|---|
| Size | 157.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cd5df41b7bf84e93a0840f13dd7866a8468d950194dbcc84ac08cb78f40722e3
|
|
BLAKE2b-256 checksum How to use checksums |
0848919ba2d615f323f85b2bba58272cb5b8ff5b1cff062aa4086007665f1dd7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.22 {"installer":{"name":"uv","version":"0.12.22","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.8rc6-py3-none-any.whl
| Download URL | waldur_site_agent-1.0.8rc6-py3-none-any.whl |
|---|---|
| Size | 182.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e0569e0094c0d97dc931acdae5e806a65e6a52a528b6eb5252a04a7bef95ea1f
|
|
BLAKE2b-256 checksum How to use checksums |
6fdc4865a41d28215d382147066acc76f761ae3fb8c8fbc52db982473de4a837
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.22 {"installer":{"name":"uv","version":"0.12.22","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}
|
