Skip to content

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:

1
2
3
4
5
sentry_dsn: ""
timezone: "UTC"
offerings:
  - name: "Example Offering"
    # Offering-specific configuration...

Global Settings

sentry_dsn

  • Type: String
  • Description: Data Source Name for Sentry error tracking
  • Default: Empty (disabled)
  • Example: "https://key@sentry.io/project"

elastic_apm_server_url

  • Type: String
  • Description: Elastic APM server URL. When set, enables Elastic APM monitoring with automatic instrumentation.
  • Default: Empty (disabled)
  • Example: "https://apm-server.example.com:8200"

timezone

  • Type: String
  • Description: Timezone for billing period calculations
  • Default: System timezone
  • Recommended: "UTC"
  • Examples: "UTC", "Europe/Tallinn", "America/New_York"

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

  • Type: String
  • Required: Yes
  • Description: Human-readable name for the offering

waldur_api_url

  • Type: String
  • Required: Yes
  • Description: URL of Waldur API endpoint
  • Example: "http://localhost:8081/api/"

waldur_api_token

  • Type: String
  • Required: Yes
  • Description: Token for Waldur API authentication
  • Permissions: The token user must have OFFERING.MANAGER role on the offering specified by waldur_offering_uuid. This grants the permissions needed for order processing, usage reporting, membership sync, and event subscriptions.
  • Security: Keep this secret and secure

verify_ssl

  • Type: Boolean
  • Default: true
  • Description: Whether to verify SSL certificates for Waldur API

waldur_offering_uuid

  • Type: String
  • Required: Yes
  • Description: UUID of the offering in Waldur
  • Note: Found in Waldur UI under Integration -> Credentials
  • Supported offering types: Waldur accepts an agent identity only for an offering whose type is Waldur site agent (Marketplace.Slurm), Script (Marketplace.Script), Basic (Marketplace.Basic) or OpenStack tenant (OpenStack.Tenant). Point an agent at any other type — a service desk offering, say — and identity registration is refused with a misleading 400 Object with uuid=... does not exist, even though the offering is there. The agent logs a warning and carries on syncing without agent telemetry; see Agent Identity Registration Is Refused. The set of accepted types is a property of the Waldur server, so it can differ between Waldur versions.

Backend Configuration

backend_type

  • Type: String
  • Required: Yes for legacy configurations
  • Values: "slurm", "moab", "mup"
  • Description: Type of backend (legacy setting, use specific backend settings instead)

Backend Selection

Configure which backends to use for different operations:

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

  • "slurm": SLURM cluster management
  • "moab": MOAB cluster management
  • "mup": MUP portal integration
  • "waldur": Waldur-to-Waldur federation
  • "base": Basic username management
  • "rancher": Direct Rancher REST API integration (single offering = one cluster)
  • "ceph_s3": Ceph S3 storage (croit and RadosGW flavours)
  • "digitalocean": DigitalOcean droplets
  • "azure": Azure virtual machines. See plugins/azure/README.md.
  • "rancher-kc-crd": CRD-driven Rancher + Keycloak management via the rancher-keycloak-operator. Membership-sync only; targets multiple clusters per offering by reading cluster_id from each Resource's backend_id. See plugins/rancher-kc-crd/README.md.
  • Custom backends via plugins

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

Event Processing

stomp_enabled

  • Type: Boolean
  • Default: false
  • Description: Enable STOMP-based event processing

stomp_membership_sync_enabled

  • Type: Boolean or null
  • Default: null (inherits stomp_enabled)
  • Description: Controls whether membership sync uses STOMP events or HTTP polling. When stomp_enabled is true this defaults to true as well. Set to false to keep HTTP polling for membership sync while using STOMP for order processing.
  • Note: Setting this to true while stomp_enabled is false leaves membership sync with no runner at all — the polling agent skips it (assuming STOMP owns it) and the STOMP consumers never start. The agent logs a MISCONFIGURATION warning on startup if it sees this combination.

websocket_use_tls

  • Type: Boolean
  • Default: true
  • Description: Use TLS for websocket connections

Resource Management

resource_import_enabled

  • Type: Boolean
  • Default: false
  • Description: Whether to expose importable resources to Waldur

preserve_unmanaged_backend_users

  • Type: Boolean
  • Default: false
  • Description: Controls how membership sync treats backend users who are not on the Waldur resource team. When false (default), any such user is removed. When true, users Waldur has ever known as offering users of this offering (any state, including DELETED and restricted) are removed once they leave the team; accounts Waldur has never seen — for example people the service provider added locally because Waldur validation blocked their offering user — are kept. Applies to every local-username backend (SLURM, MOAB, MUP, OKD, Harbor, …). Ignored for identity-bridge / Waldur-to-Waldur federation.

Common Backend Settings

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

check_backend_id_uniqueness

  • Type: Boolean
  • Default: false
  • Description: Enable checking that the generated backend ID is unique across offering history before creating a resource. When enabled, the agent queries Waldur to verify uniqueness and retries with a new ID on collision.

check_all_offerings

  • Type: Boolean
  • Default: false
  • Description: When check_backend_id_uniqueness is enabled, check uniqueness across all customer offerings instead of only the current offering.

backend_id_max_retries

  • Type: Integer
  • Default: 50
  • Description: Maximum number of retry attempts when generating a unique backend ID. Applies when check_backend_id_uniqueness is enabled or the project_slug account name generation policy is used. Set to a lower value if collisions are rare or a higher value for large deployments.

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

  • Unset (default) — the agent uses the resource's slug verbatim: {allocation_prefix}{resource_slug}. If the offering also defines a resource_slug_template (e.g. {project_slug}-{counter}), the slug is already unique and is used as-is, with no extra suffix.
  • project_slug — the agent ignores the resource slug and instead derives the backend ID from the project slug, appending an incrementing -{counter} on each collision to disambiguate multiple resources in the same project.

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

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

1
2
3
4
5
6
backend_settings:
  default_account: "root"
  customer_prefix: "c_"
  project_prefix: "p_"
  allocation_prefix: "a_"
  enable_user_homedir_account_creation: true

MUP Backend Settings

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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:

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

  • Type: String
  • Description: Unit displayed in Waldur
  • Examples: "k-Hours", "gb-Hours", "EUR"

unit_factor

  • Type: Number
  • Description: Factor for conversion from Waldur units to backend units
  • Examples:
  • 60000 for CPU (60 * 1000, converts k-Hours to CPU-minutes)
  • 61440 for memory (60 * 1024, converts gb-Hours to MB-minutes)

accounting_type

  • Type: String
  • Values: "usage", "limit", or "one"
  • Description: Controls billing type and backend behavior. "usage" for usage-based tracking, "limit" for fixed allocation caps, "one" for prepaid ONE_TIME billing (automatically sets is_prepaid: true in Waldur).

label

  • Type: String
  • Description: Human-readable label displayed in Waldur

limit

  • Type: Number
  • Optional: Yes
  • Description: Fixed limit amount for limit-type components

description

  • Type: String
  • Optional: Yes
  • Description: Description of the component shown in Waldur

min_value

  • Type: Integer
  • Optional: Yes
  • Description: Minimum allowed value for the component

max_value

  • Type: Integer
  • Optional: Yes
  • Description: Maximum allowed value for the component

max_available_limit

  • Type: Integer
  • Optional: Yes
  • Description: Maximum available limit for the component

default_limit

  • Type: Integer
  • Optional: Yes
  • Description: Default limit value applied when creating a resource

limit_period

  • Type: String
  • Optional: Yes
  • Values: "annual", "month", "quarterly", "total"
  • Description: Billing period for limit enforcement

article_code

  • Type: String
  • Optional: Yes
  • Description: Article code for billing system integration

is_boolean

  • Type: Boolean
  • Optional: Yes
  • Description: Whether the component represents a boolean (on/off) option

is_prepaid

  • Type: Boolean
  • Optional: Yes
  • Description: Whether the component requires prepaid billing. Automatically set to true when accounting_type: "one".

min_prepaid_duration

  • Type: Integer
  • Optional: Yes
  • Description: Minimum initial prepaid duration in months. Only applies when accounting_type: "one".

max_prepaid_duration

  • Type: Integer
  • Optional: Yes
  • Description: Maximum initial prepaid duration in months. Only applies when accounting_type: "one".

prepaid_duration_step

  • Type: Integer
  • Optional: Yes
  • Description: Step size in months for initial duration. If set, only multiples of this value (starting from min_prepaid_duration) are valid. For example, min_prepaid_duration: 3 and prepaid_duration_step: 3 allows 3, 6, 9, 12 months.

min_renewal_duration

  • Type: Integer
  • Optional: Yes
  • Description: Minimum renewal duration in months.

max_renewal_duration

  • Type: Integer
  • Optional: Yes
  • Description: Maximum renewal duration in months.

renewal_duration_step

  • Type: Integer
  • Optional: Yes
  • Description: Step size in months for renewal. Only multiples of this value (starting from min_renewal_duration) are valid.

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

1
2
3
4
5
backend_components:
  deposit:
    measured_unit: "EUR"
    accounting_type: "limit"
    label: "Deposit (EUR)"

Environment Variables

Override configuration values using environment variables:

Agent Timing

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

Monitoring

  • SENTRY_ENVIRONMENT: Environment name for Sentry

Example Configurations

SLURM Cluster

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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:

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