本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # PCS 中的 Slurm REST API AWS AWS PCS 通过为 Slurm 的原生 REST API 提供托管支持`slurmrestd`，为编程集群交互提供一个 HTTP 接口。您可以通过标准 HTTP 请求提交作业、监控集群状态和管理资源，而无需直接 shell 访问您的集群。 ## 常见使用案例 Slurm REST API 支持各种集成场景： + **Web 应用程序集成**：构建可直接提交和管理作业的自定义前端和 Web 应用程序。 + **Jupyter 笔记本集成**：允许研究人员在不离开开发工作流程的情况下从笔记本环境中提交作业。 + **合作伙伴解决方案集成**：将第三方 HPC 工具和工作流程管理器连接到您的 AWS PCS 集群。 + **编程集群管理**：自动执行作业提交、监控和资源管理工作流程。 + **研究计算工作流程**：支持需要 API 驱动的作业管理的学术和企业研究环境。 ## 要求和限制 在使用 Slurm REST API 之前，请查看以下详细信息： + 您的集群必须使用 Slurm 版本 25.05 或更高版本。 + API 终端节点只能通过集群 VPC 内的私有 IP 地址进行访问。 + 您的集群安全组必须允许端口 6820 上的 HTTP 流量。 + 身份验证需要带有特定用户身份声明的 JWT 令牌。 目前的限制包括： + 不支持`scontrol token`生成的令牌。 + `X-SLURM-USER-NAME`标题模拟不可用。 + 某些功能需要启用 Slurm 记账。 + 与 Slurm CLI 过滤器插件机制不兼容。 + 与 REST API 端点的连接未使用 TLS 进行加密。 **Topics** + [常见使用案例](#slurm-rest-api-use-cases) + [要求和限制](#slurm-rest-api-requirements) + [在 PCS 中启用 Slurm REST API AWS](slurm-rest-api-enable.md) + [在 PCS 中使用 Slurm REST API 进行身份验证 AWS](slurm-rest-api-authenticate.md) + [在 PCS 中使用 Slurm REST API 进行作业管理 AWS](slurm-rest-api-use.md) + [PCS 中的 Slurm REST API 常见问题解答 AWS](slurm-rest-api-faq.md) # 在 PCS 中启用 Slurm REST API AWS 启用 Slurm REST API 以访问集群的 HTTP 接口，以进行编程作业管理和监控。您可以在创建集群时启用此功能，也可以更新符合要求的现有集群。 ## 先决条件 在启用 Slurm REST API 之前，请确保您已具备以下条件： + **集群版本**：Slurm 版本 25.05 或更高版本。 + **安全组**：允许端口 6820 上的 HTTP 流量来自所需来源的规则。 ## 过程 **在新集群上启用 Slurm REST API** ------ #### [ AWS 管理控制台 ] 1. 打开 AWS PCS 控制台，网址为[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/)。 1. 选择**创建集群**。 1. 在 “**集群详细信息**” 下，选择 Slurm 版本 25.05 或更高版本。 1. 根据需要配置其他群集设置。 1. 在 “**调度程序配置**” 部分，将 **REST API** 设置为**已启用**。 1. 将您的集群安全组配置为允许来自所需来源的端口 6820 上的 HTTP 流量。 1. 完成集群创建过程。 ------ #### [ AWS CLI ] 1. 在创建集群时添加 Slurm REST 配置。 ``` aws pcs create-cluster --region region \ --cluster-name my-cluster \ --scheduler type=SLURM, version=25.05 \ --size SMALL \ --networking subnetIds=subnet-ExampleId1,securityGroupIds=sg-ExampleId1 \ --slurm-configuration slurmRest='{mode=STANDARD}' ``` 1. 将您的集群安全组配置为允许来自所需来源的端口 6820 上的 HTTP 流量。 ------ **在现有集群上启用 Slurm REST API** ------ #### [ AWS 管理控制台 ] 1. 打开 AWS PCS 控制台，网址为[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/)。 1. 从列表中选择您的集群。 1. 在集群详细信息中确认您的集群使用 Slurm 版本 25.05 或更高版本。 1. 选择**编辑集群**。 1. 在 “**调度程序配置**” 部分，将 **REST API** 设置为**已启用**。 1. 选择**更新集群**以应用更改。 1. 将您的集群安全组配置为允许来自所需来源的端口 6820 上的 HTTP 流量。 ------ #### [ AWS CLI ] 1. 使用 Slurm REST 配置更新您的集群，如本示例所示。 ``` aws pcs update-cluster --cluster-identifier my-cluster \ --slurm-configuration 'slurmRest={mode=STANDARD}' ``` 1. 将您的集群安全组配置为允许来自所需来源的端口 6820 上的 HTTP 流量。 ------ ## 启用后会发生什么 当你启用 REST API 时， AWS PCS 会自动： + 生成 JWT 签名密钥并将其存储在 S AWS ecrets Manager 中。 + 在您的 VPC `https://:6820` 内公开 API 终端节点。 + 更新您的集群配置以显示 REST API 终端节点的详细信息。 现在，您可以进行身份验证并使用 REST API 进行任务管理和集群操作。 # 在 PCS 中使用 Slurm REST API 进行身份验证 AWS AWS PCS 中的 Slurm REST API 使用 JSON 网络令牌 (JWT) 身份验证来确保对集群资源的安全访问。 AWS PCS 提供存储在 Secrets Manager 中的托管签名 AWS 密钥，您可以使用该密钥生成包含特定用户身份声明的 JWT 令牌。 ## 先决条件 在使用 Slurm REST API 进行身份验证之前，请确保您已具备以下条件： + **集群配置：启**用 Slurm 25.05\$1 且启用 REST API 的 AWS PCS 集群。 + **AWS 权限**：访问 S AWS ecrets Manager 以获取 JWT 签名密钥。 + **用户信息**：用户名、POSIX 用户 ID 以及您的集群账户的一个或多个 POSIX 组 IDs 。 + **网络访问：通过**允许端口 6820 的安全组在集群的 VPC 内进行连接。 ## 过程 **检索 Slurm REST API 端点地址** ------ #### [ AWS 管理控制台 ] 1. 打开 AWS PCS 控制台，网址为[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/)。 1. 从列表中选择您的集群。 1. 在集群配置详细信息中，找到终**端节点**部分。 1. 注意 **Slurm REST API (slurm** restd) 的私有 IP 地址和端口。 1. 您可以通过向该地址发送格式正确的 HTTP 请求来进行 API 调用。 ------ #### [ AWS CLI ] 1. 使用查询您的集群状态`aws pcs get-cluster`。在响应的`endpoints`字段中查找`SLURMRESTD`端点。示例如下： ``` "endpoints": [ { "type": "SLURMCTLD", "privateIpAddress": "192.0.2.1", "port": "6817" }, { "type": "SLURMRESTD", "privateIpAddress": "192.0.2.1", "port": "6820" } ] ``` 1. 您可以通过向发送格式正确的 HTTP 请求来进行 API 调用 `http://:/` ------ **检索 JWT 签名密钥** 1. 打开 AWS PCS 控制台，网址为[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/)。 1. 从列表中选择您的集群。 1. 在集群配置详细信息中，找到 “**调度程序身份验证**” 部分。 1. 注意 **JSON 网络令牌 (JWT) 密钥** ARN 和版本。 1. 使用从 Sec AWS CLI rets Manager 中检索签名密钥： ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **生成 JWT 令牌** 1. 使用以下必填声明创建 JWT： + `exp`— 自 1970 年以来 JWT 的到期时间（以秒为单位） + `iat`— 自 1970 年以来的当前时间（以秒为单位） + `sun`— 用于身份验证的用户名 + `uid`— POSIX 用户 ID + `gid`— POSIX 群组 ID + `id`— 其他 POSIX 身份属性 + `gecos`— 用户评论字段，通常用于存储人类可读的名称 + `dir`— 用户的主目录 + `shell`— 用户的默认外壳 + `gids`— 用户所在的其他 POSIX 组 IDs 的列表 1. 使用从 Secrets Manager 中检索到的签名密钥对 JWT 进行签名。 1. 为令牌设置适当的到期时间。 **注意** 作为`sun`索赔的替代方案，您可以提供以下任一信息： `username` 您通过`userclaimfield`中的定义的自定义字段名称 `AuthAltParameters Slurm custom settings` `id`索赔中的一个`name`字段 **对 API 请求进行身份验证** 1. 使用以下方法之一将 JWT 令牌包含在您的 HTTP 请求中： + **不记名代币**-添加`Authorization: Bearer `标题 + **Slurm 标题 — 添加标题** `X-SLURM-USER-TOKEN: ` 1. 向 REST API 端点发出 HTTP 请求： 以下是使用 curl 和`Authorized: Bearer`标头访问 `/ping` API 的示例。 ``` curl -X GET -H "Authorization: Bearer " \ http://:6820/slurm/v0.0.43/ping ``` ## JWT 生成示例 获取 AWS PCS 集群 JWT 签名密钥并将其存储为本地文件。将 **aw** s-region **、** secret-arn **和密**钥版本的值替换为适合您的集群的值。 ``` #!/bin/bash SECRET_KEY=$(aws secretsmanager get-secret-value \ --region aws-region \ --secret-id secret-arn \ --version-stage secret-version \ --query 'SecretString' \ --output text) echo "$SECRET_KEY" | base64 --decode > jwt.key ``` 此 Python 示例说明了如何使用签名密钥生成 JWT 令牌： ``` #!/usr/bin/env python3 import sys import os import pprint import json import time from datetime import datetime, timedelta, timezone from jwt import JWT from jwt.jwa import HS256 from jwt.jwk import jwk_from_dict from jwt.utils import b64decode,b64encode if len(sys.argv) != 3: sys.exit("Usage: gen_jwt.py [jwt_key_file] [expiration_time_seconds]") SIGNING_KEY = sys.argv[1] EXPIRATION_TIME = int(sys.argv[2]) with open(SIGNING_KEY, "rb") as f: priv_key = f.read() signing_key = jwk_from_dict({ 'kty': 'oct', 'k': b64encode(priv_key) }) message = { "exp": int(time.time() + EXPIRATION_TIME), "iat": int(time.time()), "sun": "ec2-user", "uid": 1000, "gid": 1000, "id": { "gecos": "EC2 User", "dir": "/home/ec2-user", "gids": [1000], "shell": "/bin/bash" } } a = JWT() compact_jws = a.encode(message, signing_key, alg='HS256') print(compact_jws) ``` 该脚本会将 JWT 打印到屏幕上。 ``` abcdefgtjwttoken... ``` # 在 PCS 中使用 Slurm REST API 进行作业管理 AWS ## Slurm REST API 概述 Slurm REST API 通过 HTTP 请求提供对集群管理功能的编程访问。了解这些关键特征将有助于您有效地将 API 与 AWS PCS 配合使用： + **访问协议**：API 使用 HTTP（不是 HTTPS）在集群的私有网络内进行通信。 + **连接详情**：使用集群的私有 IP 地址和`slurmrestd`端口（通常为 6820）访问 API。完整的基本 URL 格式为`http://:6820`。 + **API 版本控制**：API 版本与你的 Slurm 安装相对应。**对于 Slurm 25.05，请使用 v0.0.43 版本。**版本号会随着每个 Slurm 版本而变化。您可以在 [Slurm 发行](https://slurm.schedmd.com/release_notes.html)说明中找到当前支持的 API 版本。 + **网址结构**：Slurm REST API 的网址结构是。`http://://`REST API 端点的详细使用信息可以在 [Slurm](https://slurm.schedmd.com/rest_api.html) 文档中找到。 ## 先决条件 在使用 Slurm REST API 之前，请确保您已具备以下条件： + **集群配置：启**用 Slurm 25.05\$1 且启用 REST API 的 AWS PCS 集群。 + **身份验证**：具有正确用户身份声明的有效 JWT 令牌。 + **网络访问：通过**允许端口 6820 的安全组在集群的 VPC 内进行连接。 ## 过程 **使用 REST API 提交作业** 1. 使用所需参数创建任务提交请求： ``` { "job": { "name": "my-job", "partition": "compute", "nodes": 1, "tasks": 1, "script": "#!/bin/bash\necho 'Hello from Slurm REST API'" } } ``` 1. 使用 HTTP POST 请求提交任务： ``` curl -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' \ https://:6820/slurm/v0.0.43/job/submit ``` 1. 出于监控目的，请记下响应中返回的任务 ID。 **监视作业状态** 1. 获取有关特定工作的信息： ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` 1. 列出经过身份验证的用户的所有作业： ``` curl -X GET -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/jobs ``` **取消作业** + 发送 DELETE 请求以取消特定任务： ``` curl -X DELETE -H "Authorization: Bearer " \ https://:6820/slurm/v0.0.43/job/ ``` # PCS 中的 Slurm REST API 常见问题解答 AWS 本节回答了有关 PCS 中的 Slurm REST API 的 AWS 常见问题。 **什么是 Slurm REST API？** Slurm REST API 是一个 HTTP 接口，允许你以编程方式与 Slurm 工作负载管理器进行交互。您可以使用标准 HTTP 方法（例如 GET、POST 和 DELETE）来提交作业、监控集群状态和管理资源，而无需命令行访问集群。 **我可以使用由生成的代币`scontrol token`吗？** 不是，标准`scontrol token`输出与 AWS PCS 不兼容。PCS Slurm REST API 需要包含包含特定身份声明的丰富的 JWT 令牌，包括用户名 (`sun`)、POSIX 用户 ID (`uid`) 和群组 ()。 IDs `gids`标准 Slurm 代币缺少这些必需的声明，因此会被 API 拒绝。 **我能否从我的 VPC 外部访问 API？** 不可以，只有在您的 VPC 中使用 Slurm 控制器的私有 IP 地址才能访问 REST API 终端节点。要启用外部访问，请实施诸如带有 VPC Link 的 Application Load Balancer、API Gateway 之类的 AWS 服务，或者建立 VPC 对等或 VPN 连接以实现安全连接。 **为什么 API 使用 HTTP 而不是 HTTPS？** Slurm REST API 旨在成为集群私有网络中的内部终端节点。对于需要加密的生产部署，您可以在架构中更高级别实现 SSL/TLS 终止，例如通过 API 网关、负载均衡器或反向代理。 **如何控制对 REST API 的访问权限？** 配置集群的安全组规则，以限制对 Slurm 控制器上的 6820 端口的访问。将入站规则设置为仅允许来自可信 IP 范围或 VPC 内特定来源的连接，从而阻止对 API 终端节点的未经授权的访问。 **如何轮换 JWT 签名密钥？** 将您的集群置于没有活动实例的维护模式，然后通过 Secrets Manager 启动 AWS 密钥轮换。轮换完成后，重新启用队列。所有现有 JWT 令牌都将失效，必须使用 Secrets Manager 中的新签名密钥重新生成。 **我需要启用 Slurm 记账功能才能使用 REST API 吗？** 不，作业提交和监控等基本 REST API 操作不需要 Slurm 记账。但是，整个`/slurmdb`端点都需要记账才能处于活动状态。 **哪些第三方工具可以与 AWS PCS REST API 配合使用？** 许多现有的 Slurm REST API 客户端都应使用 AWS PCS，包括适用于 Prometheus 的 Slurm Exporter，以及遵循标准 Slurm REST API SlurmWeb 格式的自定义应用程序。但是，依赖身份验证`scontrol token`的工具需要修改才能满足 AWS PCS JWT 的要求。 **使用 REST API 会产生任何额外费用吗？** 不，启用或使用 Slurm REST API 功能不收取任何额外费用。您只需像往常一样为底层群集资源付费。 **如何对 REST API 进行故障排除？** + **网络连接问题** 如果您无法访问 API 终端节点，则在向集群控制器发出 HTTP 请求时，您将看到连接超时或 “连接被拒绝” 错误。 **操作方法**：验证您的客户端位于同一 VPC 中或网络路由正确，并确认您的安全组允许来自您的源 IP 或子网的 6820 端口上的 HTTP 流量。 + **Slurm REST 身份验证问题** 如果您的 JWT 令牌无效、过期或签名不正确，API 请求将在响应的错误字段中返回 “协议身份验证错误”。 错误消息示例： ``` { "errors": [ { "description": "Batch job submission failed", "error_number": 1007, "error": "Protocol authentication error", "source": "slurm_submit_batch_job()" } ] } ``` **操作方法**：检查您的 JWT 令牌的格式是否正确，未过期，并使用来自 Secrets Manager 的正确密钥进行签名。验证令牌的格式是否正确且包含所需的声明，以及您使用的身份验证标头格式是否正确。 + **提交后 Job 无法运行** 如果您的 JWT 令牌有效但包含不正确的内部结构或内容，则任务可能已进入带有原因代码的 pause `PD` d () 状态。`JobAdminHead``scontrol show job `用于检查作业 — 你会看到`JobState=PENDING, Reason=JobHeldAdmin`，和`SystemComment=slurm_cred_create failure, holding job`。 **怎么做**：根本原因可能是 JWT 中的值错误。根据PCS文档，验证令牌的结构是否正确，并包含所需的声明。 + **工作目录权限问题** 如果您的 JWT 中指定的用户身份缺少对作业工作目录的写入权限，则作业将因权限错误而失败，类似于`sbatch --chdir`使用无法访问的目录。 **操作方法**：确保您的 JWT 令牌中指定的用户对作业的工作目录具有相应的权限。