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

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.8rc11

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.8rc11
File Size Uploaded Provenance Actions
waldur_site_agent-1.0.8rc11.tar.gz 181.8 kB Without provenance Details for waldur_site_agent-1.0.8rc11.tar.gz

Built distribution (wheel)

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

Total release size: 391.6 kB

Release files / waldur_site_agent-1.0.8rc11.tar.gz

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

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

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