- GitLab Runner Operator에 속성 전달
- Operator 속성
- 캐시 속성
- 프록시 환경 구성
- 구성 템플릿을 사용한
config.toml
사용자 정의 - 사용자 정의 TLS 인증서 구성
- 러너 파드의 CPU 및 메모리 크기 구성
- 클러스터 리소스에 기반한 러너 당 작업 동시성 구성
- 문제 해결
OpenShift에서 GitLab Runner 구성
이 문서에서는 OpenShift에서 GitLab Runner를 구성하는 방법에 대해 설명합니다.
GitLab Runner Operator에 속성 전달
Runner
를 생성할 때, 해당 spec
에 속성을 설정하여 구성할 수 있습니다. 예를 들어, GitLab에 등록될 URL이나 등록 토큰이 포함된 시크릿의 이름을 지정할 수 있습니다.
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
name: dev
spec:
gitlabUrl: https://gitlab.example.com
token: gitlab-runner-secret # Runner 토큰이 포함된 시크릿의 이름
Operator 속성에서 모든 사용 가능한 속성에 대해 자세히 읽어보세요.
Operator 속성
Operator에 전달할 수 있는 지원되는 속성 디렉터리입니다.
일부 속성은 Operator의 최신 버전에서만 사용할 수 있습니다.
설정 | Operator | 설명 |
---|---|---|
gitlabUrl
| all | GitLab 인스턴스의 완전히 정규화된 도메인 이름, 예: https://gitlab.example.com .
|
token
| all | Runner를 등록하는 데 사용되는 runner-registration-token 키가 포함된 Secret 의 이름.
|
tags
| all | Runner에 적용할 쉼표로 구분된 태그 디렉터리. |
concurrent
| all | 동시에 실행할 작업 수를 제한합니다. 최대 수는 정의된 모든 Runner의 개수입니다. 0은 무제한을 의미하지 않습니다. 기본값은 10 입니다.
|
interval
| all | 새로운 작업을 확인하는 데 사용되는 초 단위 간격을 정의합니다. 기본값은 30 입니다.
|
locked
| 1.8 | Runner를 프로젝트에 잠글지 여부를 정의합니다. 기본값은 false 입니다.
|
runUntagged
| 1.8 | 태그가 지정되지 않은 작업을 실행할지 여부를 정의합니다. 태그가 지정되지 않았으면 기본값은 true 입니다. 그렇지 않으면 false 입니다.
|
protected
| 1.8 | Runner가 보호된 브랜치에서만 작업을 실행할지 여부를 정의합니다. 기본값은 false 입니다.
|
cloneURL
| all | GitLab 인스턴스의 URL을 덮어쓰기합니다. Runner가 GitLab URL에 연결할 수 없는 경우에만 사용됩니다. |
env
| all | Runner pod에 주입될 환경 변수로 된 키-값 쌍이 포함된 ConfigMap 의 이름.
|
runnerImage
| 1.7 | 기본 GitLab Runner 이미지를 덮어씁니다. 기본값은 Operator가 번들로 제공한 Runner 이미지입니다. |
helperImage
| all | 기본 GitLab Runner 보조 이미지를 덮어씁니다. |
buildImage
| all | 명시된 경우 사용할 기본 Docker 이미지. |
cacheType
| all | Runner 아티팩트에 사용되는 캐시 유형. gcs , s3 , azure 중 하나.
|
cachePath
| all | 파일 시스템의 캐시 경로를 정의합니다. |
cacheShared
| all | 러너 간 캐시 공유를 활성화합니다. |
s3
| all | S3 캐시 설정에 사용되는 옵션. Cache properties를 참조하세요. |
gcs
| all | GCS 캐시 설정에 사용되는 옵션. Cache properties를 참조하세요. |
azure
| all | Azure 캐시 설정에 사용되는 옵션. Cache properties를 참조하세요. |
ca
| all | 사용자 지정 CA(certificate authority) 인증서를 포함한 TLS 시크릿의 이름. |
serviceaccount
| all | Runner pod을 실행하는 데 사용되는 서비스 어카운트를 덮어씁니다. |
config
| all | 구성 템플릿과 함께 사용할 사용자 정의 구성 맵의 이름. |
캐시 속성
S3 캐시
설정 | Operator | 설명 |
---|---|---|
server
| all | S3 서버 주소. |
credentials
| all | 객체 리포지터리에 액세스하는 데 사용되는 accesskey 와 secretkey 속성이 포함된 Secret 의 이름.
|
bucket
| all | 캐시가 저장될 버킷의 이름. |
location
| all | 캐시가 저장될 S3 지역의 이름. |
insecure
| all | 보안되지 않은 연결이나 HTTP 를 사용합니다.
|
GCS 캐시
설정 | Operator | 설명 |
---|---|---|
credentials
| all | 객체 리포지터리에 액세스하는 데 사용되는 access-id 와 private-key 속성이 포함된 Secret 의 이름.
|
bucket
| all | 캐시가 저장될 버킷의 이름. |
credentialsFile
| all | GCS credentials 파일인 keys.json 을 사용합니다.
|
Azure 캐시
설정 | Operator | 설명 |
---|---|---|
credentials
| all | 객체 리포지터리에 액세스하는 데 사용되는 accountName 과 privateKey 속성이 포함된 Secret 의 이름.
|
container
| all | 캐시가 저장될 Azure 컨테이너의 이름. |
storageDomain
| all | Azure Blob Storage의 도메인 이름. |
프록시 환경 구성
프록시 환경을 생성하려면 다음을 수행하세요:
-
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 # Runner 토큰이 포함된 시크릿의 이름 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. 자세한 내용은 https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading 를 확인하세요.
이 오류를 해결하려면, 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
사용자 정의
config.toml
을 사용자 정의하기 위한 구성 템플릿 사용은 [runners.kubernetes.volumes]
설정을 지정하는 데로 제한됩니다.
다른 설정으로 확장하는 지원은 issue 49에서 제안되었습니다.구성 템플릿을 사용하여 Runner의 config.toml
파일을 사용자 정의할 수 있습니다.
-
사용자 지정 구성 템플릿 파일을 만듭니다. 예를 들어,
EmptyDir
볼륨을 마운트하도록 Runner에 지시하는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
이름의config.toml
를 생성합니다: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 인증서 구성
-
사용자 정의 TLS 인증서를 설정하려면
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
키를 시크릿의 이름과 동일하게 설정합니다:apiVersion: apps.gitlab.com/v1beta2 kind: Runner metadata: name: dev spec: gitlabUrl: https://gitlab.example.com token: gitlab-runner-secret ca: custom-tls-ca
러너 파드의 CPU 및 메모리 크기 구성
커스텀 config.toml
파일에서 CPU 한도와 메모리 한도를 설정하려면 이 항목의 지침을 따르세요.
클러스터 리소스에 기반한 러너 당 작업 동시성 구성
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 러너 오퍼레이터와 GitLab 러너 파드는 비루트 사용자로 실행됩니다. 따라서 작업에서 사용되는 빌드 이미지는 성공적으로 완료되려면 비루트 사용자로 실행되어야 합니다.
이는 최소한의 권한으로 작업을 성공적으로 실행할 수 있도록 보장하기 위함입니다. 그러나 이를 위해
CI 작업에 사용되는 빌드 이미지도 비루트로 실행되도록 빌드되어야 하며, 제한된 파일 시스템에 쓰여서는 안 됩니다.
OpenShift 클러스터의 대부분의 컨테이너 파일 시스템은 읽기 전용일 것이며 마운트된 볼륨을 제외한 /var/tmp
, /tmp
및 기타 /home
아래에 마운트된 볼륨을 포함합니다.
HOME
환경 변수 재정의
커스텀 빌드 이미지를 생성하거나 환경 변수를 재정의하는 경우, 홈 환경 변수가 읽기 전용인 /
로 설정되어 있지 않도록 유의하세요.
특히 작업에서 홈 디렉터리에 파일을 작성해야 하는 경우에는 더욱 주의해야 합니다.
예를 들어 /home
하위에 /home/ci
디렉터리를 생성하고 Dockerfile
에서 ENV HOME=/home/ci
를 설정할 수 있습니다.
러너 파드에서는 기본적으로 HOME
이 /home/gitlab-runner
로 설정되어 있어야 합니다.
이 변수가 변경되는 경우, 새 위치에는 적절한 권한이 있어야 합니다.
이 가이드라인은 Red Hat Container Platform 문서 > 이미지 생성 > 임의의 사용자 ID 지원에도 문서화되어 있습니다.
SCC 주의
새 OpenShift 프로젝트에 설치될 때 기본적으로 GitLab 러너 오퍼레이터는 비루트로 실행됩니다.
그러나 default
프로젝트와 같이 모든 서비스 계정에게 anyuid
액세스 권한이 부여된 경우에는 사용자가 root
가 될 수 있습니다. 이는 쉘 내에서 whoami
를 실행하여 확인할 수 있습니다. 예를 들어 작업 내에서 확인하세요.
Red Hat Container Platform 문서 > 보안 컨텍스트 제약 조건 관리에서 SCC에 대해 자세히 읽어보세요.
anyuid SCC로 실행하기
비록 권장되지는 않지만 CI 작업이 루트 사용자로 실행되거나 루트 파일 시스템에 쓸 필요가 있는 경우, GitLab 러너 서비스 계정 gitlab-runner-sa
에 anyuid
SCC를 설정해야 합니다. 이 계정은 GitLab 러너 컨테이너에 사용됩니다.
OpenShift 4.3.8 및 이전 버전에서:
oc adm policy add-scc-to-user anyuid -z gitlab-runner-sa -n <runner_namespace>
# anyuid SCC가 설정되었는지 확인합니다:
oc get scc anyuid -o yaml
OpenShift 4.3.8부터:
oc create -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: scc-anyuid
namespace: <runner_namespace>
rules:
- apiGroups:
- security.openshift.io
resourceNames:
- anyuid
resources:
- securitycontextconstraints
verbs:
- use
EOF
oc create -f - <<EOF
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: sa-to-scc-anyuid
namespace: <runner_namespace>
subjects:
- kind: ServiceAccount
name: gitlab-runner-sa
roleRef:
kind: Role
name: scc-anyuid
apiGroup: rbac.authorization.k8s.io
EOF
SETFCAP 구성
Red Hat OpenShift Container Platform (RHOCP) 4.11 이상을 사용하는 경우 다음과 같은 오류 메시지가 표시될 수 있습니다:
error reading allowed ID mappings:error reading subuid mappings for user
일부 작업(예: buildah)은 올바르게 실행되려면 SETFCAP
기능이 부여되어야 합니다. 이 문제를 해결하려면 다음을 수행합니다:
-
GitLab 러너가 사용하는 SCC에
SETFCAP
기능을 추가합니다. (gitlab-scc
를 사용 중인 SCC로 대체하세요)oc patch scc gitlab-scc --type merge -p '{"allowedCapabilities":["SETFCAP"]}'
-
config.toml
을 업데이트하고kubernetes
섹션 하위에SETFCAP
기능을 추가합니다:[[runners]] [runners.kubernetes] [runners.kubernetes.pod_security_context] [runners.kubernetes.build_container_security_context] [runners.kubernetes.build_container_security_context.capabilities] add = ["SETFCAP"]
-
이
config.toml
을 GitLab 러너가 배포된 네임스페이스에 사용하여 configmap을 생성합니다:oc create configmap custom-config-toml --from-file config.toml=config.toml
-
수정하려는 러너에
config:
매개변수가 최근에 생성된 configmap을 가리키도록 추가합니다 (my-runner를 올바른 러너 파드 이름으로 바꿉니다).oc patch runner my-runner --type merge -p '{"spec": {"config": "custom-config-toml"}}'
자세한 내용은 Red Hat 문서를 참조하세요.
FIPS 호환 GitLab Runner 사용하기
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 Self-Managed형 설치에서 자체 서명 인증서를 사용하는 경우, 개인 인증서를 서명하는 데 사용된 CA 인증서가 포함된 시크릿을 만들어야 합니다.
그런 다음 시크릿의 이름이 Runner 사양 섹션에서 CA로 제공됩니다:
KIND: Runner
VERSION: apps.gitlab.com/v1beta2
FIELD: ca <string>
DESCRIPTION:
사용자 정의 인증 기관 (CA) 인증서를 포함하는 tls 시크릿의 이름
다음 명령을 사용하여 시크릿을 생성할 수 있습니다:
oc create secret generic mySecret --from-file=tls.crt=myCert.pem -o yaml
IP 주소를 지침하는 외부 URL로 GitLab Runner 등록하기
러너(runner)가 자체 서명 인증서를 호스트 이름과 일치시킬 수 없을 때 오류 메시지가 표시될 수 있습니다. 이는 GitLab Self-Managed형 인스턴스가 호스트 이름 대신 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 <---- 이 줄을 추가합니다. 169.57.64.36은 GitLab 서버 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
-
이 새로운 인증서를 사용하여 새로운 시크릿을 생성하세요.