队列

一个健壮的、用户级别的、工作窃取的分布式任务调度器。

为什么选择 Kueue？

Kueue 在大学研究环境中开发。通常，科学实验是通过多次运行商业工具或自定义脚本来进行的，每次执行都需要一定数量的硬件资源和运行时间。同时，可用的计算基础设施是异构的，从几台专用服务器到可能偶尔重启的一堆实验室工作站。在这样的环境中，将工作负载分配到不同的机器可能是一个繁琐的任务：哪些机器当前是空闲的？我可以在每台机器上启动/安排多少个作业？我的脚本是否已经完成，或者机器在此期间是否已重新启动？

Kueue 尝试减轻这些任务，同时尽可能保持易用性。其易用性和简单的配置部分灵感来源于我长时间使用的 任务队列。使用 Kueue 运行作业应该与在本地机器上使用命令行一样简单。在实践中，使用 Kueue 在任何空闲机器上运行 ./my_script.py 可以通过一个简单的前缀来实现：kueue cmd ./my_script.py。

当 ... 时，Kueue 可能适合您：

• 您只有可用的计算机器上的用户权限。
• 简单的命令行界面足以满足您的需求。
• 您正在使用定期重启或关机的机器。
• 简单的设置比丰富的功能集更重要。

当 ... 时，Kueue 可能不适合您：

• 您具有 root 权限，可以安装一个成熟的（多用户）调度系统。
• 您没有共享文件系统，因此需要将数据附加到作业查询。

准备

Kueue采用客户端-服务器模型，需要将kueue_server运行在一台机器上，而kueue_worker则运行在所有需要进行作业执行任务的机器上。需要确保kueue_server进程可以通过一个（可自由指定的）TCP网络端口进行访问。与worker类似，kueue（命令行客户端）也使用服务器上的相同TCP端口连接到服务器。身份验证通过一个必须在所有机器上相同的shared_secret进行。Kueue完全在用户级别模式下运行，所有作业都是使用启动kueue_worker时的权限来执行的。因此，请确保不要在您的配置中泄露shared_secret，否则其他人可以代表您启动进程！

在许多基础设施中，/home和其他目录通过网络挂载/同步。如果用户的家目录被同步，那么位于~/.config/kueue/config.toml的配置可以轻易地被所有进程访问。否则，您可能需要手动将配置分布到所有机器上。所有计划中的作业都是相对于它们的当前工作目录执行的。worker只有在它们可以看到相同的目录（或它们系统上的相同路径的目录）时才会执行作业。

安装

获取Kueue的最简单方法是直接从crates.io下载。这需要您首先安装Rust，如果已安装基本依赖项，则无需root权限。默认情况下，所有文件都将安装到您的家目录中。在同步家目录的环境中，这意味着您通常只需要进行一次安装过程。

安装Rust

确保您已安装C/C++编译器。然后，像往常一样安装Rust。

curl https://sh.rustup.rs -sSf | sh

安装OpenSSL

您需要安装OpenSSL头文件作为Kueue的依赖项。在许多系统中，它可能已经安装了。在Ubuntu上，以下包就足够了

sudo apt install pkg-config libssl-dev

在Fedora上，以下包解决了缺失的依赖问题

sudo dnf install openssl-devel

安装Kueue

最后，使用Cargo（它是Rust安装的一部分）来安装（或更新）Kueue。

cargo install kueue

这将安装kueue（客户端）、kueue_server和kueue_worker到Rust安装的bin文件夹中。

基本配置

在首次启动任何Kueue二进制文件时，会在~/.config/kueue/config.toml创建一个模板配置文件。查看默认设置并调整以满足您的需求是值得的。所有设置的说明可以在文档中找到。

最重要的设置在[common_settings]部分。请确保您配置中的shared_secret在您希望使用的所有系统上都是相同的。对于server_name和server_port，客户端和worker使用它连接到服务器，这也可能是相同的。

[common_settings]
shared_secret = "keep private!"
server_name = "ralab29"
server_port = 11236

要开始，请在用作服务器的机器上运行kueue_server，在您想要执行作业的所有机器上运行kueue_worker。请注意，这些程序以前台启动，所以您可能需要使用像screen这样的工具将进程发送到后台，并在您未登录时保持它们存活。

全局资源（例如许可证管理）

Kueue可以处理必须在所有工作者之间同时尊重的“全局”资源，例如许可证。我们通过示例演示如何使用此功能。要开始，请向您的配置中添加一个新的资源表，命名为[global_resources]。之后，每行指定一个资源，如下例所示。

[global_resources]
primelib = 31
genus = 3

在这个例子中，我们指定了两种许可证及其可同时被作业使用的数量。假设my_script.sh运行需要一个genus许可证。这可以通过以下命令实现

kueue cmd --resource genus ./my_script.sh

在以下示例中，我们的脚本不仅需要一个genus许可证，还需要4个primelib许可证

kueue cmd --resource genus --resource primelib=4 ./my_script.sh

通过相应地提供所需的全球资源，Kueue可以无冲突地调度作业。

重启工作者

Kueue附带一个名为kueue_restart_workers的简单工具，该工具检查工作者的状态，并在它们出现故障时尝试重启它们。要使用此工具，请向您的config.toml添加一个新块，如下所示

[restart_workers]
ssh_user = "klemmefn"
hostnames = """
rax11   rax17   rax19   rax32
ralab04 ralab06 ralab07 ralab08
ralab10 ralab11 ralab13 ralab14
ralab16 ralab18 ralab22 ralab23
ralab24 ralab25 ralab26 ralab27
"""
sleep_minutes_before_recheck = 60

目前，该工具使用您的SSH密钥连接到工作者，并使用screen在后台启动工作者任务。请确保screen已安装在工作者上，并且通过密钥的ssh登录是可能的。然后，您可以使用此工具如下

# Make sure your SSH key is loaded.
eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa
# Spawn "restart_workers" in the background.
screen kueue_restart_workers

请注意，kueue_restart_workers不是Kueue工作的必需品，而是一个简化工作者重启的简单工具。您也可以使用任何其他策略来启动和重启您的远程工作者。

常见问题解答（FAQ）

如何升级到新版本？

1. 如果您正在使用kueue_restart_worker来启动您的工作者进程，请先停止它。
2. 停止kueue_server。这将终止所有连接的工作者进程。
3. 在所有您的机器（或Kueue安装）上运行cargo install kueue。如果您有一个共享的主目录，则单个cargo install kueue可能已经足够。
4. 更新完成后，重启kueue_server。如果服务器在您的配置中抱怨有未识别的设置，请阅读以下常见问题解答。
5. 重启您的工作者，例如再次启动kueue_restart_worker。

如何获取新的配置文件（TOML）版本？

在许多情况下，在更新Kueue时不需要更新配置文件。对于任何缺失的设置，都假定默认值。所有设置的默认值都可以在首次启动时生成的初始模板配置文件中找到。

每次启动任何kueue二进制文件时，如果不存在现有的配置文件，都会创建一个模板配置文件。因此，更新配置文件的一个简单方法是进行备份（例如，重命名配置文件），然后简单地运行一次kueue。之后，将您的备份配置与新生成的模板进行比较，并按您喜欢的设置进行调整。

启动服务器时出错！

INFO  [kueue_server::server] Successfully started listening on 0.0.0.0:11236...
ERROR [kueue_server::server] Failed to start listening on [::]:11236: Address already in use (os error 98)

kueue_server 支持监听多个接口，这些接口在配置文件中的 bind_addresses 中定义。这可能会很有用，例如，如果您想允许客户端通过 IPv4（0.0.0.0）或 IPv6（[::]）连接。服务器将尝试使用在 server_port 中指定的端口单独绑定每个地址。虽然在某些系统上工作良好，但其他系统可能会在 0.0.0.0 或 [::] 存在的情况下自动绑定 IPv4 和 IPv6 地址。在这种情况下，您会收到上面的错误消息，因为服务器尝试绑定相同的地址两次。您可以忽略此消息（服务器仍将正常工作），或者您可以通过从 bind_addresses 中删除 0.0.0.0 或 [::] 来修复它。

如何设置 shell 完成功能？

kueue 客户端支持通过 clap_complete 在命令行上使用 shell 完成功能。调用 kueue complete 和您的 shell 名称作为另一个参数将返回您相应 shell 的完成脚本。您可以直接评估返回的脚本，或将它保存到文件中稍后加载。一种简单的方法（已在 bash 和 zsh 上测试过）是将 eval 语句直接放入您的启动脚本中。例如，对于 bash，将 eval "$(kueue complete bash)" 放入您的 ~/.bashrc 脚本中，对于 zsh，将 eval "$(kueue complete zsh)" 放入您的 ~/.zshrc 脚本中。