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. The core package contains
no backends, so install it together with the plugins you need — all packages share
the same version number, so keep them in sync. waldur-site-agent-basic-username-management
provides the default username backend (base); include it unless the offering sets
another username_management_backend:
pip install waldur-site-agent waldur-site-agent-slurm waldur-site-agent-basic-username-management
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>
-m,--mode:order_process(default),report,membership_syncorevent_process-c,--config-file: path to the configuration file (defaultwaldur-site-agent-config.yamlin the working directory)
Command-line tools
| Command | Purpose |
|---|---|
waldur_site_agent |
Run the agent in one mode |
waldur_site_diagnostics |
Check the configuration, Waldur access and the order processing backend; see Validation for what it checks |
waldur_site_load_components |
Create the offering's components in Waldur from backend_components |
waldur_site_healthz |
Liveness (heartbeat age) and readiness (Waldur reachable) probe for containers |
waldur_site_create_homedirs |
Create home directories for the offering's users |
waldur_sync_offering_users |
Run username generation and state transitions for the offering users once |
waldur_sync_resource_limits |
Reconcile resource limits once — by default the backend's limits are written to Waldur |
waldur_site_test_order |
Generate an order from a template and run it through a mock (or, with --use-real-backend, the real) backend |
waldur_site_load_historical_usage |
Backfill historical usage into Waldur |
The utility commands accept -c for the configuration file like the agent does;
waldur_site_healthz spells it --config-file (plus --max-age, --heartbeat-path and
--liveness-only). Run any of them with --help.
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"}
The level is set by log_level in the configuration file (default INFO).
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)WALDUR_SITE_AGENT_RECONCILIATION_PERIOD_MINUTES:event_processreconciliation period (default 60)WALDUR_SITE_AGENT_STOMP_UNHEALTHY_AFTER_MINUTES: how long a STOMP consumer may stay down before liveness fails (default 15)WALDUR_SITE_AGENT_HEARTBEAT_PATH: liveness heartbeat file (default/tmp/waldur-site-agent-heartbeat)SENTRY_ENVIRONMENT: Sentry environment name
See Environment Variables for details.
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 - what is checked on load, which errors stop the agent, 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.8rc9
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.8rc9.tar.gz | 178.9 kB | Without provenance | Details for waldur_site_agent-1.0.8rc9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| waldur_site_agent-1.0.8rc9-py3-none-any.whl | Python 3 | none | any | Details for waldur_site_agent-1.0.8rc9-py3-none-any.whl |
Total release size: 385.1 kB
Release files / waldur_site_agent-1.0.8rc9.tar.gz
| Download URL | waldur_site_agent-1.0.8rc9.tar.gz |
|---|---|
| Size | 178.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c8f169f9b93cca5cb3ceab8f95e75d9c531d9f6b7df38ccfed35a6fd21ebfe31
|
|
BLAKE2b-256 checksum How to use checksums |
e07346c47bf368bc7020a2b570179575e4e7abe75e5e305f2d2620fc43a83017
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","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.8rc9-py3-none-any.whl
| Download URL | waldur_site_agent-1.0.8rc9-py3-none-any.whl |
|---|---|
| Size | 206.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c0a5376cf8115718714e764f78903d7055cbd9e1332ab5e0d53d579fd4875f9b
|
|
BLAKE2b-256 checksum How to use checksums |
79a2ae74b02a69a52427f482e632a77410b698666ed746b96f3cf8158d0abf42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","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.8rc9
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.