| slurmrestd(8) | Slurm REST Daemon | slurmrestd(8) |
slurmrestd - Interface to Slurm via REST API.
slurmrestd [OPTIONS...] <[host]:port|unix:/path/to/socket>...
slurmrestd is REST API interface for Slurm. It can be used in two modes:
Inetd Mode: slurmrestd will read and write to STDIO. If STDIN is a socket file descriptor, then slurmrestd will detect this and use relevant functionality. If a controlling TTY is detected, interactive mode will automatically activate to provide additional logging information. This mode is designed to work with piped input, inetd, xinetd or systemd socket activation.
Listen Mode: slurmrestd will open a listening socket on each requested host:port pair or UNIX socket.
The following environment variables can be used to override settings compiled into slurmrestd.
SPANK and clifilter plugins are not supported in slurmrestd due to their lack of thread safety. Active SPANK plugins and JobSubmitPlugins in slurmctld are independent of slurmrestd and can be used to enforce site policy on job submissions.
Generate OpenAPI schema without configuration
$ slurmrestd -f /dev/null --generate-openapi-spec -s slurmdbd,slurmctld -d v0.0.42 > openapi.json
Start slurmrestd with a UNIX socket in listen mode:
$ export SLURMRESTD=/var/spool/slurm/restd/rest $ slurmrestd -s slurmctld,slurmdbd -d v0.0.42 unix:$SLURMRESTD
Verify connectivity with slurmctld with a ping, with slurmrestd running in listen mode:
$ export $(scontrol token)
$ curl --unix-socket "${SLURMRESTD}" -H "X-SLURM-USER-TOKEN:${SLURM_JWT}" 'http://ignored_with_unix_sockets/slurm/v0.0.42/ping' | jq '.pings'
[
{
"hostname": "omicronpersei8",
"pinged": "UP",
"latency": 314,
"mode": "primary"
}
]
Verify connectivity with slurmdbd with a diag request, with slurmrestd running in listen mode:
$ export $(scontrol token)
$ curl --unix-socket "${SLURMRESTD}" -H "X-SLURM-USER-TOKEN:${SLURM_JWT}" 'http://ignored_with_unix_sockets/slurmdb/v0.0.42/diag' | jq '.pings'
1722009793
Query the status of a node with slurmrestd running in INETD mode:
$ echo -e "GET http://ignored/slurm/v0.0.42/node/host1 HTTP/1.1\r\n" | slurmrestd
HTTP/1.1 200 OK
Content-Length: 3174
Content-Type: application/json
{
"nodes": [
{
"architecture": "x86_64",
"burstbuffer_network_address": "",
"boards": 1,
"boot_time": {
"set": true,
"infinite": false,
"number": 1720820315
},
"cluster_name": "",
"cores": 16,
"specialized_cores": 0,
"cpu_binding": 0,
"cpu_load": 446,
"free_mem": {
"set": true,
"infinite": false,
"number": 39871
},
"cpus": 32,
"effective_cpus": 32,
"specialized_cpus": "",
"energy": {
"average_watts": 0,
"base_consumed_energy": 0,
"consumed_energy": 0,
"current_watts": {
"set": false,
"infinite": false,
"number": 0
},
"previous_consumed_energy": 0,
"last_collected": 0
},
"external_sensors": {},
"extra": "",
"power": {},
"features": [],
"active_features": [],
"gpu_spec": "",
"gres": "gpu:fake1:1(S:0),gpu:fake2:1(S:0)",
"gres_drained": "NA",
"gres_used": "gpu:fake1:0(IDX:NA),gpu:fake2:0(IDX:NA)",
"instance_id": "",
"instance_type": "",
"last_busy": {
"set": true,
"infinite": false,
"number": 1722009794
},
"mcs_label": "",
"specialized_memory": 0,
"name": "host1",
"next_state_after_reboot": [
"INVALID"
],
"address": "localhost",
"hostname": "omicronpersei8",
"state": [
"IDLE"
],
"operating_system": "Linux 6.5.0-44-generic #44-Ubuntu SMP PREEMPT_DYNAMIC Fri Jun 7 15:10:09 UTC 2024",
"owner": "",
"partitions": [
"debug"
],
"port": 5015,
"real_memory": 127927,
"res_cores_per_gpu": 0,
"comment": "",
"reason": "",
"reason_changed_at": {
"set": true,
"infinite": false,
"number": 0
},
"reason_set_by_user": "",
"resume_after": {
"set": true,
"infinite": false,
"number": 0
},
"reservation": "",
"alloc_memory": 0,
"alloc_cpus": 0,
"alloc_idle_cpus": 32,
"tres_used": "",
"tres_weighted": 0.0,
"slurmd_start_time": {
"set": true,
"infinite": false,
"number": 1722009794
},
"sockets": 1,
"threads": 2,
"temporary_disk": 0,
"weight": 1,
"tres": "cpu=32,mem=127927M,billing=32,gresgpu=2",
"version": "24.11.0-0rc1"
}
],
"last_update": {
"set": true,
"infinite": false,
"number": 1722010273
},
"meta": {
<<< TRIMMED >>>
},
"errors": [],
"warnings": []
}
Submit a job to slurmrestd with it running in listen mode:
$ jq . example_job.json
{
"job": {
"script": "#!/bin/bash\nsleep 30",
"name": "ExampleJob",
"account": "sub1",
"environment": [
"PATH=/usr/bin/:/bin/"
],
"current_working_directory": "/tmp/",
"tasks": 12,
"memory_per_cpu": 100,
"time_limit": 240
}
}
$ curl -H "Content-Type: application/json" --data-binary @example_job.json --unix-socket "${SLURMRESTD}" 'http://ignored/slurm/v0.0.42/job/submit'
{
"job_id": 9,
"step_id": "batch",
"job_submit_user_msg": "",
"meta": {
<<< TRIMMED >>>
},
"errors": [],
"warnings": []
}
$ curl -H "Content-Type: application/json" --data-binary @example_job.json --unix-socket "${SLURMRESTD}" 'http://ignored/slurm/v0.0.42/job/submit'
{
"job_id": 7,
"step_id": "batch",
"job_submit_user_msg": "",
"meta": {
},
"errors": [],
"warnings": [
{
"description": "Expected OpenAPI type=array (Slurm type=list) but got OpenAPI type=object (Slurm type=dictionary): {
"source": "#jobenvironment"
}
]
}
Copyright (C) 2019-2022 SchedMD LLC.
This file is part of Slurm, a resource management program. For details, see <https://slurm.schedmd.com/>.
Slurm is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Slurm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
slurm.conf(5), slurmctld(8), slurmdbd(8)
| Slurm REST Daemon | July 2023 |