k3s x GitLab Runner Operator，GitLab CI 云原生构建新体验

GitLab CI 是非常常用的一款 CI/CD 工具，只需要在 .gitlab-ci.yml 文件中用 YAML 语法编写 CI/CD 流水线即可。而 GitLab CI 能够运行的关键组件是 GitLab Runner。GitLab Runner 是一个轻量级、高扩展的代理，主要用来执行 GitLab CI/CD 流水线中的 Job，然后将 Job 的执行结果返回 GitLab 实例。

GitLab Runner 的安装方式有很多种，包括安装包、Docker、Helm Chart 等，本文将用 GitLab Runner Operator 的方式来在 k3s 上安装 GitLab Runner，并执行 CI/CD 流水线。关于其他安装方式的详情，可以查看 GitLab Runner 安装文档。

GitLab Runner Operator 主要是在 Kubernetes 平台上来管理 GitLab Runner。在 Kubernetes 平台上安装 GitLab Runner 有两个先决条件：

Kubernetes 的版本必须是 v1.21.1 以上
Cert manager 的版本为 v1.7.1 以上

本文使用 k3s 来搭建一个 Kubernetes 平台。

k3s 的安装

k3s 是经 CNCF 一致性认证的 Kubernetes 发行版，专为物联网及边缘计算而设计。简言之，k3s 是一个轻量级的 Kubernetes 发行版。

k3s 的安装非常简单，对于国内用户来讲，执行如下命令可以加速 k3s 的安装：

$ curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -
[INFO]  Finding release for channel stable
[INFO]  Using v1.28.5+k3s1 as release
[INFO]  Downloading hash rancher-mirror.rancher.cn/k3s/v1.28.5-k3s1/sha256sum-amd64.txt
[INFO]  Downloading binary rancher-mirror.rancher.cn/k3s/v1.28.5-k3s1/k3s
[INFO]  Verifying binary download
[INFO]  Installing k3s to /usr/local/bin/k3s
[INFO]  Skipping installation of SELinux RPM
[INFO]  Creating /usr/local/bin/kubectl symlink to k3s
[INFO]  Creating /usr/local/bin/crictl symlink to k3s
[INFO]  Skipping /usr/local/bin/ctr symlink to k3s, command exists in PATH at /usr/bin/ctr
[INFO]  Creating killall script /usr/local/bin/k3s-killall.sh
[INFO]  Creating uninstall script /usr/local/bin/k3s-uninstall.sh
[INFO]  env: Creating environment file /etc/systemd/system/k3s.service.env
[INFO]  systemd: Creating service file /etc/systemd/system/k3s.service
sh: 1014: restorecon: not found
sh: 1015: restorecon: not found
[INFO]  systemd: Enabling k3s unit
Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → /etc/systemd/system/k3s.service.
[INFO]  systemd: Starting k3s

接着可以查看 k3s 是否安装成功：

#查看 k3s 版本
$ k3s --version
k3s version v1.28.5+k3s1 (5b2d1271)
go version go1.20.12

# 查看 k3s 集群
$ kubectl get nodes
NAME             STATUS   ROLES                  AGE   VERSION
vm-0-12-ubuntu   Ready    control-plane,master   38s   v1.28.5+k3s1

上述命令已经快速构建了一个单节点的 k3s 集群。接下来就可以在这个 k3s 集群上使用 GitLab Runner Operator 来安装 GitLab Runner 了。安装详情可以在 OperatorHub.io 上查看详细步骤。

GitLab Runner Operator 的安装

在安装之前首先需要安装 cert-manager。

安装 cert-manager

使用如下命令即可完成安装。

$ kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.7.1/cert-manager.yaml

customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created

......太长了，删除一部分输出日志......

mutatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created
validatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created

上述过程中安装了 N 多 Kubernetes 资源。

安装 Operator Lifecycle Manager

接下来要安装 Operator Lifecycle Manager（OLM），这是一个能够对 Kubernetes 集群上 Operator 进行管理的工具。使用如下命令安装：

$ curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.26.0/install.sh | bash -s v0.26.0

customresourcedefinition.apiextensions.k8s.io/catalogsources.operators.coreos.com created
customresourcedefinition.apiextensions.k8s.io/clusterserviceversions.operators.coreos.com created

......太长了，删除一部分输出日志......

Waiting for deployment "olm-operator" rollout to finish: 0 of 1 updated replicas are available...
deployment "olm-operator" successfully rolled out
deployment "catalog-operator" successfully rolled out
Package server phase: Installing
Package server phase: Succeeded
deployment "packageserver" successfully rolled out

可以将上面的版本换成自己想要的版本，比如 `v0.22.0`。

安装 Operator

接下来执行如下命令来完成 Operator 的安装：

$ kubectl create -f https://operatorhub.io/install/stable/gitlab-runner-operator.yaml
subscription.operators.coreos.com/my-gitlab-runner-operator created

查看安装的 Operator

使用如下命令查看 Operator 是否安装成功

# 查看 csv 资源
$ kubectl get csv -n operators
NAME                             DISPLAY         VERSION   REPLACES                         PHASE
gitlab-runner-operator.v1.15.1   GitLab Runner   1.15.1    gitlab-runner-operator.v1.15.0   Succeeded

# 查看 pod 状态
$ kubectl -n operators get pods
NAME                                                READY   STATUS    RESTARTS   AGE
gitlab-runner-controller-manager-5b7f856fc5-fhk2f   2/2     Running   0          20h

接下来就可以使用 GitLab Runner Operator 来创建 GitLab Runner 了。

使用 Operator 创建 GitLab Runner

本文使用 GitLab 中国发行版——极狐GitLab 来进行测试。极狐GitLab 是 GitLab 除 CE/EE 之外发行的另外一个版本，专门面向中国用户。可以私有化部署，也可以使用 SaaS（jihulab.com)。

创建 GitLab Runner 之前，需要明确创建什么样的 Runner，是共享的还是专有的，是群组级别的还是项目级别的。关于 GitLab Runner 的作用范围可以查看 GitLab Runner 官方文档。

获取 Runner 注册 token

以注册项目 Runner 为例来说，在项目 --> 设置 --> CI/CD --> Runner 中，选择新建项目 Runner：

点击新建项目 Runner 选项，在出现的界面中填写好对于的信息，包括 Runner 标签、描述等：

点击创建 Runner就会出现注册 Runner 的命令，在命令中就有 Runner 注册的 token，默认以 plrt 开头。

一定要保存好此 token，后面会用到。

创建包含注册 token 的 secret

将上一步中获取的 Runner 注册 token 存入下方的 yaml 文件：

cat > gitlab-runner-secret.yml << EOF
  apiVersion: v1
  kind: Secret
  metadata:
    name: jh-gitlab-runner-secret
  type: Opaque
  stringData:
    runner-registration-token: REPLACE_ME # 上一步中创建的 Runner 注册 token
  EOF

使用如下命令创建 secret

$ kubectl  apply -f gitlab-runner-secret.yml
secret/jh-gitlab-runner-secret created

创建 Runner CRD

Runner CRD yaml 文件内容如下：

cat > gitlab-runner.yml << EOF
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
    name: gitlab-runner
spec:
    gitlabUrl: https://jihulab.com
    buildImage: alpine
    token: jh-gitlab-runner-secret
EOF

参数说明：

gitlabUrl：GitLab/极狐GitLab 实例的地址，本文使用极狐GitLab SaaS，地址为 https://jihulab.com。
token：上一步创建的 secret 名称。

使用如下命令完成 Runner CRD 的创建：

$ kubectl apply -f gitlab-runner.yml
runner.apps.gitlab.com/jh-gitlab-runner created

接着确认一下 Runner CRD 是否创建成功：

# 查看 Runner CRD 资源
kubectl get runner
NAME               AGE
jh-gitlab-runner   20h

# 查看 Runner pod
$ kubectl  get pods
NAME                                       READY   STATUS    RESTARTS   AGE
jh-gitlab-runner-runner-6f7c4bf7dc-r9lzh   1/1     Running   0          16h

接着就可以在项目的 Runner 页面查看 Runner 是否注册成功：

可以看到有一个该项目专用的 Runner 已经注册成功。接下来测试此 Runner。

Runner 测试

在项目的 .gitlab-ci.yml 文件中写入一个构建容器镜像并推送到极狐GitLab 内置的镜像仓库的 Job 配置：

build:
  image: docker:latest
  stage: build
  tags:
    - jh
  services:
    - docker:20.10.7-dind
  script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:v1.0.0 .
    - docker push $CI_REGISTRY_IMAGE:v1.0.0

触发流水线，然后在项目 --> 构建 --> 流水线中查看结果：

可以看到流水线构建成功。再查看构建日志，确认构建此次流水线所需的 Runner 是否为上面创建的 Runner：

从红色方框的信息看，此次 CI/CD 流水线构建使用的就是上述用 GitLab Runner Operator 创建出来的 Runner。

过程中遇到的问题及修复方案

operators 中 gcr.io 镜像不可用问题

在安装 Operator 的过程中，gitlab-runner-controller-manager 依赖镜像 gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0。由于此镜像在国内无法正常拉取，会导致以下错误：

$ kubectl -n operators get pods -w
NAME                                                READY   STATUS              RESTARTS   AGE
gitlab-runner-controller-manager-6d88d9d9d4-tdf5m   0/2     ContainerCreating   0          15s
gitlab-runner-controller-manager-6d88d9d9d4-tdf5m   1/2     ErrImagePull        0          31s
gitlab-runner-controller-manager-6d88d9d9d4-tdf5m   1/2     ImagePullBackOff    0          32s

镜像拉取失败的详细日志：

Warning  Failed     45s                kubelet            Failed to pull image "gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0": rpc error: code = DeadlineExceeded desc = failed to pull and unpack image "gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0": failed to resolve reference "gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0": failed to do request: Head "https://gcr.io/v2/kubebuilder/kube-rbac-proxy/manifests/v0.8.0": dial tcp 173.194.174.82:443: i/o timeout
Warning  Failed     45s                kubelet            Error: ErrImagePull
Normal   Pulled     45s                kubelet            Container image "registry.gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/gitlab-runner-operator:v1.15.1" already present on machine
Normal   Created    45s                kubelet            Created container manager
Normal   Started    45s                kubelet            Started container manager
Normal   BackOff    44s (x2 over 45s)  kubelet            Back-off pulling image "gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0"
Warning  Failed     44s (x2 over 45s)  kubelet            Error: ImagePullBackOff
Normal   Pulling    29s (x2 over 75s)  kubelet            Pulling image "gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0"

提示无法拉取 gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0。解决办法为将上述镜像替换为 kubesphere/kube-rbac-proxy:v0.8.0。替换完成后，pod 运行正常：

$ kubectl  -n operators get pods
NAME                                                READY   STATUS    RESTARTS   AGE
gitlab-runner-controller-manager-5b7f856fc5-fhk2f   2/2     Running   0          20h

看这个镜像应该是 kubesphere 制作的，在此感谢 kubesphere 团队所做的贡献。

pod 中执行 docker 命令

上面测试的 Job 是现在在 kubernetes pod 中执行 docker 命令来构建容器镜像：

build:
  image: docker:latest
  stage: build
  tags:
    - jh
  services:
    - docker:20.10.7-dind
  script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:v1.0.0 .
    - docker push $CI_REGISTRY_IMAGE:v1.0.0

这个过程中其实需要将宿主机的 docker.sock 文件挂在到 Runner pod 里面。这个时候就需要对于 Runner 的 config.toml 文件进行修改了。

使用 Operator 安装的 Runner，其配置文件以 configmap 的形式存在，可以在 Runner 所在的 namespace 下面查看：

$ kubectl  get cm
NAME                             DATA   AGE
jh-gitlab-runner-runner-config   6      20h

查看上述 configmap 的内容，默认情况下对于 config.toml 文件的描述仅有一下内容：

  config.toml: |-
    concurrent = 10
    check_interval = 30
    log_level = "info"
    listen_address = '[::]:9252'

在 Runner pod 中查看 `config.toml` 文件的配置：

[runners.kubernetes]
    host = ""
    bearer_token_overwrite_allowed = false
    image = "alpine"
    namespace = "default"
    namespace_overwrite_allowed = ""
    node_selector_overwrite_allowed = ""
    helper_image = "registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp:v16.0.1"
    poll_timeout = 180
    pod_labels_overwrite_allowed = ""
    service_account_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    [runners.kubernetes.pod_security_context]
    [runners.kubernetes.init_permissions_container_security_context]
    [runners.kubernetes.build_container_security_context]
    [runners.kubernetes.helper_container_security_context]
    [runners.kubernetes.service_container_security_context]
    [runners.kubernetes.volumes]
    [runners.kubernetes.dns_config]

可以看到在 `[runners.kubernetes.volumes]` 配置中并没有挂载 docker.sock 文件。这时候就需要通过自定义 config.toml 文件的形式来完成文件的挂载了。整个自定义的过程可以查看GitLab config.toml 文件自定义官方文档。

首先，创建一个 `custome-config.toml` 文件，写入挂载文件的内容：

[[runners]]
  [runners.kubernetes]
    [runners.kubernetes.volumes]
      [[runners.kubernetes.volumes.host_path]]
          name = "docker"
          mount_path = "/var/run/docker.sock"
          host_path = "/var/run/docker.sock"

然后，以文件的形式创建 configmap：

$ kubectl create configmap custom-config-toml --from-file config.toml=custom-config.toml
configmap/custom-config-toml created

然后将上述新增的 configmap 添加到 Runner 的 CRD 中：

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: jh-gitlab-runner
spec:
  gitlabUrl: https://jihulab.com
  buildImage: alpine
  token: jh-gitlab-runner-secret
  config: custom-config-toml

以 config 为关键字将自定义的 configmap 内容引入。然后创建 Runner 即可。最后可以在 Runner pod 中看到如下内容：

    [runners.kubernetes.volumes]
      [[runners.kubernetes.volumes.host_path]]
        name = "docker"
        mount_path = "/var/run/docker.sock"
        host_path = "/var/run/docker.sock"

说明宿主机的 docker.sock 文件被挂载到了 Runner pod 中，这样就可以在 pod 中使用 docker 命令了。当然，这种方式存在一定的安全问题，建议使用 `kaniko` 进行镜像构建。详情可以查看过往的技术文章Kaniko- 以一种更安全可靠的方式在Kubernetes平台上构建容器镜像。

GitHub 无法链接

在安装 Operator 的时候，因为会从 Operator GitHub 仓库拉取资源直接安装，这时候可能会遇到 GitHub 无法链接的问题（看你服务器在哪儿了）。这时候就可以在Operator Lifycycle Manager GitHub Repo上看一下内容，把无法拉取的文件内容想办法搞到本地，然后在本地执行即可。比如 install.sh、crds.yml、olm.yml文件。当然，前提是要看懂这些文件里面的内容，适当的时候要做一些调整。当然，调整不会影响安装使用。