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 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.8rc1
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.8rc1.tar.gz | 133.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| waldur_site_agent-1.0.8rc1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 291.4 kB
Release files / waldur_site_agent-1.0.8rc1.tar.gz
| Download URL | waldur_site_agent-1.0.8rc1.tar.gz |
|---|---|
| Size | 133.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49c45d317d9ce53fa3c320ca7518a1929e8a7b71d0189c512f1184c2635ed018
|
|
BLAKE2b-256 checksum How to use checksums |
281e5582b395b62063128bb70c6df3153d923f7521f5a407d58b00308a017eb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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.8rc1-py3-none-any.whl
| Download URL | waldur_site_agent-1.0.8rc1-py3-none-any.whl |
|---|---|
| Size | 157.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0276ac61a606d14a53a5fce69daf96d6dabecf228219d00294f69da24be948ba
|
|
BLAKE2b-256 checksum How to use checksums |
345d2a5c9f552a3d203b3e0609f092f3b5ad4222c413c25c7ca8b8e13cc6de4d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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}
|
