Heptapod Runner的Python实用工具和子系统

Heptapod Runner 是 GitLab Runner 的分支，旨在为 Heptapod 和 GitLab 实例工作。

此包提供的服务是 Heptapod Runner 扩展分布的一部分，旨在提供更多选项。它们也与 Heptapod Runner 共享相同的 源代码仓库。

它们不应与主 Heptapod Runner 程序混淆，主程序是一个独立编写在 Go 中的程序（如 GitLab Runner），不依赖于 python-heptapod-runner。

Python 被选为快速原型设计和因为它是 Mercurial 社区的通用语言，但某些功能最终可能用其他语言重写。

heptapod-paas-runner-register

此交互式程序可用于为 heptapod-paas-runner 启动配置。

警告：在所有情况下，配置之后都需要手动完成。

它特别关注对 GitLab 或 Heptapod 实例的注册，因此发挥着类似于 gitlab-runner register 命令的作用。

如果配置文件已存在，它将仅追加一个新的 [[runners] 部分。

配置文件创建注意事项

• 配置文件路径的父目录必须存在，并且可以被进行注册的系统用户写入。
• 生成的配置文件必须可以被heptapod-paas-runner的系统用户读取。
• 状态文件路径的父目录必须可以被heptapod-paas-runner的系统用户写入。

heptapod-paas-runner

该程序的目的在于在遵循PAAS系统预期工作流程的同时提供按需配置。

• 仅在从协调器获取作业后才会为Docker主机进行配置。
• 实际作业启动涉及将Dockerfile推送到控制Docker主机的Git仓库。

进程和状态管理

简单调用

heptapod-paas-runner接受一个位置参数：配置文件路径（见上文中关于heptapod-paas-runner-register的部分）。

有几种选项可供使用，可以使用以下方式显示：

heptapod-paas-runner --help

优雅重启和状态管理

heptapod-paas-runner跟踪它启动的作业，以便在它们完成后释放资源。

为此，它在接收到SIGTERM信号时实现优雅关闭（这是许多进程管理器（包括systemd）使用的默认停止信号）。

接收到信号后，它将

• 停止获取新的作业
• 完成无法中断的操作（启动、退役）
• 将当前跟踪作业所需的所有信息写入文件
• 退出

此关闭序列不是瞬时的。在诉诸更激烈的手段之前，应等待2分钟，这包括缓冲时间。

我们可能会改进中断启动序列，但我们不能中断当前正在运行请求，因为这可能会配置不可追踪的资源。

优雅重载

目前不支持，配置更改可以在优雅重启时不丢失信息。

理论上，适当的重载会更安全。

示例systemd单元文件

[Unit]
Description=Heptapod PAAS Runner
After=network.target

[Install]
WantedBy=multi-user.target

[Service]
User=heptapod-runner
WorkingDirectory=/srv/heptapod-runner
ExecStart=/srv/heptapod-runner/venv/bin/heptapod-paas-runner /etc/heptapod-runner/pass-runner.toml
# We don't need a specific ExecStop, as systemd has a cascading system
# of defaults for the stop signal, with the
# SIGTERM being the ultimate default.

TimeoutStopSec=120
Restart=always
RestartSec=125

配置文件

heptapod-paas-runner使用与正常Heptapod（或GitLab）Runner相同的配置文件。

每个runners部分都有一个executor条目，它必须是PAAS执行器之一，其余部分则是由以下内容混合组成：

• 特定PAAS Runner配置，取决于执行器。
• 标准的GitLab Runner配置，除非由PAAS Runner强制，否则会转发到最终执行器。

当前的PAAS执行器是

• clever-docker（见下文）
• local-docker，仅用于测试和开发目的

注意：heptapod-paas-runner还没有注册功能。实际上，您可以使用任何heptapod-runner或gitlab-runner可执行文件来创建一个配置文件，并使用适当的协调器令牌进行配置，然后将其修改为heptapod-paas-runner。这不必在目标系统上完成。

全局配置

全局配置不会转发到PAAS资源。它用于调整heptapod-paas-runner本身。

• concurrent（默认50）：与标准GitLab Runner中的含义相同。这是所有定义的运行器中作业的最大数量。

• check_interval（默认3）：与标准GitLab Runner中的含义相似。这是完整协调器轮询之间的时间（秒），在以下情况下：

  • 如果协调器授予作业，它将立即重新轮询，除非达到作业限制（作业数量、加权配额和并发配置）
  • 如果达到作业限制，等待时间由job_progress_poll_interval给出（见下文）

• job_progress_interval（默认30）：等待协调器请求之间的时间（秒），以检查启动的作业是否完成。

• quota_computation（必需）：允许通过取一个运行器部分、其中一个相关风味和一个作业数量作为参考来设置加权配额。示例

  [quota_computation]
    reference_runner = "my-runner"
    reference_flavor = "M"
    reference_jobs_count = 4
  
  [[runners]]
    name = "my-runner"
    url = "https://heptapod.example"
    ...
  

  这会将配额设置为后续定义的my-runner运行器中4个带有风味M的工作的权重。

• state_file：用于在优雅重启后跟踪正在运行的作业的文件路径。

• paas_max_concurrent_provisioning (默认 10)：在PAAS基础设施中当前队列的最大并发作业数，这些作业尚未被其协调器确认真正运行。

• paas_finished_jobs_keep_resources（默认 false）：如果设置为true，则不会发生退役。

• pass_decommision_launched_failures（默认 true）：如果设置为false，则在资源似乎已在PAAS基础设施中创建但实际上未启动的情况下，将不会尝试删除它，以便可以检查以了解问题。

全局足迹：权重系统

一些heptapod-paas-runner执行器可以根据作业详细信息使用不同的资源（“风味”）。作业详细信息通常只有在作业获取后才能获得，目前无法撤销。

因此，仅考虑作业数量的并发控制系统将需要削弱其运行小型作业的能力，因为可能运行大型作业。这就是在引入权重系统之前发生的情况。

各种配置的runners使用的权重只是简单相加。请注意，不同执行器的权重通常相差很大，因此在单个heptapod-paas-runner服务中混合多个执行器类型是一个非常糟糕的想法。例如，在撰写本文时，clever-docker执行器的权重范围大约从2到75，而未实现权重的执行器所有值都等于1。

将那些限制平滑到单个服务中是完全可以接受的，甚至是推荐的，只要它们都具有相同的executor。这种情况的典型用例是为几个Heptapod（或纯上游GitLab）实例执行CI。

Docker执行器的常见属性

• 所有标准功能（图像、服务）都受到支持

镜像管理和依赖代理

我们目前没有重用PAAS资源的手段，因此所有作业都从下载所有必要的Docker镜像开始。

部分原因是因为此，Heptapod PAAS Runner会自动使用依赖代理，与标准GitLab Runner Docker执行器不同。

对作业作者的直接影响

• 不要禁用组中的依赖代理

• 如果服务在作业中没有定义别名，则只能使用GitLab Runner通常支持的两个语法之一访问它

  • 如果服务镜像定义为postgres:13，则可以像往常一样访问服务容器postgres
  • 如果镜像定义为tutum/wordpress，则可以像往常一样访问服务容器tutum-wordpress，但不能访问tutum__wordpress

clever-docker执行器

这将在Clever Cloud上运行作业。

Clever Cloud也是托管公共Heptapod实例（用于免费和开源软件）的公司，其中Heptapod是自托管的，并且是商业Heptapod实例。

有两种操作模式：单一组织和多租户。

常见配置

必需

• executor: clever-docker
• cc_extra_env子部分。可以用于将额外环境传递给在提供的资源上生成的子运行器。目前需要CC_ENABLE_HEPTAPOD_RUNNER = "true"

可选

• cc_api_url（默认为https://api.clever-cloud.com/v2）：Clever Cloud基本API URL
• cc_zone（默认为par）：理论上可以使用任何区域。实际上，区域最好靠近GitLab / Heptapod实例（协调器）。
• cc_default_flavor（默认为M）：如果作业未指定，将在Clever Cloud上启动的实例的flavor（大小）。
• [job_trace_watch]（强烈推荐）：此部分允许监视用户级作业日志（内部称为“作业跟踪”），以限制正在配置且尚未完全启动的并发作业的数量，并在出现问题时提供更快的用户反馈。项目包括
  • token：遗憾的是，必须是具有read-api范围的管理员令牌。Heptapod的未来版本应该能够避免这种情况，但可能不是GitLab的源代码。
  • timout_seconds（默认300）：作业启动被视为失败的时间。
  • poll_step（默认10）：检查作业跟踪的时间间隔（秒）。
• cc_deployment_repo_timeout（默认20）：等待Clever Cloud的部署Git仓库准备就绪的最大时间（秒）。
• cc_deployment_repo_wait_step（默认2）：评估Clever Cloud的部署Git仓库是否就绪的请求之间的时间。

为单个Clever Cloud组织运行

将这些放入运行器配置中

• cc_multi_tenant：未指定或false。
• cc_orga_id：指定您的Clever Cloud组织ID，例如，在Clever Cloud控制台的概览页中查看。
• cc_token：Clever Cloud API的令牌，拥有足够的权利创建、部署和删除应用程序和实例。

无论运行器是否绑定到特定项目、组或整个GitLab / Heptapod实例：所有资源都将附加（并收费）到指定的组织。

这对于自托管Heptapod实例来说是个不错的选择。

完整示例

state_file = "/srv/heptapod-runner/paas-runner-state.json"

[quota_computation]
  reference_runner = "clever-cloud"
  reference_flavor = "3XL"
  reference_jobs_count = 8

[[runners]]
  name = "clever-cloud"
  url = "https://heptapod.example.com"
  token = "D3adNQYu8OCjkYDbwDaG"
  executor = "clever-docker"

  cc_orga_id = "orga_07cf2ef0-c9ad-4f04-b492-94c164f95c76"
  cc_token = "bb52e490-d47e-47a4-b190-73e23eb17111"

  [runners.cc_extra_env]
    CC_ENABLE_HEPTAPOD_RUNNER = "true"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    # A future version of Heptapod PAAS Runner may fill this in automatically.
    # Meanwhile it is possible to use any S3 configuration. Using Clever's
    # Cellar for your CI caches in the same zone is the best for
    # network proximity and bandwidth.
    # (replace with your credentials and bucket of choice)
    ServerAddress = "cellar-c2.services.clever-cloud.com"
    AccessKey = "dEA7gjmYM98gobVi6Y1x"
    SecretKey = "v0tdpjgpsDRqaSvIndvHAXFmjbpEd958gbZuO7yv"
    BucketName = "heptapod-ci"
    [runners.cache.gcs]
  [runners.docker]
    helper_image = "registry.heptapod.net/heptapod/heptapod-runner/helper:x86_64-latest"
    tls_verify = false
    image = "debian:bullseye"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

（此示例中所有令牌和uuid都是为这份文档新鲜获得的随机值）

多租户模式

在此模式下，运行器从属于项目的顶层Heptapod组的高级属性中确定Clever Cloud组织及其关联的API令牌。

它假设有人填充了这些属性。

此操作模式适用于类似heptapod.host的实例。

必需的运行器配置

• cc_multi_tenant：true
• cc_gitlab_namespace_attributes_token：GitLab / Heptapod的私有令牌，具有查询组自定义属性的权利。

可选的运行器配置

• cc_orga_id_attribute（默认为cc_orga_id）。用于组织ID的顶级组上自定义属性的名称。
• cc_orga_token_attribute (默认为cc_orga_token）。用于组织Clever API令牌的顶级组上自定义属性的名称。

完整示例

state_file = "/srv/heptapod-runner/paas-runner-state.json"

[quota_computation]
  reference_runner = "clever-cloud"
  reference_flavor = "3XL"
  reference_jobs_count = 8

[[runners]]
  name = "clever-cloud"
  url = "https://heptapod.example.com"
  token = "D3adNQYu8OCjkYDbwDaG"
  executor = "clever-docker"

  cc_multi_tenant = true
  cc_gitlab_namespace_attributes_token = "D7aY5I5SygxA5oyZ11vB"

  [runners.cc_extra_env]
    CC_ENABLE_HEPTAPOD_RUNNER = "true"

  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    # Do not fill in this: it would use the same bucket for all tenants.
    # A future version of Heptapod PAAS Runner will fill this automatically,
    # using the Cellar add-on of each tenant for proper separation.
    [runners.cache.gcs]
  [runners.docker]
    helper_image = "registry.heptapod.net/heptapod/heptapod-runner/helper:x86_64-latest"
    tls_verify = false
    image = "debian:bullseye"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0

（此示例中所有令牌都是为这份文档新鲜获得的随机值）

flavor及其权重

最终用户可以控制运行其作业的Clever Cloud实例的flavor（大小）。这是通过使用CI_CLEVER_CLOUD_FLAVOR作业变量来完成的，当前可接受值从XS到3XL。

clever-docker执行器实现了上述权重系统，以限制整个运行器服务在Clever中的最大占用，同时考虑不同flavor之间的差异。

如果希望允许最多N个具有flavorF的作业，最简单的方法是使用quota_computation部分（见上文）。或者，可以将全局配置参数concurrent设置为N*F.weight。然后，权重系统将自动调整典型负载的含义，该负载可能包含比F更大的或更小的实例。

预计权重计算将在未来发生变化，因为它只是实际基础设施约束的近似，因此最好使用quota_computation而不是concurrent。

目前，香味的权重计算方式为 M^1.25，其中 M 是香味的内存占用，以 GiB 为单位。该公式的非线性将允许在实际中孵化更多较小的香味，而总内存占用保持等效。