waldur-site-agent

Quickstart

The fastest path from a fresh install to a running, verified agent. This page deliberately skips options and edge cases — it links out to the full Configuration Reference and Deployment Guide for everything beyond a first working setup. Written around the SLURM backend, since it’s the most common first deployment; other backends follow the same shape with a different backend_type and backend_settings block (see your plugin’s README, linked from the plugin table).

Budget about 15-20 minutes if the offering side is already set up in Waldur.

1. Create the offering in Waldur

Go to the Service Provider section of your organization, open offering creation, pick a name and category, and select Waldur site agent from the type drop-down.
On the offering’s Edit tab, open Accounting → Accounting plans, add a plan.
Still on Edit, open Integration → User management, set Service provider can create offering user to Yes.
Activate the offering with the green Activate button.
Copy the offering UUID from Integration → Credentials — you’ll need it below.
Create a dedicated agent account — a Waldur login that exists only for the agent to authenticate with, not a real person’s. As a staff user, go to the Support workspace → User management → Users → Create user, and work through the wizard: set a username and email, and set (or generate) a Password on the Account step — leave it blank and the account ends up passwordless. Leave Staff and Support unchecked; offering-level access, granted next, is all this account needs.
Grant that account the OFFERING.MANAGER role on this specific offering — not a customer-wide role. On the offering’s Team tab, use Add to invite the account with the OFFERING.MANAGER role. This is the minimum the agent needs and nothing more: it covers order approval, usage reporting, and resource state/backend-metadata updates. It’s unrelated to the GET_SERVICE_PROVIDER_API_SECRET_CODE permission mentioned in step 3 below — that one’s only needed by a human using the UI config generator, not by the agent’s own token.
Create an API token for the agent account. You’ll need it below too. Log in as that account, open the avatar menu in the top-right corner → Profile → API token tab, then click the eye icon to reveal and copy the token.

That page also has a Token lifetime setting (10/30 min, 1/2/12 hours, or indefinite) — it’s extended automatically on each successful API call, but the agent runs unattended and can go quiet for stretches (initial setup, a paused service, sparse polling intervals) that outlast any timed option. Set it to indefinite — anything shorter will eventually expire and break the agent’s auth. The UI warns that an indefinite token can be used by anyone who has it until it’s changed, so treat it like any other long-lived service credential: keep it out of version control and out of shell history.

2. Install the agent

The core package has no backends of its own — install it together with the SLURM plugin and the default username backend, in one environment:

curl -LsSf https://astral.sh/uv/install.sh \
  | sudo env UV_INSTALL_DIR=/usr/local/bin UV_NO_MODIFY_PATH=1 sh

sudo env UV_TOOL_DIR=/opt/waldur-agent/tools \
         UV_TOOL_BIN_DIR=/usr/local/bin \
         UV_PYTHON_INSTALL_DIR=/opt/waldur-agent/python \
  /usr/local/bin/uv tool install --python 3.12 --managed-python waldur-site-agent \
    --with-executables-from waldur-site-agent-slurm \
    --with waldur-site-agent-basic-username-management

The Installation Guide covers the OS packages (including the SLURM client tools the agent shells out to), a pip-based alternative, other backends and why commands below are called by their full path.

3. Write a minimal config

Option A: generate it from Waldur (SLURM only, recommended)

For SLURM offerings, skip hand-writing YAML entirely. On the same Integration → Credentials page from step 1, open Actions → Generate Site Agent Config. It builds a config from your actual offering — name, waldur_api_url, waldur_offering_uuid, all three *_backend fields, backend_settings, and backend_components (including your real plan components, not a generic example) are filled in for you. Only waldur_api_token comes back as a placeholder (<YOUR_API_TOKEN_HERE>) — swap in the token from step 1. Copy or download the result as waldur-site-agent-config.yaml.

You need the GET_SERVICE_PROVIDER_API_SECRET_CODE permission on the customer to see this action — if it’s missing from the Actions menu, that’s usually why.

Option B: write it by hand

Only the fields below are required to get a SLURM offering running. Everything else in the full example (multi-offering setups, LDAP, prepaid billing, QoS management, home directory quotas, …) can wait until this is working.

sudo mkdir -p /etc/waldur
sudo tee /etc/waldur/waldur-site-agent-config.yaml <<'EOF'
timezone: "UTC"
offerings:
  - name: "My SLURM Cluster"
    waldur_api_url: "https://waldur.example.com/api/"   # REQUIRED
    waldur_api_token: "your-token-here"                 # REQUIRED, OFFERING.MANAGER role
    waldur_offering_uuid: "your-offering-uuid-here"      # REQUIRED
    order_processing_backend: "slurm"
    membership_sync_backend: "slurm"
    reporting_backend: "slurm"
    backend_type: "slurm"
    backend_settings:
      default_account: "root"
      customer_prefix: "hpc_"
      project_prefix: "hpc_"
      allocation_prefix: "hpc_"
    backend_components:
      cpu:
        measured_unit: "k-Hours"
        unit_factor: 60000
        accounting_type: "usage"
        label: "CPU"
EOF
sudo chmod 600 /etc/waldur/waldur-site-agent-config.yaml   # it holds the API token

Swap in real values for the three lines marked REQUIRED. default_account must already exist in sacctmgr — the agent doesn’t create it for you.

Either way, wherever the file ends up, remember to save it at /etc/waldur/waldur-site-agent-config.yaml (or update the -c path in the commands below to match).

4. Load offering components into Waldur

This pushes the backend_components block above (the cpu component here) into the offering as a billable plan component. Without this step the offering has nothing to charge for.

sudo /usr/local/bin/waldur_site_load_components -c /etc/waldur/waldur-site-agent-config.yaml

5. Check your setup before you touch systemd

sudo /usr/local/bin/waldur_site_diagnostics -c /etc/waldur/waldur-site-agent-config.yaml
echo "exit code: $?"

This checks both sides for every offering: the Waldur API, your token and the offering, and the backend itself — for SLURM it runs the SLURM tools, so a missing sacctmgr or an unreachable accounting database shows up here. It exits non-zero when something is wrong. Once at least one resource exists (step 7), the SLURM plugin’s deeper check compares an account’s SLURM state with what Waldur expects:

sudo /usr/local/bin/waldur_site_diagnose_slurm_account <allocation-account> \
  -c /etc/waldur/waldur-site-agent-config.yaml

<allocation-account> is the SLURM account the agent created for the resource: its backend ID, shown on the resource in Waldur, normally allocation_prefix followed by the resource’s slug.

6. Enable it for real

Follow Deployment → Systemd Service Setup to install and start the services: three for polling (order_process, membership_sync, report) or two for event-based processing (event_process, report). Come back here once they’re running.

7. Verify end-to-end

Place a small test order against your offering in the Waldur marketplace, then:

# Watch the order get picked up and the SLURM account get created
journalctl -u waldur-agent-order-process.service -f

# Confirm the account actually exists on the cluster
sacctmgr show account <expected-account-name>

The resource should move to OK in Waldur and the account should exist in sacctmgr with the prefix/limits from your config. If it doesn’t, see Deployment → Troubleshooting — that section is ordered to match the failure modes you’ll hit at each step above, starting with waldur_site_diagnostics.

This site is open source. Improve this page.