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 resources
• report: Reports usage data from backend to Waldur
• membership_sync: Synchronizes user memberships
• event_process: Event-based processing using STOMP

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
pre-commit 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

• Architecture & Plugin Development
• Installation Guide
• Configuration Reference
• Deployment Guide
• Username Management
• SLURM Usage Reporting Setup
• Releasing Guide

Plugins

Plugin	Description
basic_username_management	Basic username management plugin
croit-s3	Croit S3 storage plugin
cscs-dwdi	CSCS-DWDI reporting plugin
digitalocean	DigitalOcean plugin
harbor	Harbor container registry plugin
k8s-ut-namespace	Kubernetes UT ManagedNamespace plugin
keycloak-client	Shared Keycloak client for Waldur Site Agent plugins
ldap	LDAP plugin
moab	MOAB plugin
mup	MUP plugin
okd	OKD/OpenShift plugin
opennebula	OpenNebula VDC plugin
rancher	Rancher plugin
slurm	SLURM plugin
waldur	Waldur-to-Waldur federation plugin

License

MIT License - see LICENCE file for details.