REST API 快速入门指南

Slurm 通过 slurmrestd 守护进程提供 REST API，使用 JSON Web Tokens 进行身份验证。此页面提供了设置这些组件的简要教程。

另请参见：

目录

先决条件

编译 slurmrestd 所需以下开发库（最低版本见相关软件页面）：

此外，强烈建议您设置 SlurmDBD 以进行 计费。如果没有 slurmdbd，slurmrestd 在加载某些插件时可能会失败（使用 -s 指定要加载的插件）或在尝试 JWT 身份验证时。

快速入门

这可以在专用的 REST API 机器上或您现有的 'slurmctld' 机器上完成，具体取决于需求。如果您有多个集群，则每个集群需要一个唯一的 slurmrestd 实例。

  1. 安装 slurmrestd 的组件
    • DEB: slurm-smd slurm-smd-slurmrestd
    • RPM: slurm slurm-slurmrestd（需要在构建时使用 --with slurmrestd）
  2. 设置 JSON Web Tokens 进行身份验证
  3. 确保 /etc/slurm/slurm.conf 存在并且对于您的集群是正确的（请参见 快速入门管理员指南 和 slurm.conf 手册页）
  4. 在您首选的 [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 或手动构建，使文件位于相同位置。
注意 以下步骤中与某些版本相关的内容；这些步骤在其他版本上应被忽略。

  1. 创建一个本地服务帐户和 slurmrestd 组来运行 slurmrestd 守护进程。为了防止权限提升，用户帐户应：
    • 不是 root 或 SlurmUser
    • 不被真实用户使用或用于其他任何功能
    • 不被授予任何特殊权限
    sudo useradd -M -r -s /usr/sbin/nologin -U slurmrestd
  2. 如有需要，站点可以运行 systemctl edit slurmrestd 来覆盖默认的用户和组为站点特定的用户和组： 
    [Service]
  User=slurmrestd
  Group=slurmrestd
  3. （Slurm 24.05 及更高版本）可选：自定义 slurmrestd 的套接字。默认情况下，它仅会在 TCP 端口 6820 上监听。您可以通过更改 SLURMRESTD_LISTEN 来更改此行为（请参见 自定义 slurmrestd.service）。
  4. （Slurm 23.11 及更早版本）配置 slurmrestd 的套接字。这可以通过创建/更改父目录的权限和/或更改服务文件中的套接字路径来完成。
    • 权限：运行服务的用户必须对将包含 UNIX 套接字的目录具有写入+执行权限
    • 更改套接字：在 Slurm 23.11 上，更改或禁用套接字的方法是修改服务的 'ExecStart' 行
      1. 运行 systemctl edit slurmrestd
      2. 将以下内容添加到 [Service] 部分： 
        ExecStart=
ExecStart=/usr/sbin/slurmrestd $SLURMRESTD_OPTIONS
Environment=SLURMRESTD_LISTEN=:6820
      3. 调整 SLURMRESTD_LISTEN 的赋值以包含您希望守护进程监听的套接字。
      4. 在未来升级到 Slurm 24.05+ 后，'ExecStart' 的覆盖将不再必要，但不会与新版本冲突。

自定义 slurmrestd.service

Slurm 24.05 版本更改了默认服务文件的操作，可能会破坏现有的覆盖。如果您已覆盖 ExecStart= 以直接包含任何 TCP/UNIX 套接字，则如果它与 SLURMRESTD_LISTEN 中包含的任何套接字重复，将导致服务失败。这些覆盖在升级后需要更改。

默认的 slurmrestd.service 文件有两种自定义其操作的预期方式：

  1. 环境文件： 该服务将从两个文件中读取环境变量： /etc/default/slurmrestd 和 /etc/sysconfig/slurmrestd。 您可以设置任何 slurmrestd 识别的环境变量，但以下特别相关：
    • SLURMRESTD_OPTIONS：要添加到 slurmrestd 命令的 CLI 选项（请参见 slurmrestd）
    • SLURMRESTD_LISTEN：要监听的主机:端口对或 unix:$SOCKET_PATH 套接字的逗号分隔列表
      注意：如果这与服务文件中的 'ExecStart' 行中已经设置的内容重复，则会失败。从 Slurm 24.05 开始，默认服务文件在 'ExecStart' 中不包含套接字，完全依赖此变量包含所需的套接字。
  2. 服务编辑：Systemd 具有内置的方式通过运行 systemctl edit slurmrestd 来编辑服务。
    • 这将在 '/etc/systemd/' 中创建一个覆盖文件，包含将添加到或替换 '/lib/systemd/' 中默认单元的指令。
    • 覆盖文件必须具有适当的部分声明（例如，[Service]）。
    • 可以使用 Environment=NAME=value 设置环境变量（有关更多详细信息，请参阅 systemd 文档）
    • 通过运行 systemctl revert slurmrestd 可以恢复更改

基本用法

  1. 查找最新支持的 API 版本 
    slurmrestd -d list
  2. 获取 JWT 的身份验证令牌 
    unset SLURM_JWT; export $(scontrol token)
    • 这确保旧令牌不会阻止新令牌的发放
    • 默认情况下，令牌将在 1800 秒（30 分钟）后过期。将 lifespan=SECONDS 添加到 'scontrol' 命令以更改此设置。
  3. 在监听 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 更改为该端点的正确方法。
  4. 使用 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 详细信息 页面。

常见问题

一般来说，请注意以下事项：

  1. 身份验证令牌在 SLURM_JWT 中的有效性
  2. 主机名和端口号
  3. API 版本和端点
  4. 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 日