本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS PCS 中的 Slurm REST API 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) + [在 AWS PCS 中啟用 Slurm REST API](slurm-rest-api-enable.md) + [在 AWS PCS 中使用 Slurm REST API 驗證](slurm-rest-api-authenticate.md) + [在 AWS PCS 中使用 Slurm REST API 進行任務管理](slurm-rest-api-use.md) + [AWS PCS 中的 Slurm REST API 常見問答集](slurm-rest-api-faq.md) # 在 AWS PCS 中啟用 Slurm REST API 啟用 Slurm REST API 來存取叢集的 HTTP 介面，以進行程式設計任務管理和監控。您可以在叢集建立期間啟用此功能，或更新符合需求的現有叢集。 ## 先決條件 啟用 Slurm REST API 之前，請確定您已： + **叢集版本**：Slurm 25.05 版或更新版本。 + **安全群組**：允許連接埠 6820 上來自所需來源的 HTTP 流量的規則。 ## 程序 **在新叢集上啟用 Slurm REST API** ------ #### [ AWS 管理主控台 ] 1. 在 https：//[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 開啟 AWS PCS 主控台。 1. 選擇 **Create Cluster** (建立叢集)。 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. 在 https：//[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 開啟 AWS 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 簽署金鑰並將其存放在 AWS Secrets Manager 中。 + 在 VPC `https://:6820`中公開 API 端點。 + 更新您的叢集組態，以顯示 REST API 端點詳細資訊。 您現在可以驗證和使用 REST API 進行任務管理和叢集操作。 # 在 AWS PCS 中使用 Slurm REST API 驗證 AWS PCS 中的 Slurm REST API 使用 JSON Web Token (JWT) 身分驗證來確保對叢集資源的安全存取。 AWS PCS 提供存放在 AWS Secrets Manager 中的受管簽署金鑰，您可用來產生包含特定使用者身分宣告的 JWT 權杖。 ## 先決條件 使用 Slurm REST API 驗證之前，請確定您有： + **叢集組態**：已啟用 Slurm 25.05\$1 和 REST API 的 AWS PCS 叢集。 + **AWS 許可**：存取 JWT 簽署金鑰的 AWS Secrets Manager。 + **使用者資訊**：您叢集帳戶的使用者名稱、POSIX 使用者 ID 和一或多個 POSIX 群組 IDs。 + **網路存取**：叢集 VPC 內的連線與允許連接埠 6820 的安全群組。 ## 程序 **擷取 Slurm REST API 端點地址** ------ #### [ AWS 管理主控台 ] 1. 在 https：//[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 開啟 AWS PCS 主控台。 1. 從清單中選擇您的叢集。 1. 在叢集組態詳細資訊中，找到**端點**區段。 1. 請注意 **Slurm REST API (slurmrestd)** 的私有 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 請求傳送至 `http://:/` ------ **擷取 JWT 簽署金鑰** 1. 在 https：//[https://console.aws.amazon.com/pcs/](https://console.aws.amazon.com/pcs/) 開啟 AWS PCS 主控台。 1. 從清單中選擇您的叢集。 1. 在叢集組態詳細資訊中，找到**排程器身分驗證**區段。 1. 請注意 **JSON Web Token (JWT) 金鑰** ARN 和版本。 1. 使用 從 Secrets Manager AWS CLI 擷取簽署金鑰： ``` aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region:account:secret:name --version-id version ``` **產生 JWT 字符** 1. 使用下列必要宣告建立 JWT： + `exp` – JWT 自 1970 以來的過期時間，以秒為單位 + `iat` – 自 1970 以來的目前時間，以秒為單位 + `sun` – 身分驗證的使用者名稱 + `uid` – POSIX 使用者 ID + `gid` – POSIX 群組 ID + `id` – 其他 POSIX 身分屬性 + `gecos` – 使用者註解欄位，通常用於存放人類可讀取的名稱 + `dir` – 使用者的主目錄 + `shell` – 使用者的預設 shell + `gids` – 使用者所在的其他 POSIX 群組 IDs清單 1. 使用從 Secrets Manager 擷取的簽署金鑰簽署 JWT。 1. 為字符設定適當的過期時間。 **注意** 作為`sun`宣告的替代方案，您可以提供下列任何一項： `username` 您在 `userclaimfield`中透過 定義的自訂欄位名稱 `AuthAltParameters Slurm custom settings` `id` 宣告中的`name`欄位 **驗證 API 請求** 1. 使用下列其中一種方法在 HTTP 請求中包含 JWT 字符： + **承載字符** – 新增`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 簽署金鑰，並將其儲存為本機檔案。將 **aws-region**、 **secret-arn** 和 **secret 版本**的值取代為您的叢集適用的值。 ``` #!/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... ``` # 在 AWS PCS 中使用 Slurm REST API 進行任務管理 ## 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 版本備註中找到目前支援的 API 版本](https://slurm.schedmd.com/release_notes.html)。 + **URL 結構**：Slurm REST API 的 URL 結構為 `http://://`。您可以在 [Slurm 文件](https://slurm.schedmd.com/rest_api.html)中找到 REST API 端點的詳細用量資訊。 ## 先決條件 使用 Slurm REST API 之前，請確定您已： + **叢集組態**：已啟用 Slurm 25.05\$1 和 REST API 的 AWS PCS 叢集。 + **身分驗證**：具有適當使用者身分宣告的有效 JWT 字符。 + **網路存取**：叢集 VPC 內的連線，以及允許連接埠 6820 的安全群組。 ## 程序 **使用 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/ ``` # AWS PCS 中的 Slurm REST API 常見問答集 本節回答有關 AWS PCS 中 Slurm REST API 的常見問題。 **什麼是 Slurm REST API？** Slurm REST API 是一種 HTTP 介面，可讓您以程式設計方式與 Slurm 工作負載管理員互動。您可以使用 GET、POST 和 DELETE 等標準 HTTP 方法來提交任務、監控叢集狀態和管理資源，而不需要對叢集進行命令列存取。 **我可以使用 產生的權杖`scontrol token`嗎？** 否，標準`scontrol token`輸出與 AWS PCS 不相容。PCS Slurm REST API 需要包含特定身分宣告的豐富 JWT 字符，包括 username(`sun`)、POSIX 使用者 ID(`uid`) 和群組 IDs()`gids`。標準 Slurm 權杖缺少這些必要的宣告，且會被 API 拒絕。 **我可以從 VPC 外部存取 API 嗎？** 否，REST API 端點只能從 VPC 中使用 Slurm 控制器的私有 IP 地址存取。若要啟用外部存取，請使用 VPC Link、API Gateway 實作 Application Load Balancer 等 AWS 服務，或建立 VPC 對等互連或 VPN 連線以實現安全連線。 **為什麼 API 使用 HTTP 而不是 HTTPS？** Slurm REST API 旨在成為叢集私有網路內的內部端點。對於需要加密的生產部署，您可以在架構的更高層級實作 SSL/TLS 終止，例如透過 API 閘道、負載平衡器或反向代理。 **如何控制對 REST API 的存取？** 設定叢集的安全群組規則，以限制對 Slurm 控制器上連接埠 6820 的存取。設定傳入規則以僅允許來自信任 IP 範圍或 VPC 內特定來源的連線，封鎖對 API 端點的未經授權存取。 **如何輪換 JWT 簽署金鑰？** 將您的叢集置於沒有作用中執行個體的維護模式中，然後透過 AWS Secrets Manager 啟動金鑰輪換。輪換完成後，重新啟用佇列。所有現有的 JWT 字符都將失效，並且必須使用 Secrets Manager 的新簽署金鑰重新產生。 **是否需要啟用 Slurm 會計才能使用 REST API？** 否，基本 REST API 操作不需要 Slurm 會計，例如任務提交和監控。不過，整個`/slurmdb`端點需要處於作用中狀態。 **哪些第三方工具可與 AWS PCS REST API 搭配使用？** 許多現有的 Slurm REST API 用戶端應該使用 AWS PCS，包括適用於 Prometheus 的 Slurm Exporter、SlurmWeb，以及遵循標準 Slurm REST API 格式的自訂應用程式。不過，依賴 `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 的正確金鑰進行簽署。確認字符格式正確，並包含必要的宣告，而且您使用正確的身分驗證標頭格式。 + **提交後任務無法執行** 如果您的 JWT 字符有效，但包含不正確的內部結構或內容，則任務可能已進入暫停 (`PD`) 狀態，原因碼為 `JobAdminHead`。使用 `scontrol show job ` 檢查任務 – 您將看到 `JobState=PENDING, Reason=JobHeldAdmin`、 和 `SystemComment=slurm_cred_create failure, holding job`。 **做法**：根本原因可能是 JWT 中的錯誤值。確認字符結構正確，並根據 PCS 文件包含必要的宣告。 + **工作目錄許可問題** 如果 JWT 中指定的使用者身分缺少對任務工作目錄的寫入許可，任務將失敗並出現許可錯誤，類似於使用 `sbatch --chdir`搭配無法存取的目錄。 **做法**：確保 JWT 字符中指定的使用者具有任務工作目錄的適當許可。