cli_filter 插件 API

概述

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

cli_filter 插件的目的是在执行 sallocsbatchsrun 命令行接口 (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 日