waldur-site-agent

Configuration Reference

This document provides a complete reference for configuring Waldur Site Agent. It’s a reference, not a tutorial — if this is your first setup, start with the Quickstart instead and come back here once something needs a field this page covers but the Quickstart didn’t.

Required in every offering, regardless of backend: name, waldur_api_url, waldur_api_token, waldur_offering_uuid, a *_backend setting for each process you run (e.g. order_processing_backend), and at least one entry under backend_components. Everything else on this page — global settings, event processing, resource management, backend-specific backend_settings, and the ~15 optional component fields — has a working default and can be added when you actually need it.

Configuration File Structure

The agent uses a YAML configuration file (waldur-site-agent-config.yaml) with the following structure:

sentry_dsn: ""
timezone: "UTC"
offerings:
  - name: "Example Offering"
    # Offering-specific configuration...

Global Settings

sentry_dsn

elastic_apm_server_url

timezone

Note: Important when agent and Waldur are deployed in different timezones to prevent billing period mismatches at month boundaries.

Offering Configuration

Each offering in the offerings array represents a separate service offering.

Basic Settings

name

waldur_api_url

waldur_api_token

verify_ssl

waldur_offering_uuid

Backend Configuration

backend_type

Backend Selection

Configure which backends to use for different operations:

order_processing_backend: "slurm"    # Backend for order processing
membership_sync_backend: "slurm"     # Backend for membership syncing
reporting_backend: "slurm"           # Backend for usage reporting
username_management_backend: "base"  # Backend for username management

Available backends (via entry points):

Note: If a backend setting is omitted, that process won’t start for the offering.

Event Processing

stomp_enabled

stomp_membership_sync_enabled

websocket_use_tls

Resource Management

resource_import_enabled

Common Backend Settings

These settings can be used in backend_settings for any backend type.

check_backend_id_uniqueness

check_all_offerings

backend_id_max_retries

Account name generation vs. resource slug templates

The offering’s account_name_generation_policy plugin option (set in Waldur, not in the agent config) controls how the agent derives a resource’s backend ID (e.g. the SLURM account name):

Warning: account_name_generation_policy: project_slug and resource_slug_template are two mutually exclusive ways to make backend IDs unique. If you set both, the project_slug policy wins and appends its own counter on top of (and ignoring) your template — producing IDs like prefix-test-prj-01-2-31. If you use a resource_slug_template, leave account_name_generation_policy unset so the unique slug is used directly.

Backend-Specific Settings

SLURM Backend Settings

backend_settings:
  default_account: "root"                              # DefaultAccount= on user associations
  # root_account: "root"                               # Parent of top-tier customer account
  # default_account_policy: "common"                   # common (default) | individual | none
  customer_prefix: "hpc_"                              # Prefix for customer accounts
  project_prefix: "hpc_"                               # Prefix for project accounts
  allocation_prefix: "hpc_"                            # Prefix for allocation accounts
  qos_downscaled: "limited"                           # QoS for downscaled accounts
  qos_paused: "paused"                                # QoS for paused accounts
  qos_default: "normal"                               # Default QoS
  enable_user_homedir_account_creation: true         # Create home directories
  default_homedir_umask: "0077"                              # Umask for home directories

MOAB Backend Settings

backend_settings:
  default_account: "root"
  customer_prefix: "c_"
  project_prefix: "p_"
  allocation_prefix: "a_"
  enable_user_homedir_account_creation: true

MUP Backend Settings

backend_settings:
  # MUP-specific settings
  api_url: "https://mup.example.com/api/"
  api_token: "your-api-token"
  # Other MUP-specific configuration

Waldur Federation Backend Settings

The target_api_token user must be a customer owner (can be a non-SP customer separate from the offering’s service provider) and an ISD identity manager (is_identity_manager: true with managed_isds set). Access to the target offering’s users is granted via ISD overlap, not via OFFERING.MANAGER.

backend_settings:
  target_api_url: "https://waldur-b.example.com/api/"
  target_api_token: "token-for-waldur-b"  # customer owner + ISD manager
  target_offering_uuid: "offering-uuid-on-waldur-b"
  target_customer_uuid: "customer-uuid-on-waldur-b"
  user_match_field: "cuid"                   # cuid | email | username
  order_poll_timeout: 300                    # Max seconds for sync order completion
  order_poll_interval: 5                     # Seconds between sync order polls
  user_not_found_action: "warn"              # warn | fail
  identity_bridge_source: "isd:efp"          # ISD source for identity bridge
  user_resolve_method: "identity_bridge"     # identity_bridge | remote_eduteams | user_field
  role_mapping:                              # Optional: translate role names A -> B
    PROJECT.ADMIN: PROJECT.ADMIN
    PROJECT.MANAGER: PROJECT.MANAGER
  end_date_sync_direction: "bidirectional"   # a_to_b | b_to_a | bidirectional | disabled
  limit_sync_direction: "b_to_a"             # b_to_a (default) | disabled -- limit sync
  passthrough_attributes: []                 # Offering attribute keys forwarded verbatim to B
  fetch_consented_users_only: false          # Only sync users with data-sharing consent
  # Optional: target STOMP for instant async order completion
  # Requires target_offering_uuid to be a Marketplace.Slurm offering
  target_stomp_enabled: false

Backend Components

Define computing components tracked by the backend:

backend_components:
  cpu:
    measured_unit: "k-Hours"           # Waldur measured unit
    unit_factor: 60000                 # Conversion factor
    accounting_type: "usage"           # "usage", "limit", or "one"
    label: "CPU"                       # Display label in Waldur
  mem:
    limit: 10                          # Fixed limit amount
    measured_unit: "gb-Hours"
    unit_factor: 61440                 # 60 * 1024
    accounting_type: "usage"
    label: "RAM"

Component Settings

measured_unit

unit_factor

accounting_type

label

limit

description

min_value

max_value

max_available_limit

default_limit

limit_period

article_code

is_boolean

is_prepaid

min_prepaid_duration

max_prepaid_duration

prepaid_duration_step

min_renewal_duration

max_renewal_duration

renewal_duration_step

Prepaid Billing

Prepaid billing allows customers to pay upfront for a fixed capacity over a specified duration. Prepaid components use accounting_type: "one" which maps to Waldur’s ONE_TIME billing type and automatically sets is_prepaid: true.

When a component has accounting_type: "one", the following flow applies:

  1. Ordering: Customer orders a resource with limits and an end_date. Waldur validates the duration against component constraints.
  2. Upfront billing: Waldur creates a single invoice item for the full subscription period (limit × price × months).
  3. Backend enforcement: The site agent calculates GrpTRESMins = limit × duration_months × unit_factor and sets it on the SLURM account. This gives SLURM a cumulative budget cap for the subscription period.
  4. Limit changes: Customer can request more capacity. Waldur creates supplementary invoice items. The agent recalculates GrpTRESMins with the new limits and remaining duration.
  5. Renewal: Customer extends the subscription. The agent detects the new end_date and recalculates GrpTRESMins with the extended duration.
  6. Termination: When end_date is reached, Waldur automatically creates a TERMINATE order.

Backend-Specific Component Notes

SLURM: Supports cpu, mem, and other custom components

MOAB: Only supports deposit component

backend_components:
  deposit:
    measured_unit: "EUR"
    accounting_type: "limit"
    label: "Deposit (EUR)"

Environment Variables

Override configuration values using environment variables:

Agent Timing

Monitoring

Example Configurations

SLURM Cluster

sentry_dsn: ""
timezone: "UTC"
offerings:
  - name: "HPC SLURM Cluster"
    waldur_api_url: "https://waldur.example.com/api/"
    waldur_api_token: "your-api-token"
    verify_ssl: true
    waldur_offering_uuid: "uuid-from-waldur"

    order_processing_backend: "slurm"
    membership_sync_backend: "slurm"
    reporting_backend: "slurm"
    username_management_backend: "base"

    resource_import_enabled: true
    stomp_enabled: false

    backend_settings:
      default_account: "root"
      customer_prefix: "hpc_"
      project_prefix: "hpc_"
      allocation_prefix: "hpc_"
      qos_default: "normal"
      enable_user_homedir_account_creation: true
      default_homedir_umask: "0077"

    backend_components:
      cpu:
        measured_unit: "k-Hours"
        unit_factor: 60000
        accounting_type: "usage"
        label: "CPU"
      mem:
        measured_unit: "gb-Hours"
        unit_factor: 61440
        accounting_type: "usage"
        label: "RAM"

MOAB Cluster

offerings:
  - name: "MOAB Cluster"
    waldur_api_url: "https://waldur.example.com/api/"
    waldur_api_token: "your-api-token"
    waldur_offering_uuid: "uuid-from-waldur"

    order_processing_backend: "moab"
    membership_sync_backend: "moab"
    reporting_backend: "moab"
    username_management_backend: "base"

    backend_settings:
      default_account: "root"
      customer_prefix: "c_"
      project_prefix: "p_"
      allocation_prefix: "a_"
      enable_user_homedir_account_creation: true

    backend_components:
      deposit:
        measured_unit: "EUR"
        accounting_type: "limit"
        label: "Deposit (EUR)"

Event-Based Processing

offerings:
  - name: "Event-Driven SLURM"
    # ... basic settings ...

    stomp_enabled: true
    websocket_use_tls: true

    order_processing_backend: "slurm"
    reporting_backend: "slurm"
    # Note: membership_sync_backend omitted for event processing

Waldur-to-Waldur Federation

offerings:
  - name: "Federated HPC Access"
    waldur_api_url: "https://waldur-a.example.com/api/"
    waldur_api_token: "token-for-waldur-a"
    waldur_offering_uuid: "offering-uuid-on-waldur-a"
    backend_type: "waldur"
    order_processing_backend: "waldur"
    membership_sync_backend: "waldur"
    reporting_backend: "waldur"

    # Optional: STOMP event processing
    stomp_enabled: true
    websocket_use_tls: true

    backend_settings:
      target_api_url: "https://waldur-b.example.com/api/"
      target_api_token: "token-for-waldur-b"  # customer owner + ISD manager
      target_offering_uuid: "offering-uuid-on-waldur-b"
      target_customer_uuid: "customer-uuid-on-waldur-b"
      user_match_field: "cuid"
      order_poll_timeout: 300
      order_poll_interval: 5
      user_not_found_action: "warn"
      target_stomp_enabled: true

    backend_components:
      node_hours:
        measured_unit: "Node-hours"
        unit_factor: 1.0
        accounting_type: "limit"
        label: "Node Hours"
        target_components:
          cpu_k_hours:
            factor: 128.0
      tb_hours:
        measured_unit: "TB-hours"
        unit_factor: 1.0
        accounting_type: "limit"
        label: "TB Hours"
        target_components:
          gb_k_hours:
            factor: 1.0

Validation

Validate your configuration:

# Test configuration syntax
waldur_site_diagnostics -c /etc/waldur/waldur-site-agent-config.yaml

# Load components (validates backend configuration)
waldur_site_load_components -c /etc/waldur/waldur-site-agent-config.yaml
This site is open source. Improve this page.