SPANK (Slurm Plug-in)
===
###### tags: `SlinkyProject`
###### tags: `Kubernetes`, `k8s`, `app`, `slurm`, `SlinkyProject`, `SPANK`

<br>

[TOC]

<br>

## Slurm / SPANK
> https://slurm.schedmd.com/spank.html

- ### SPANK
- Slurm Plug-in Architecture for Node and job (K)control
(Slurm 節點與工作控制的外掛架構)
- **簡介**
SPANK 是 Slurm 的外掛架構，讓管理員可動態擴充與修改工作啟動行為。它支援多種執行環境（context）和多種插件回調函式，並提供擴充命令列選項的能力，方便自訂 Slurm 工作流程。

- ### 關於手冊
- 本手冊簡要說明 Slurm 節點與工作控制外掛架構（SPANK）的功能，以及 SPANK 的設定檔（預設為 `plugstack.conf`）。
- SPANK 提供一個非常通用的介面，用於堆疊式外掛，可用來動態修改 Slurm 的工作啟動程式碼。SPANK 外掛不需要取得 Slurm 原始碼即可編譯，只需針對 Slurm 的 `spank.h` 標頭檔進行編譯，並將外掛加入 SPANK 設定檔 `plugstack.conf`，即可在下次工作啟動時被載入執行。因此，SPANK 架構讓系統管理員及開發者能以低成本、低工時的方式，動態調整 Slurm 工作啟動時的執行行為。
- **注意**
所有 SPANK 外掛在升級 Slurm 到新版主版本時，都應重新編譯。SPANK API 在主版本間並不保證 ABI 相容。任何連結 Slurm 函式庫的 SPANK 外掛，皆應謹慎檢查，因為 Slurm API 及標頭檔可能在主版本間有所變動。
- **FILES**
- `/etc/slurm/slurm.conf` - Slurm configuration file.
- `/etc/slurm/plugstack.conf` - SPANK configuration file.
- `/usr/include/slurm/spank.h` - SPANK header file.

- ### gpt-4.1-mini (2025/06/26)
這份 SPANK 文件非常詳盡，涵蓋了 SPANK 插件的載入時機、插件可實作的函式、錯誤處理行為、配置方式，以及用於擴充 Slurm 功能的選項接口。以下是幾個重點與注意事項，供你在使用和開發 SPANK 插件時參考：

---

### 1. 插件載入的五種「Context」（執行環境）

* **local**：由 `srun` 載入，代表平行工作的「本地端」部分。
* **remote**：由 `slurmstepd` 載入，代表平行工作的「遠端」部分。
* **allocator**：由工作配置工具（如 `salloc`, `sbatch`, `scrontab`）載入。
* **slurmd**：在 `slurmd` 守護進程中載入，且會持續整個守護進程執行期間。修改設定或更新插件後需重啟 `slurmd`。
* **job\_script**：在工作 prolog 或 epilog 腳本的上下文中載入，每次執行 prolog/epilog 都會重新載入，且與 slurmd context 狀態互不影響。

**注意：** 不同 context 中會呼叫不同的 callback 函式，且 context 之間狀態不共用。

---

### 2. 主要可實作的函式 (Callbacks)

插件可實作多種函式，如：

* `slurm_spank_init`：初始化，插件載入後立即呼叫。
* `slurm_spank_job_prolog` / `slurm_spank_job_epilog`：工作啟動前後的回調。
* `slurm_spank_exit`：工作或守護進程退出時呼叫。
* 任務初始化與退出相關函式（如 `slurm_spank_task_init`, `slurm_spank_task_exit`）等。

**注意：** 若 `job_prolog` 或 `job_epilog` 回傳非零值且該插件是必須的，會導致該節點被標記為 drained。

---

### 3. 插件錯誤處理與節點/工作的影響

文件中有詳細的錯誤行為對照表，說明不同函式在不同 context 返回錯誤時：

* 是否會標記節點為 drained（不可用）。
* 是否會導致工作失敗（是否重新排隊）。

例如：`slurm_spank_init` 在 local context 回傳錯誤會使工作失敗，但不會 drain 節點；在 remote context 回傳錯誤則不會失敗也不會 drain 節點。

---

### 4. 配置檔 `plugstack.conf`

* 插件透過這個配置檔指定是否必須（required）或選用（optional）。
* 支援多個插件堆疊，依序載入。
* 可用 `include` 關鍵字引用其他配置檔案或目錄，方便管理。
* **必須確保集群所有節點的設定檔一致，否則可能導致行為不一。**

---

### 5. 插件選項擴展機制

* 插件可以定義自訂命令列參數，並由 Slurm 的 srun/salloc/sbatch 等命令接收使用者輸入，並在遠端節點中傳遞。
* 使用 `struct spank_option` 結構定義選項，包括名稱、參數描述、說明、是否需要參數，以及回調函式。
* 本地端會先呼叫回調以做參數檢查，遠端節點則在插件初始化前註冊參數，根據參數改變插件行為。

---

### 6. 環境變數存取

* 在 local 和 allocator context，使用標準 libc 的 `getenv`、`setenv`、`unsetenv` 修改環境變數。
* 在 remote context，需使用 SPANK 提供的 `spank_getenv`、`spank_setenv`、`spank_unsetenv`。
* 可建立傳給 Slurm Prolog/Epilog 的特殊環境變數，名稱前綴會自動加上 `SPANK_` 以避免安全風險。

---

### 7. 注意 API 及 ABI 相容性

* 升級 Slurm 主版本時，必須重新編譯所有 SPANK 插件，因為 API/ABI 可能會變動。
* 插件不得直接存取 Slurm 內部資料結構，需透過 `spank_get_item` 等介面間接取得工作相關資訊。

---

### 8. 其他重要事項

* **插件必須安裝在執行 `slurmd` 的節點（計算節點）和執行分配工具（如 `salloc`、`sbatch`）的節點（登入節點）。**
* 插件可檢查是否支援特定的 hook 函式（symbols）以確保相容性。
* 出錯時可用 `spank_strerror()` 將錯誤碼轉換成字串，並用 `slurm_spank_log()` 記錄錯誤訊息。

---

### 總結

這份文件主要強調了：

* SPANK 的多環境、多階段載入特性與插件函式分工。
* 插件可動態擴充 Slurm 的工作啟動與控制行為。
* 錯誤處理行為會影響工作和節點狀態，且須小心配置。
* 插件與 Slurm 主版本間的相容性限制。
* 配置檔管理與多插件堆疊機制。

若您是開發或管理 SPANK 插件，務必注意上述細節，尤其是插件上下文的區分、錯誤影響行為、版本相容性及配置一致性。

<br>

{%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}