- 向极狐GitLab Runner 执行器传递属性
- 运算符属性
- 缓存属性
- 配置代理环境
- 通过配置模板自定义
config.toml
- 配置自定义 TLS cert
- 配置 Runner Pod 的 CPU 和内存
- 基于集群资源配置每个 Runner 的作业并发
- 故障排除
在 OpenShift 上配置极狐GitLab Runner
本文档描述如何在 OpenShift 上配置极狐GitLab Runner。
向极狐GitLab Runner 执行器传递属性
当创建 Runner
时,您可以通过在它的 spec
中设置属性来配置。例如,您可以指定它将要注册到的极狐GitLab URL,或者包含注册令牌的密钥的名称:
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
name: dev
spec:
gitlabUrl: https://gitlab.example.com
token: gitlab-runner-secret # Name of the secret containing the Runner token
所有可用属性请参见运算符属性。
运算符属性
以下是可以传递给运算符的支持的属性列表。
一些属性只有在新版本运算符中可用。
设置 | 运算符 | 描述 |
---|---|---|
gitlabUrl
| 所有 | 极狐GitLab 实例的完全限定域名,如 https://gitlab.example.com 。
|
token
| 所有 | 包含用于注册 Runner 的 runner-registration-token key 的 Secret 的名称。
|
tags
| 所有 | 应用于 Runner 的以逗号分隔的标签的列表。 |
concurrent
| 所有 | 限定可以并发运行的作业的数量。最大数量是所有定义的 Runner。0 不表示无限。默认为 10 。
|
interval
| 所有 | 定义检查新作业的秒数。默认为 30 。
|
locked
| 1.8 | 定义 Runner 是否应该被锁定到特定项目。默认为 false 。
|
runUntagged
| 1.8 | 定义是否应该运行无标签的作业。如果没有指定标签,默认为 true ,否则为 false 。
|
protected
| 1.8 | 定义 Runner 是否应该只在受保护的分支上运行作业。默认为 false 。
|
cloneURL
| 所有 | 覆盖极狐GitLab 实例的 URL。只有在 Runner 无法连接到极狐GitLab URL 的时候使用。 |
env
| 所有 | 包含作为环境变量注入到 Runner pod 的键值对的 ConfigMap 的名称。
|
runnerImage
| 1.7 | 覆盖默认的极狐GitLab Runner 镜像。默认的是运算符绑定的 Runner 镜像。 |
helperImage
| 所有 | 覆盖默认的极狐GitLab Runner helper 镜像。 |
buildImage
| 所有 | 当没有指定 Docker 镜像时,用于作业的默认的 Docker 镜像。 |
cacheType
| 所有 | 用于 Runner 产物的缓存类型。gcs 、 s3 或 azure 中的一个。
|
cachePath
| 所有 | 定义文件系统上的缓存路径。 |
cacheShared
| 所有 | 在 Runner 之间启用缓存共享。 |
s3
| 所有 | 用于设置 S3 缓存的选项。详情请参考缓存属性。 |
gcs
| 所有 | 用于设置 GCS 缓存的选项。详情请参考缓存属性。 |
azure
| 所有 | 用于设置 Azure 缓存的选项。详情请参考缓存属性。 |
ca
| 所有 | 包含自定义 CA 证书的 TLS 密钥的名称。 |
serviceAccount
| 所有 | 用于覆盖用于运行 Runner pod 的服务账号。 |
config
| 所有 | 用于通过配置模板提供自定义的配置 map。 |
缓存属性
S3 缓存
设置 | 运算符 | 描述 |
---|---|---|
server
| 所有 | S3 服务器地址。 |
credentials
| 所有 | 包含用于访问对象存储的 accesskey 和 secretkey 属性的 Secret 的名称。
|
bucket
| 所有 | 存储缓存的桶的名称。 |
location
| 所有 | 存储缓存的 S3 区域的名称。 |
insecure
| 所有 | 使用不安全的连接或 HTTP 。
|
GCS 缓存
设置 | 运算符 | 描述 |
---|---|---|
credentials
| 所有 | 包含用于访问对象存储的 access-id 和 private-key 的 Secret 的名称。
|
bucket
| 所有 | 存储缓存的桶的名称。 |
credentialsFile
| 所有 | 取 GCS 凭证文件 keys.json 。
|
Azure 缓存
设置 | 运算符 | 描述 |
---|---|---|
credentials
| 所有 | 包含用于访问对象存储的 accountName 和 privateKey 属性的 Secret 的名称。
|
container
| 所有 | 存储缓存的 Azure 容器的名称。 |
storageDomain
| 所有 | Azure blob 存储的域名。 |
配置代理环境
创建代理环境:
-
编辑
custom-env.yaml
文件。例如:apiVersion: v1 data: HTTP_PROXY: example.com kind: ConfigMap metadata: name: custom-env
-
更新 OpenShift 以应用更改。
oc apply -f custom-env.yaml
-
更新您的
gitlab-runner.yml
文件。apiVersion: apps.gitlab.com/v1beta2 kind: Runner metadata: name: dev spec: gitlabUrl: https://gitlab.example.com token: gitlab-runner-secret # Name of the secret containing the Runner token env: custom-env
如果代理无法访问 Kubernetes API,您会在您的 CI/CD 作业中看到如下报错信息:
ERROR: Job failed (system failure): prepare environment: setting up credentials: Post https://172.21.0.1:443/api/v1/namespaces/<KUBERNETES_NAMESPACE>/secrets: net/http: TLS handshake timeout. Check https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading for more information
为解决这个错误,需要在 custom-env.yaml
文件的 NO_PROXY
配置中添加 Kubernetes API 的 IP 地址:
apiVersion: v1
data:
NO_PROXY: 172.21.0.1
HTTP_PROXY: example.com
kind: ConfigMap
metadata:
name: custom-env
您可以通过运行如下命令验证 Kubernetes API 的 IP 地址:
oc get services --namespace default --field-selector='metadata.name=kubernetes' | grep -v NAME | awk '{print $3}'
通过配置模板自定义 config.toml
您可以使用配置模板自定义 runner config.toml
文件。
-
创建自定义配置模板文件。例如,我们构建 Runner 挂载
EmptyDir
卷。创建custom-config.toml
文件:[[runners]] [runners.kubernetes] [runners.kubernetes.volumes] [[runners.kubernetes.volumes.empty_dir]] name = "empty-dir" mount_path = "/path/to/empty_dir" medium = "Memory"
-
从我们的
custom-config.toml
文件创建名为custom-config-toml
的ConfigMap
:oc create configmap custom-config-toml --from-file config.toml=custom-config-toml
-
设置
Runner
的config
属性:apiVersion: apps.gitlab.com/v1beta2 kind: Runner metadata: name: dev spec: gitlabUrl: https://gitlab.example.com token: gitlab-runner-secret config: custom-config-toml
配置自定义 TLS cert
-
为设置自定义 TLS cert,用 key
tls.crt
创建密钥。 在这个例子中,文件的名称是custom-tls-ca-secret.yaml
:apiVersion: v1 kind: Secret metadata: name: custom-tls-ca type: Opaque stringData: tls.crt: | -----BEGIN CERTIFICATE----- MIIEczCCA1ugAwIBAgIBADANBgkqhkiG9w0BAQQFAD..AkGA1UEBhMCR0Ix ..... 7vQMfXdGsRrXNGRGnX+vWDZ3/zWI0joDtCkNnqEpVn..HoX -----END CERTIFICATE-----
-
创建密钥:
oc apply -f custom-tls-ca-secret.yaml
-
在
runner.yaml
中,将ca
key 的名称设置成我们的密钥的名称:apiVersion: apps.gitlab.com/v1beta2 kind: Runner metadata: name: dev spec: gitlabUrl: https://gitlab.example.com token: gitlab-runner-secret ca: custom-tls-ca
配置 Runner Pod 的 CPU 和内存
基于集群资源配置每个 Runner 的作业并发
设置 Runner
资源的 concurrent
属性:
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
name: dev
spec:
gitlabUrl: https://gitlab.example.com
token: gitlab-runner-secret
concurrent: 2
作业并发由特定项目的要求决定。
- 尝试判断执行 CI 作业所需的计算和内存资源。
- 计算作业能够执行集群中给定资源的次数。
如果您将并发值设置得过大,Kubernetes 执行器会尽快处理作业。 然而,Kubernetes 集群的调度器容量决定了调度作业的时间。
故障排除
根 vs 非根
极狐GitLab Runner 运算符和极狐GitLab Runner pod 以非根用户运行。因此,作业中使用的构建镜像需要以非根用户运行,用以成功完成。
这是为了确保作业能够以最小的权限运行成功。然而为了达到这个目的,
CI 作业的构建镜像也需要构建为以非根的形式运行,且不应该写入限制文件系统。记住大多数 OpenShift 集群上的容器文件系统是只读的,除了挂载卷、 /var/tmp
、 /tmp
和其他以 tmpfs
挂载到根文件系统的卷。
覆盖 HOME
环境变量
如果创建自定义构建镜像或覆盖 env 变量,请确保环境变量没有被设置为只读的 /
。
特别是当您的作业需要向主目录写入文件时。
您需要在 /home
下面创建一个目录,如 /home/ci
,并在您的 Dockerfile
中设置 ENV HOME=/home/ci
。
注意 SCC
默认情况下,当安装了新的 OpenShift 项目,极狐GitLab Runner 运算符会以非根形式运行。
但也有例外,当项目中的所有服务账户被授以 anyuid
访问权限,如 default
项目。
在那种情况下,镜像的用户会是 root
。通过在任意容器 shell(例如作业)中运行 whoami
可以轻松进行检查。
详情请参见 Red Hat 容器平台文档 > 管理安全上下文约束。
以 anyuid SCC 运行
尽管不鼓励,但是在 CI 作业绝对必要以根用户运行或写入到根文件系统的情况下,
您需要在极狐GitLab Runner 容器所使用的极狐GitLab Runner 服务账户 gitlab-runner-sa
上设置 anyuid
SCC。
oc adm policy add-scc-to-user anyuid -z gitlab-runner-sa -n <runner_namespace>
# Check that the anyiud SCC is set:
oc get scc anyuid -o yaml
使用符合 FIPS 的极狐GitLab Runner
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
name: dev
spec:
gitlabUrl: https://gitlab.example.com
token: gitlab-runner-secret
helperImage: gitlab/gitlab-runner-helper:ubi-fips
concurrent: 2
使用自签名证书注册极狐GitLab Runner
当您使用自签名证书安装私有化部署极狐GitLab,您必须创建包含用于签署私有证书的 CA 证书的密钥。
密钥的名称由 Runner spec 部分的 CA 提供:
KIND: Runner
VERSION: apps.gitlab.com/v1beta2
FIELD: ca <string>
DESCRIPTION:
Name of tls secret containing the custom certificate authority (CA)
certificates
使用下列命令创建密钥:
oc create secret generic mySecret --from-file=tls.crt=myCert.pem -o yaml
通过指向 IP 地址的外部 URL 注册极狐GitLab Runner
如果 Runner 用主机名无法匹配自签名证书,您可能会收到错误信息。当极狐GitLab 私有化部署实例被配置为从 IP 地址而不是主机名(###.##.##.## 是极狐GitLab 服务器的 IP 地址)访问时,会发生这种情况:
[31;1mERROR: Registering runner... failed [0;m [31;1mrunner[0;m=A5abcdEF [31;1mstatus[0;m=couldn't execute POST against https://###.##.##.##/api/v4/runners:
Post https://###.##.##.##/api/v4/runners: x509: cannot validate certificate for ###.##.##.## because it doesn't contain any IP SANs
[31;1mPANIC: Failed to register the runner. You may be having network problems.[0;m
解决这个问题:
-
在极狐GitLab 私有化部署服务器上,更改
openssl
,将 IP 地址添加到subjectAltName
参数中:# vim /etc/pki/tls/openssl.cnf [ v3_ca ] subjectAltName=IP:169.57.64.36 <---- Add this line. 169.57.64.36 is your GitLab server IP.
-
使用如下命令重新生成自签名 CA:
# cd /etc/gitlab/ssl # openssl req -x509 -nodes -days 3650 -newkey rsa:4096 -keyout /etc/gitlab/ssl/169.57.64.36.key -out /etc/gitlab/ssl/169.57.64.36.crt # openssl dhparam -out /etc/gitlab/ssl/dhparam.pem 4096 # gitlab-ctl restart
-
使用新的证书生成新的密钥。