waldur-site-agent

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 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. 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_sync or event_process
• -c, --config-file: path to the configuration file (default waldur-site-agent-config.yaml in 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 | | 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.

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_process reconciliation 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:

• Architecture & Plugin Development
• Releasing Guide

Plugins

| Plugin | PyPI package | Description | | —— | ———— | ———– | | azure | waldur-site-agent-azure | Azure virtual machines plugin | | 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 | | ldap-client | waldur-site-agent-ldap-client | Shared LDAP client for Waldur Site Agent plugins | | ldap-roles | waldur-site-agent-ldap-roles | LDAP role-driven group membership sync 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.

This site is open source. Improve this page.