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.
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)
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
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-managementSee 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-agentRelease candidates are pre-release versions — add --devel to see and install
them. Configurable values are documented in the
chart README.
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 | 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 |
waldur_site_export_plugin_catalogue |
Write the catalogue of installed plugins (roles, settings schemas, secret settings) that Waldur vendors; see Secret settings and roles |
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.
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).
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.
# 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>./scripts/release.sh 0.10.0
# Review the commit, then push:
git push origin main --tagsSee the Releasing Guide for details on version bumping, changelog generation, and what CI does after you push.
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:
MIT License - see LICENCE file for details.