cli_filter 插件 API

概述

本文档描述了 Slurm cli_filter 插件及其定义的 API。它旨在为希望编写自己 Slurm cli_filter 插件的程序员提供资源。

cli_filter 插件的目的是在执行 salloc、sbatch 和 srun 命令行接口 (CLI) 程序时提供编程钩子。定义了三个钩子：

cli_filter_p_setup_defaults — 在任何选项处理之前调用，每个作业组件，允许插件替换默认选项值。
cli_filter_p_pre_submit — 在选项处理 每个作业组件 之后但在与 slurm 控制器进行任何通信之前调用。此位置非常适合执行策略 enforcement，因为插件可以读取用户提供的所有选项（以及环境） - 因此无效的作业请求可以在到达 slurmctld 之前被阻止。
cli_filter_p_post_submit — 在生成 jobid（在 srun 的情况下，在生成 stepid 之后）之后调用，通常在作业执行之前或与之并行。结合在 cli_filter_p_pre_submit() 钩子中收集的数据，这是记录活动的理想位置。

cli_filter 插件与 job_submit 插件不同，因为它完全在客户端执行，而 job_submit 在服务器端处理（在 slurm 控制器内）。cli_filter 的好处在于它可以在简单一致的接口中访问所有命令行选项，并且更安全地运行破坏性操作（例如，配额检查或其他您可能希望用于集成政策决策的长时间运行的操作），如果从控制器运行则可能会出现问题。cli_filter 的缺点是它不应被依赖于安全目的，因为有心的用户可以通过提供禁用 CliFilterPlugins 选项的替代 slurm.conf 来轻松规避它。如果您计划使用 cli_filter 来管理策略，您还应该配置一个 job_submit 插件来加强这些政策。

Slurm cli_filter 插件必须符合 Slurm 插件 API，具有以下规范：

const char plugin_name[]="完整文本名称"

一个自由格式的 ASCII 文本字符串，用于标识插件。

const char plugin_type[]="主/次"

主类型必须是 "cli_filter." 次类型可以是适合作业提交包类型的任何名称。我们在 Slurm 分发中包含示例：

none — 一个不执行任何操作的空插件，是新插件的有用起始模板。

const uint32_t plugin_version
如果指定，标识用于构建此插件的 Slurm 版本，任何尝试从不同版本的 Slurm 加载插件将导致错误。如果未指定，则插件可以由任何版本的 Slurm 命令和守护进程加载，但这可能会导致由于插件函数参数或插件使用的其他 Slurm 函数的更改而导致难以诊断的故障。

如果需要，Slurm 可以配置为使用多个 cli_filter 插件，但 lua 插件将仅执行一个名为 "cli_filter.lua" 的 lua 脚本，该脚本位于默认脚本目录中（通常是安装目录的子目录 "etc"）。

API 函数

以下所有函数都是必需的。未实现的函数必须是存根。

int init(void)

描述:
当插件加载时调用，在调用任何其他函数之前。请在此处进行全局初始化。

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败。

void fini(void)

描述:
当插件被移除时调用。在此处清除任何分配的存储。

返回: 无。

注意: 这些 init 和 fini 函数与 dlopen (3) 系统库中描述的不同。 C 运行时系统会占用这些符号进行自己的初始化。系统 _init() 在 Slurm init() 之前被调用，而 Slurm fini() 在系统的 _fini() 之前被调用。

int cli_filter_p_setup_defaults(slurm_opt_t *options, bool early)

描述:
此函数在 salloc、sbatch 或 srun 命令行接口 (CLI) 程序中调用，紧接着处理环境、命令行或脚本 (#SBATCH) 中的任何选项之前。钩子可以在每个作业组件中多次运行，一次用于早期处理（如果 CLI 实现），再一次用于主要处理。请注意，此调用在现有作业分配中运行的任何 srun 命令中被跳过，以防止设置覆盖基于作业环境填充的选项集。选项和 early 参数旨在传递给 slurm_option_set()，如果在适当的处理阶段，它将设置该选项。设置选项失败可能是尝试在错误的处理阶段设置选项的症状。鉴于此，您不应仅仅因为设置选项失败而返回 SLURM_ERROR。

参数:
options （输入）slurm 选项数据结构；旨在传递给 src/common/slurm_opt.h 中的 slurm_option_* API。
early （输入）布尔值，指示这是否是早期处理；旨在传递给 src/common/slurm_opt.h 中的 slurm_option_* API。

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败，将终止 CLI 的执行。

int cli_filter_p_pre_submit(slurm_opt_t *options, int offset)

描述:
此函数在选项处理后由 CLI 调用，但在与 slurmctld 进行任何通信之前。此时所有 cli_filter_p_setup_defaults() 钩子（针对当前作业组件）已执行，环境变量已处理，命令行选项和 #SBATCH 指令已解释。 cli_filter_p_pre_submit() 在数据结构的任何部分被重写之前调用，因此安全地读取和写入或取消设置您希望从插件中读取的任何选项。请注意，cli_filter_p_post_submit() 不能安全地读取（或写入）选项，因此您应该在 cli_filter_p_pre_submit() 中保存任何状态以供 cli_filter_p_post_submit() 使用。此函数每个作业组件调用一次。

参数:
options （输入/输出）作业分配请求规范。
offset （输入）当前 hetjob 偏移的整数值；应作为键在 cli_filter_p_pre_submit() 和 cli_filter_p_post_submit() 之间存储数据时使用。

返回:
SLURM_SUCCESS 表示成功，或
SLURM_ERROR 表示失败，将终止 CLI 的执行。

void cli_filter_p_post_submit(int offset, uint32_t jobid, uint32_t stepid)

描述:
此函数在控制器分配 jobid（如果是 srun，则分配 stepid）之后由 CLI 调用。此时不再安全读取或写入选项数据结构，因此已从此函数中移除。您应该在 cli_filter_p_pre_submit() 中使用 het_job_offset 作为键保存所需的任何状态，因为该函数针对每个作业组件单独调用，并在此处访问。

参数:
offset （输入）当前 hetjob 偏移的整数值；应作为键在 cli_filter_p_pre_submit() 和 cli_filter_p_post_submit() 之间存储数据时使用。
jobid （输入）作业的作业 ID
stepid （输入）作业的步骤 ID（如适用），否则为 NO_VAL

LUA 接口

在 slurm.conf 中设置 CliFilterPlugins=cli_filter/lua 将允许您使用 Lua 语言实现提到的 API 函数。该文件必须命名为 "cli_filter.lua"，并且与 job_submit 插件类似，必须位于默认配置目录中（通常是安装目录的子目录 "etc"）。源代码中提供了一个示例，您可以在这里找到。

注意: 尽管可用选项在 slurm_opt_t 结构中定义，但某些选项可能会被重命名。提供的示例展示了一种通过使用 slurm.json_cli_options(options) 显示配置选项的方法。

用户默认设置

在 slurm.conf 中设置 CliFilterPlugins=cli_filter/user_defaults 将允许用户为从配置文件提交的机器提交的作业定义自己的默认值。插件在 $HOME/.slurm/defaults 中查找定义文件。它将读取每一行作为 component=value 对，其中 component 是可用于 salloc、sbatch 或 srun 的任何作业提交选项，而 value 是用户定义的默认值。以下示例将配置每个作业具有默认名称、时间限制、内存量以及错误和输出文件：

job-name=default_name
time=10:00
mem=256
error = slurm-%j.errfile
output = slurm-%j.logfile

您还可以根据用于提交作业的命令和/或提交到的集群指定不同的默认设置。其语法为：
<command>:<cluster>:<component>

<command> 可以是以下之一：

salloc：使用 salloc 命令提交的作业。
sbatch：使用 sbatch 命令提交的作业。
srun：使用 srun 命令提交的作业。
*：使用任何提交命令提交的作业。

<cluster> 可以是您系统上定义的任何集群，或 * 以匹配任何集群。

<component> 是可用于 salloc、sbatch 或 srun 的任何作业提交选项。

以下示例将根据用于提交作业的命令分配不同的默认分区。它还将根据所使用的集群为使用 salloc 提交的作业分配不同的分区：

salloc:cluster1:partition = interactive
salloc:cluster2:partition = member
sbatch:*:partition = high
srun:*:partition = short

最后修改于 2024 年 2 月 19 日