REST API 快速入门指南
Slurm 通过 slurmrestd 守护进程提供 REST API,使用 JSON Web Tokens 进行身份验证。此页面提供了设置这些组件的简要教程。
另请参见:
目录
先决条件
编译 slurmrestd 所需以下开发库(最低版本见相关软件页面):
此外,强烈建议您设置 SlurmDBD 以进行 计费。如果没有 slurmdbd,slurmrestd 在加载某些插件时可能会失败(使用 -s 指定要加载的插件)或在尝试 JWT 身份验证时。
快速入门
这可以在专用的 REST API 机器上或您现有的 'slurmctld' 机器上完成,具体取决于需求。如果您有多个集群,则每个集群需要一个唯一的 slurmrestd 实例。
- 安装 slurmrestd 的组件
- DEB:
slurm-smd slurm-smd-slurmrestd
- RPM:
slurm slurm-slurmrestd
(需要在构建时使用--with slurmrestd
)
- DEB:
- 设置 JSON Web Tokens 进行身份验证
- 确保
/etc/slurm/slurm.conf
存在并且对于您的集群是正确的(请参见 快速入门管理员指南 和 slurm.conf 手册页) - 在您首选的 [HOST]:PORT 组合上运行 slurmrestd(有关 systemd 指令,请参见 下文),默认值为 ':6820'
export SLURM_JWT=daemon export SLURMRESTD_DEBUG=debug slurmrestd <host>:<port>
调整 SLURMRESTD_DEBUG 以获得所需的输出级别(如手册页中所述)
使用 systemd 运行
Slurm 附带了一个 slurmrestd 的 systemd 服务单元,但可能需要一些额外的设置才能正常运行。本节假设您已使用 DEB/RPM 包安装 slurmrestd 或手动构建,使文件位于相同位置。
注意 以下步骤中与某些版本相关的内容;这些步骤在其他版本上应被忽略。
- 创建一个本地服务帐户和
slurmrestd
组来运行 slurmrestd 守护进程。为了防止权限提升,用户帐户应:- 不是 root 或 SlurmUser
- 不被真实用户使用或用于其他任何功能
- 不被授予任何特殊权限
sudo useradd -M -r -s /usr/sbin/nologin -U slurmrestd
- 如有需要,站点可以运行
systemctl edit slurmrestd
来覆盖默认的用户和组为站点特定的用户和组:[Service] User=slurmrestd Group=slurmrestd
- (Slurm 24.05 及更高版本)可选:自定义 slurmrestd 的套接字。默认情况下,它仅会在 TCP 端口 6820 上监听。您可以通过更改
SLURMRESTD_LISTEN
来更改此行为(请参见 自定义 slurmrestd.service)。 - (Slurm 23.11 及更早版本)配置 slurmrestd 的套接字。这可以通过创建/更改父目录的权限和/或更改服务文件中的套接字路径来完成。
- 权限:运行服务的用户必须对将包含 UNIX 套接字的目录具有写入+执行权限
- 更改套接字:在 Slurm 23.11 上,更改或禁用套接字的方法是修改服务的 'ExecStart' 行
- 运行
systemctl edit slurmrestd
- 将以下内容添加到
[Service]
部分:ExecStart= ExecStart=/usr/sbin/slurmrestd $SLURMRESTD_OPTIONS Environment=SLURMRESTD_LISTEN=:6820
- 调整 SLURMRESTD_LISTEN 的赋值以包含您希望守护进程监听的套接字。
- 在未来升级到 Slurm 24.05+ 后,'ExecStart' 的覆盖将不再必要,但不会与新版本冲突。
- 运行
自定义 slurmrestd.service
Slurm 24.05 版本更改了默认服务文件的操作,可能会破坏现有的覆盖。如果您已覆盖 ExecStart=
以直接包含任何 TCP/UNIX 套接字,则如果它与 SLURMRESTD_LISTEN 中包含的任何套接字重复,将导致服务失败。这些覆盖在升级后需要更改。
默认的 slurmrestd.service
文件有两种自定义其操作的预期方式:
- 环境文件:
该服务将从两个文件中读取环境变量:
/etc/default/slurmrestd
和/etc/sysconfig/slurmrestd
。 您可以设置任何 slurmrestd 识别的环境变量,但以下特别相关:- SLURMRESTD_OPTIONS:要添加到 slurmrestd 命令的 CLI 选项(请参见 slurmrestd)
- SLURMRESTD_LISTEN:要监听的主机:端口对或 unix:$SOCKET_PATH 套接字的逗号分隔列表
注意:如果这与服务文件中的 'ExecStart' 行中已经设置的内容重复,则会失败。从 Slurm 24.05 开始,默认服务文件在 'ExecStart' 中不包含套接字,完全依赖此变量包含所需的套接字。
- 服务编辑:Systemd 具有内置的方式通过运行
systemctl edit slurmrestd
来编辑服务。- 这将在 '/etc/systemd/' 中创建一个覆盖文件,包含将添加到或替换 '/lib/systemd/' 中默认单元的指令。
- 覆盖文件必须具有适当的部分声明(例如,
[Service]
)。 - 可以使用
Environment=NAME=value
设置环境变量(有关更多详细信息,请参阅 systemd 文档) - 通过运行
systemctl revert slurmrestd
可以恢复更改
基本用法
- 查找最新支持的 API 版本
slurmrestd -d list
- 获取 JWT 的身份验证令牌
unset SLURM_JWT; export $(scontrol token)
- 这确保旧令牌不会阻止新令牌的发放
- 默认情况下,令牌将在 1800 秒(30 分钟)后过期。将
lifespan=SECONDS
添加到 'scontrol' 命令以更改此设置。
- 在监听 TCP 主机:端口时运行基本的 curl 命令以访问 API
curl -s -o "/tmp/curl.log" -k -vvvv \ -H X-SLURM-USER-TOKEN:$SLURM_JWT \ -X GET 'http://<server>:<port>/slurm/v0.0.<api-version>/diag'
- 用适当的值替换 server、port 和 api-version。
- 检查输出以确保响应为 200 OK,并检查 /tmp/curl.log 以获取有效的 JSON 响应。
- 尝试访问 API 方法和模型 中描述的其他端点。将 GET 更改为该端点的正确方法。
- 使用 UNIX 套接字的替代命令
curl -s -o "/tmp/curl.log" -k -vvvv \ -H X-SLURM-USER-TOKEN:$SLURM_JWT \ --unix-socket /path/to/slurmrestd.socket \ 'http://<server>/slurm/v0.0.<api-version>/diag'
- 用适当的值替换 path、server 和 api-version。
- 检查输出以确保响应为 200 OK,并检查 /tmp/curl.log 以获取有效的 JSON 响应。
令牌管理
本指南提供了使用 scontrol
获取令牌的简单概述。这是一种基本的入门方法,在许多情况下应禁用,以便使用更复杂的令牌管理。有关更多详细信息,请参见 JWT 页面。
高级用法
有关进一步自定义和配置 slurmrestd 的方法的信息,包括身份验证方法、运行模式、插件、高可用性和代理,请参见 REST API 详细信息 页面。
常见问题
一般来说,请注意以下事项:
- 身份验证令牌在
SLURM_JWT
中的有效性 - 主机名和端口号
- API 版本和端点
- slurmrestd 的日志输出
无法绑定套接字
这可能是由于在尝试设置套接字时出现权限问题。检查 slurmrestd 的日志输出以获取套接字的路径。确保运行 slurmrestd 服务的用户对配置的套接字路径的父目录具有权限,或按照 上述描述 更改/删除套接字路径。
如果提示“地址已在使用”,请检查正在运行的命令和 "SLURMRESTD_LISTEN" 的内容,以查找重复的 TCP 或 UNIX 套接字。
连接被拒绝
验证 slurmrestd 是否正在运行并监听您尝试连接的端口。
协议身份验证错误(HTTP 500)
一个常见的身份验证问题是令牌过期。请求一个新的:
unset SLURM_JWT; export $(scontrol token)
此解决方案也适用于由于未发送身份验证令牌而导致的 HTTP 401 错误。这可能在 slurmrestd 日志中显示为“身份验证不适用于请求。”
否则,请检查 slurmctld 和 slurmdbd 的日志。
无法找到请求的 URL(HTTP 404)
检查 API 方法和模型 页面,以确保您使用的是有效的 URL 和正确的方法。请注意路径,因为 slurm 和 slurmdbd 有不同的端点。
拒绝线程配置令牌(HTTP 401)
检查 slurmrestd 是否已加载 auth/jwt 插件。您应该看到类似于以下内容的调试消息:
slurmrestd: debug: auth/jwt: init: JWT authentication plugin loaded如果没有加载 jwt,请在您用于 slurmrestd 的终端中运行:
export SLURM_JWT=daemon
意外的 URL 字符(HTTP 400)
检查请求的 URL 和 slurmrestd 日志,以查找可能导致 URL 被错误解析的字符。使用适当的 URL 编码序列替换问题字符(例如,/ = %2F)。
... -X GET "localhost:8080/slurmdb/v0.0.40/jobs?submit_time=02/28/24" ### 400 BAD REQUEST ... -X GET "localhost:8080/slurmdb/v0.0.40/jobs?submit_time=02%2F28%2F24" ### 200 OK
其他 slurm 命令无法工作
如果 SLURM_JWT 被设置,其他 slurm 命令将尝试使用 JWT 身份验证,导致失败。可以通过清除该变量来修复:
unset SLURM_JWT
最后修改于 2025 年 5 月 16 日