Skip to main content
Pre-release

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

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:

For contributors:

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.

Metadata

Release files for waldur-site-agent 1.0.8rc10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for waldur-site-agent 1.0.8rc10
File Size Uploaded Provenance Actions
waldur_site_agent-1.0.8rc10.tar.gz 179.3 kB Without provenance Details for waldur_site_agent-1.0.8rc10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for waldur-site-agent 1.0.8rc10
File Interpreter ABI Platform Actions
waldur_site_agent-1.0.8rc10-py3-none-any.whl Python 3 none any Details for waldur_site_agent-1.0.8rc10-py3-none-any.whl

Total release size: 385.8 kB

Release files / waldur_site_agent-1.0.8rc10.tar.gz

Download URL waldur_site_agent-1.0.8rc10.tar.gz
Size 179.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0d75d9fa8c5ea3e93e01de4ac27d3db9f6edef0cc991951164a5965d4f0143e0
BLAKE2b-256 checksum
How to use checksums
9a7b9747e8bcb26eaade6f2845eaebdb0588146b74ad0b81c01e24aa2549fd19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.8rc10-py3-none-any.whl

Download URL waldur_site_agent-1.0.8rc10-py3-none-any.whl
Size 206.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4c52684201b52e7651894fee9714438906802751aa40e7089303b9e573150d64
BLAKE2b-256 checksum
How to use checksums
0dc52f228e191575735e63a99bff004f30e3a70b3c46dfb672594989b03bf585
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","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.8rc10

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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page