本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS PCS 中的 Slurm REST API 常見問答集
<a name="slurm-rest-api-faq"></a>

本節回答有關 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 <job-id>` 檢查任務 – 您將看到 `JobState=PENDING, Reason=JobHeldAdmin`、 和 `SystemComment=slurm_cred_create failure, holding job`。

  **做法**：根本原因可能是 JWT 中的錯誤值。確認字符結構正確，並根據 PCS 文件包含必要的宣告。
+ **工作目錄許可問題**

  如果 JWT 中指定的使用者身分缺少對任務工作目錄的寫入許可，任務將失敗並出現許可錯誤，類似於使用 `sbatch --chdir`搭配無法存取的目錄。

  **做法**：確保 JWT 字符中指定的使用者具有任務工作目錄的適當許可。