当前位置：首页 > ops >正文

ARC 02 runner scale set chart:对接集群与 Github Action 服务器

ops 2025/7/14 7:18:19

背景

controller chart 安装的 controller 容器将四个自定义资源控制器注册进入集群。
runner scale set chart 安装的资源将使得仓库 runner 连接 Github Action 服务器。

安装

同样用 helm 安装 runner scale set chart。controller chart 可以用默认的 values.yaml，但是 runner chart 必须自定义 values.yaml以指定仓库以及仓库权限。
values.yaml的常见配置如下：

## Github 仓库地址
githubConfigUrl: https://github.com/myorg/myrepo## Github token 用于 runner 通过Github API 连接 Github Action 服务器。可以是PAT，也可以是 Github App。
githubConfigSecret:github_token: "ghp_sampleSampleSampleSampleSampleSample"## 集群中最大 runner 数。受限于集群资源。
maxRunners: 5## runner scale set 所属 group，一般不用填，后面源码会用到
# runnerGroup: "default"## 集群中最小 runner 数。
minRunners: 0## prometheus 监听指标
listenerMetrics:counters: gha_started_jobs_total: ## 已启动的 job 总数labels:["repository", "organization", "enterprise", "job_name", "event_name", "job_workflow_ref"]gha_completed_jobs_total: ## 已完成的 job 总数labels:["repository","organization","enterprise","job_name","event_name","job_result","job_workflow_ref",]## runner pod 的 spec
template:spec:containers:- name: runnerimage: ghcr.io/actions/actions-runner:latest ## runner pod 所用镜像。tag 不设置为 latest，设置为某个版本以保证系统安全稳定。command: ["/home/runner/run.sh"] ## 入口脚本

部署脚本：

helm install "arc-runner-set" \--namespace "arc-runners" \--create-namespace \-f your-custom-values.yamloci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set--version=0.12.0

"arc-runner-set"是 chart 的部署名称，也是 Github 仓库展示的 runner scale set 名称。
"arc-runners"是 chart 的部署 namespace。为了隔离安全，一般不与 controller chart 同一个 namespace。
-f your-custom-values.yaml: 指定 values.yaml

它用 values.yaml 文件渲染如下AutoscalingRunnerSet资源，并且将其部署到 kubernetes 集群。

apiVersion: actions.github.com/v1alpha1
kind: AutoscalingRunnerSet
metadata:name: arc-runner-setnamespace: arc-runners
spec:githubConfigUrl: https://github.com/myorg/myrepogithubConfigSecret: "ghp_sampleSampleSampleSampleSampleSample" 
maxRunners: 5
minRunners: 0
template:spec:containers:- name: runnerimage: ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]

源码

四个控制器中，第一个处理AutoscalingRunnerSet资源的是AutoscalingRunnerSet控制器。它的 Reconcile 函数源码。控制器按照如下步骤创建资源：

校验AutoscalingRunnerSet资源的版本是否与 controller image 的版本一致。也就是校验 controller chart 与 runner scale set chart 的版本是否一致。

// build.Version 是 controller image 的版本
// LabelKeyKubernetesVersion 是 runner scale set 的版本
if !v1alpha1.IsVersionAllowed(autoscalingRunnerSet.Labels[LabelKeyKubernetesVersion], build.Version) {

添加 finalizer 字段，阻止集群删除本资源。

autoscalingRunnerSetFinalizerName = "autoscalingrunnerset.actions.github.com/finalizer"if !controllerutil.ContainsFinalizer(autoscalingRunnerSet, autoscalingRunnerSetFinalizerName) {log.Info("Adding finalizer")if err := patch(ctx, r.Client, autoscalingRunnerSet, func(obj *v1alpha1.AutoscalingRunnerSet) {controllerutil.AddFinalizer(obj, autoscalingRunnerSetFinalizerName)

控制器调用 Github API 根据资源的 runnerGroup 字段获取 runner group Id。并且将 runner group Id 和资源名称组合作为唯一标识向 Github Action 服务器注册自身。服务器返回 runner scale set id 表示注册成功。控制器将 id 局部更新给资源。

        runnerScaleSet, err = actionsClient.CreateRunnerScaleSet( // 向服务器注册ctx,&actions.RunnerScaleSet{Name:          autoscalingRunnerSet.Spec.RunnerScaleSetName, // 资源名称RunnerGroupId: runnerGroupId, // runner group IdLabels: []actions.Label{{Name: autoscalingRunnerSet.Spec.RunnerScaleSetName,Type: "System",},},RunnerSetting: actions.RunnerSetting{Ephemeral:     true,DisableUpdate: true,},})

    if err = patch(ctx, r.Client, autoscalingRunnerSet, func(obj *v1alpha1.AutoscalingRunnerSet) {obj.Annotations[AnnotationKeyGitHubRunnerScaleSetName] = runnerScaleSet.Name // 服务器返回的资源名称obj.Annotations[runnerScaleSetIdAnnotationKey] = strconv.Itoa(runnerScaleSet.Id) // 服务器返回的 scale set idobj.Annotations[AnnotationKeyGitHubRunnerGroupName] = runnerScaleSet.RunnerGroupName // 服务器返回的 runner group

以AutoscalingRunnerSet资源为模板创建EphemeralRunnerSet资源(之后分析)和AutoscalingListener资源。
AutoscalingListener资源如下。它保存RunnerScaleSetId。

autoscalingListener := &v1alpha1.AutoscalingListener{ObjectMeta: metav1.ObjectMeta{Name:        scaleSetListenerName(autoscalingRunnerSet), // Name 由`AutoscalingRunnerSet`资源的name 和 namespace 组成Namespace:   namespace,Labels:      labels,Annotations: annotations,},Spec: v1alpha1.AutoscalingListenerSpec{GitHubConfigUrl:               autoscalingRunnerSet.Spec.GitHubConfigUrl,GitHubConfigSecret:            autoscalingRunnerSet.Spec.GitHubConfigSecret,VaultConfig:                   autoscalingRunnerSet.VaultConfig(),RunnerScaleSetId:              runnerScaleSetId, // runner scale set idAutoscalingRunnerSetNamespace: autoscalingRunnerSet.Namespace,AutoscalingRunnerSetName:      autoscalingRunnerSet.Name,EphemeralRunnerSetName:        ephemeralRunnerSet.Name,MinRunners:                    effectiveMinRunners,MaxRunners:                    effectiveMaxRunners,Image:                         image,ImagePullSecrets:              imagePullSecrets,Proxy:                         autoscalingRunnerSet.Spec.Proxy,GitHubServerTLS:               autoscalingRunnerSet.Spec.GitHubServerTLS,Metrics:                       autoscalingRunnerSet.Spec.ListenerMetrics,Template:                      autoscalingRunnerSet.Spec.ListenerTemplate,},}

AutoscalingRunnerSet控制器的工作至此结束。接下来是AutoscalingListener控制器处理AutoscalingListener资源。

添加 finalizer 字段，阻止集群删除本资源。

if !controllerutil.ContainsFinalizer(autoscalingListener, autoscalingListenerFinalizerName) {log.Info("Adding finalizer")if err := patch(ctx, r.Client, autoscalingListener, func(obj *v1alpha1.AutoscalingListener) {controllerutil.AddFinalizer(obj, autoscalingListenerFinalizerName)

从AutoscalingRunnerSet资源获取 Github token，即Values.yaml文件的 githubConfigSecret 字段。

appConfig, err := r.GetAppConfig(ctx, &autoscalingRunnerSet)

创建 serivceaccount, role 和 role_binding 资源。使得之后创建的 listener pod 有权限访问资源。
将AutoscalingListener资源的配置写入 config 结构体，包括RunnerScaleSetId。并且将qi secret 资源保存到集群。

    config := ghalistenerconfig.Config{ConfigureUrl:                autoscalingListener.Spec.GitHubConfigUrl,EphemeralRunnerSetNamespace: autoscalingListener.Spec.AutoscalingRunnerSetNamespace,EphemeralRunnerSetName:      autoscalingListener.Spec.EphemeralRunnerSetName,MaxRunners:                  autoscalingListener.Spec.MaxRunners,MinRunners:                  autoscalingListener.Spec.MinRunners,RunnerScaleSetId:            autoscalingListener.Spec.RunnerScaleSetId, // runner scale set idRunnerScaleSetName:          autoscalingListener.Spec.AutoscalingRunnerSetName,ServerRootCA:                cert,LogLevel:                    scaleSetListenerLogLevel,LogFormat:                   scaleSetListenerLogFormat,MetricsAddr:                 metricsAddr,MetricsEndpoint:             metricsEndpoint,Metrics:                     autoscalingListener.Spec.Metrics,}return &corev1.Secret{ObjectMeta: metav1.ObjectMeta{Name:      scaleSetListenerConfigName(autoscalingListener),Namespace: autoscalingListener.Namespace,},Data: map[string][]byte{"config.json": buf.Bytes(), // buf 来自 config 结构体},}, nil

创建 listener pod。跟 controller pod 一样，业务镜像也是ghcr.io/actions/gha-runner-scale-set-controller。但是 command 是 /ghalistener，从 Dockerfile 可以看出，它的 main() 函数。

    listenerEnv := []corev1.EnvVar{{Name:  "LISTENER_CONFIG_PATH",Value: "/etc/gha-listener/config.json", // config.json 就是第四步的 config 结构体},}podSpec := corev1.PodSpec{ServiceAccountName: serviceAccount.Name,Containers: []corev1.Container{{Name:  autoscalingListenerContainerName,Image: autoscalingListener.Spec.Image, // 镜像字段来自 autoscalingListener 资源，来自 autoscalingrunnerset 资源Env:   listenerEnv,Command: []string{scaleSetListenerEntrypoint, // /ghalistener},

监听 listener pod 的业务容器状态，如果 container 异常则报错。
AutoscalingListener控制器的工作至此结束。接下来看看 listener pod 做了什么。

func main() {configPath, ok := os.LookupEnv("LISTENER_CONFIG_PATH") // 读取环境变量config, err := config.Read(ctx, configPath) // 读取 config 文件app, err := app.New(*config) // 新建 app 对象if err := app.Run(ctx); err != nil { // 连接 Github Action 服务器log.Printf("Application returned an error: %v", err)os.Exit(1)}
}

app.Run()方法：

func (app *App) Run(ctx context.Context) error {g, ctx := errgroup.WithContext(ctx)metricsCtx, cancelMetrics := context.WithCancelCause(ctx)g.Go(func() error {app.logger.Info("Starting listener")listnerErr := app.listener.Listen(ctx, app.worker) // 监听上游仓库cancelMetrics(fmt.Errorf("Listener exited: %w", listnerErr))return listnerErr})if app.metrics != nil {g.Go(func() error {app.logger.Info("Starting metrics server")return app.metrics.ListenAndServe(metricsCtx) // 启动http服务，输出 prometheus 格式的指标})}return g.Wait()
}

app.listener.Listen(ctx, app.worker)的主逻辑：不断循环，从 Github Action 服务器接收消息。

    for {select {case <-ctx.Done():return ctx.Err()default:}msg, err := l.getMessage(ctx) // 从 Github Action 服务器获取 messageif err != nil {return fmt.Errorf("failed to get message: %w", err)}// Remove cancellation from the context to avoid cancelling the message handling.if err := l.handleMessage(context.WithoutCancel(ctx), handler, msg); err != nil { // 处理消息return fmt.Errorf("failed to handle message: %w", err)}}