• GitLab Runner Operator에 속성 전달하기
• Operator 속성
• 캐시 속성
  • S3 캐시
  • GCS 캐시
  • Azure 캐시
• 프록시 환경 구성
• config.toml을 구성 템플릿으로 사용자 정의하기
• 사용자 정의 TLS 인증서 구성
• 러너 파드의 CPU 및 메모리 크기 구성
• 클러스터 자원에 따라 러너당 작업 동시성 구성
• 문제 해결
  • 루트 사용자와 비루트 사용자
    • HOME 환경 변수 오버라이드
    • SCC 주의
    • anyuid SCC로 실행
    • SETFCAP 구성
  • FIPS 호환 GitLab Runner 사용
    • 자체 서명된 인증서를 사용하여 GitLab Runner 등록
    • IP 주소를 가리키는 외부 URL로 GitLab Runner 등록

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에서만 사용할 수 있습니다.

캐시 속성

S3 캐시

GCS 캐시

Azure 캐시

프록시 환경 구성

프록시 환경을 만들려면:

1. custom-env.yaml 파일을 편집합니다. 예를 들어:

   apiVersion: v1
   data:
     HTTP_PROXY: example.com
   kind: ConfigMap
   metadata:
     name: custom-env
   

2. 변경 사항을 적용하기 위해 OpenShift를 업데이트합니다.

   oc apply -f custom-env.yaml
   

3. 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. 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을 구성 템플릿으로 사용자 정의하기

러너의 config.toml 파일을 구성 템플릿을 사용하여 사용자 정의할 수 있습니다.

1. 사용자 정의 구성 템플릿 파일을 만듭니다. 예를 들어, 러너에게 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"
   

2. custom-config.toml 파일에서 custom-config-toml라는 이름의 ConfigMap을 만드세요:

    oc create configmap custom-config-toml --from-file config.toml=custom-config.toml
   

3. 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 인증서 구성

1. 사용자 정의 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-----
   

2. 비밀을 생성합니다:

   oc apply -f custom-tls-ca-secret.yaml
   

3. 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

작업 동시성은 프로젝트의 요구 사항에 따라 결정됩니다.

1. CI 작업을 실행하는 데 필요한 컴퓨팅 및 메모리 자원을 파악하는 것부터 시작하세요.

2. 클러스터의 리소스를 고려하여 해당 작업이 몇 번 실행될 수 있을지 계산합니다.

너무 큰 동시성 값을 설정하면 Kubernetes 실행자가 가능한 한 빨리 작업을 처리합니다.
그러나 작업이 언제 예약되는지는 Kubernetes 클러스터의 스케줄러 용량에 의해 결정됩니다.

문제 해결

루트 사용자와 비루트 사용자

GitLab Runner Operator와 GitLab Runner Pod는 비루트 사용자로 실행됩니다.

그 결과, 작업에 사용되는 빌드 이미지는 성공적으로 완료되기 위해 비루트 사용자로 실행되어야 합니다.

이는 최소한의 권한으로 작업이 성공적으로 실행될 수 있도록 하기 위함입니다. 그러나 이를 위해서는

CI 작업에 사용되는 빌드 이미지도 비루트로 실행되도록 빌드되어야 하며, 제한된 파일 시스템에 쓸 수 없어야 합니다.

OpenShift 클러스터의 대부분의 컨테이너 파일 시스템은 읽기 전용이며, 마운트된

볼륨, /var/tmp, /tmp 및 루트 파일 시스템에 마운트된 다른 볼륨이 tmpfs로 설정된 경우를 제외합니다.

HOME 환경 변수 오버라이드

커스텀 빌드 이미지를 생성하거나 환경 변수를 오버라이드하는 경우,

HOME 환경 변수가 읽기 전용인 /로 설정되지 않도록 해야 합니다.

특히 작업에서 홈 디렉토리에 파일을 써야 하는 경우에는 더욱 중요합니다.

예를 들어 /home 아래에 /home/ci 디렉토리를 만들고 Dockerfile에 ENV HOME=/home/ci를 설정할 수 있습니다.

러너 Pods의 경우 기대되는 HOME은 /home/gitlab-runner로 설정될 것입니다.

이 변수가 변경된 경우, 새로운 위치는 적절한 권한을 가져야 합니다.

이러한 지침은 Red Hat Container Platform Docs > 이미지를 생성하기 > 임의 사용자 ID 지원에도 문서화되어 있습니다.

SCC 주의

기본적으로 새로운 OpenShift 프로젝트에 설치될 때, GitLab Runner Operator는 비루트 사용자로 실행됩니다.

모든 서비스 계정이 anyuid 액세스를 부여받은 경우(예: default 프로젝트)에는 예외가 있습니다.

그러한 경우, 이미지의 사용자는 root가 됩니다. 이는 컨테이너 셸 내에서 whoami를 실행하여 쉽게 확인할 수 있습니다.

SCC에 대한 자세한 내용은 Red Hat Container Platform Docs > 보안 컨텍스트 제약 조건 관리에서 확인하세요.

anyuid SCC로 실행

권장되지 않지만, CI 작업을 루트 사용자로 실행해야 하거나 루트 파일 시스템에 쓰는 것이 절대적으로 필요한 경우,

GitLab Runner 컨테이너에서 사용되는 GitLab Runner 서비스 계정인 gitlab-runner-sa에 대해 anyuid SCC를 설정해야 합니다.

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 기능이 필요합니다. 이 문제를 해결하려면:

1. GitLab Runner가 사용하는 SCC에 SETFCAP 기능을 추가합니다(다른 SCC의 경우 gitlab-scc를 교체):

   oc patch scc gitlab-scc --type merge -p '{"allowedCapabilities":["SETFCAP"]}'
   

2. 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"]
   

3. GitLab Runner가 배포된 네임스페이스에서 이 config.toml을 사용하여 configmap을 생성합니다:

   oc create configmap custom-config-toml --from-file config.toml=config.toml
   

4. 수정할 러너를 선택하고 최근에 생성된 configmap을 가리키도록 config: 매개변수를 추가합니다(올바른 러너 pod 이름으로 my-runner를 교체):

   oc patch runner my-runner --type merge -p '{"spec": {"config": "custom-config-toml"}}'
   

자세한 내용은 Red Hat 문서를 참조하세요.

FIPS 호환 GitLab Runner 사용

FIPS 호환 GitLab Runner Helper를 사용하려면 도우미 이미지를 다음과 같이 변경합니다:

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 스펙 섹션에서 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 등록

러너가 자체 서명된 인증서를 호스트 이름과 일치시킬 수 없으면 오류 메시지가 발생할 수 있습니다. 이는 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

이 문제를 해결하려면:

1. GitLab 자체 관리 서버에서 openssl을 수정하여 subjectAltName 매개변수에 IP 주소를 추가합니다:

   # vim /etc/pki/tls/openssl.cnf
   
   [ v3_ca ]
   subjectAltName=IP:169.57.64.36 <---- 이 줄을 추가합니다. 169.57.64.36은 귀하의 GitLab 서버 IP입니다.
   

2. 그런 다음 아래 명령어를 사용하여 자체 서명된 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
   

3. 이 새 인증서를 사용하여 새 비밀을 생성합니다.