Skip to content

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

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:

1
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:

1
2
3
4
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

1
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:

1
{"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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 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

1
2
3
./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:

For contributors:

Plugins

Plugin PyPI package Description
basic_username_management waldur-site-agent-basic-username-management Basic username management plugin
ceph-s3 waldur-site-agent-ceph-s3 Ceph S3 storage plugin (croit and RadosGW flavours)
cscs-dwdi waldur-site-agent-cscs-dwdi CSCS-DWDI reporting plugin
digitalocean waldur-site-agent-digitalocean DigitalOcean plugin
envoy-ai-gateway waldur-site-agent-envoy-ai-gateway Envoy AI Gateway (API keys + usage reporting) plugin
harbor waldur-site-agent-harbor Harbor container registry plugin
k8s-ut-namespace waldur-site-agent-k8s-ut-namespace Kubernetes UT ManagedNamespace plugin
keycloak-client waldur-site-agent-keycloak-client Shared Keycloak client for Waldur Site Agent plugins
ldap waldur-site-agent-ldap LDAP plugin
litellm waldur-site-agent-litellm LiteLLM (virtual key lifecycle + usage reporting) plugin
moab waldur-site-agent-moab MOAB plugin
mup waldur-site-agent-mup MUP plugin
nextcloud waldur-site-agent-nextcloud Nextcloud plugin
okd waldur-site-agent-okd OKD/OpenShift plugin
opennebula waldur-site-agent-opennebula OpenNebula VDC plugin
rancher waldur-site-agent-rancher Rancher plugin
rancher-kc-crd waldur-site-agent-rancher-kc-crd Rancher + Keycloak CRD-driven plugin
slurm waldur-site-agent-slurm SLURM plugin
waldur waldur-site-agent-waldur Waldur-to-Waldur federation plugin

License

MIT License - see LICENCE file for details.