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.
Metadata
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 | Provenance | Actions |
|---|---|---|---|---|
| waldur_site_agent-1.0.7.tar.gz | 133.0 kB | Without provenance | Details for waldur_site_agent-1.0.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| waldur_site_agent-1.0.7-py3-none-any.whl | Python 3 | none | any | Details for waldur_site_agent-1.0.7-py3-none-any.whl |
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}
|
Security for waldur-site-agent 1.0.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.