이 문서는 OpenShift에서 GitLab Runner를 구성하는 방법을 설명합니다.

GitLab Runner Operator에 속성 전달#

Runner를 생성할 때, spec에 속성을 설정하여 구성할 수 있습니다. 예를 들어, Runner가 등록된 GitLab URL이나 등록 토큰이 포함된 시크릿의 이름을 지정할 수 있습니다:

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret # 러너 토큰이 포함된 시크릿의 이름

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 # 러너 토큰이 포함된 시크릿의 이름
     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//secrets: net/http: TLS handshake timeout. Check https://docs.gitlab.com/runner/shells/#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 파일을 사용자 지정할 수 있습니다.

1. 사용자 정의 구성 템플릿 파일을 생성합니다. 예를 들어, Runner가 EmptyDir 볼륨을 마운트하고 cpu_limit을 설정하도록 지시해 보겠습니다. custom-config.toml 파일을 생성합니다:

   [[runners]]
     [runners.kubernetes]
       cpu_limit = "500m"
       [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
   

Runner 포드의 CPU 및 메모리 크기 구성#

사용자 정의 config.toml 파일에서 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

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

1. 먼저 CI 작업을 실행하는 데 필요한 컴퓨팅 및 메모리 리소스를 결정합니다.
2. 클러스터의 리소스를 감안하여 해당 작업이 몇 번 실행될 수 있는지 계산합니다.

높은 동시성 값을 설정하면 Kubernetes 실행자가 가능한 빨리 작업을 처리합니다. 그러나 Kubernetes 클러스터의 스케줄러 용량이 작업이 언제 스케줄될지를 결정합니다.

GitLab Runner 관리자의 서비스 계정#

신규 설치의 경우, GitLab Runner는 다음 RBAC 역할 바인딩 리소스가 없는 경우 Runner 관리자 포드에 대해 gitlab-runner-app-sa라는 이름의 Kubernetes ServiceAccount를 생성합니다:

• gitlab-runner-app-rolebinding
• gitlab-runner-rolebinding

역할 바인딩 중 하나가 존재하는 경우 GitLab은 역할 바인딩에 정의된 subjects 및 roleRef에서 역할과 서비스 계정을 확인합니다.

두 역할 바인딩이 모두 존재하는 경우 gitlab-runner-app-rolebinding이 gitlab-runner-rolebinding보다 우선합니다.

트러블슈팅#

Root 대 non-root#

GitLab Runner Operator와 GitLab Runner 포드는 non-root 사용자로 실행됩니다. 결과적으로 작업에 사용되는 빌드 이미지도 성공적으로 완료하려면 non-root 사용자로 실행되어야 합니다. 이렇게 하면 작업이 최소한의 권한으로 성공적으로 실행될 수 있습니다.

이것이 작동하려면 CI/CD 작업에 사용되는 빌드 이미지가 다음을 확인해야 합니다:

• Non-root로 실행됨
• 제한된 파일 시스템에 쓰지 않음

OpenShift 클러스터의 대부분의 컨테이너 파일 시스템은 읽기 전용이며, 예외는 다음과 같습니다:

• 마운트된 볼륨
• /var/tmp
• /tmp
• 루트 파일 시스템에 tmpfs로 마운트된 기타 볼륨

HOME 환경 변수 재정의#

사용자 정의 빌드 이미지를 생성하거나 환경 변수를 재정의하는 경우, HOME 환경 변수가 읽기 전용인 /로 설정되지 않도록 합니다. 특히 작업이 홈 디렉터리에 파일을 써야 하는 경우입니다. 예를 들어 /home 아래에 /home/ci와 같은 디렉터리를 생성하고 Dockerfile에서 ENV HOME=/home/ci를 설정할 수 있습니다.

Runner 포드의 경우 HOME이 /home/gitlab-runner로 설정될 것으로 예상됩니다. 이 변수가 변경되면 새 위치에 적절한 권한이 있어야 합니다. 이러한 지침은 Red Hat Container Platform 문서에도 문서화되어 있습니다.

locked 변수 재정의#

Runner 토큰을 등록할 때 locked 변수를 true로 설정하면 다음 오류가 발생합니다: Runner configuration other than name, description, and exector is reserved and cannot be specified

  locked: true # REQUIRED
  tags: ""
  runUntagged: false
  protected: false
  maximumTimeout: 0

자세한 내용은 이슈 472를 참조하세요.

보안 컨텍스트 제약 사항 주의#

기본적으로 새 OpenShift 프로젝트에 설치될 때 GitLab Runner Operator는 non-root로 실행됩니다. default 프로젝트와 같이 모든 서비스 계정이 anyuid 액세스를 가지는 일부 프로젝트는 예외입니다. 이 경우 이미지의 사용자는 root입니다. 모든 컨테이너 셸에서 whoami를 실행하여 이를 확인할 수 있습니다. 예를 들어 작업에서 확인합니다. 보안 컨텍스트 제약 사항에 대한 자세한 내용은 Red Hat Container Platform 문서를 참조하세요.

anyuid 보안 컨텍스트 제약 사항으로 실행#

CI/CD 작업을 root 사용자로 실행하거나 root 파일 시스템에 쓰려면 gitlab-runner-app-sa 서비스 계정에 anyuid 보안 컨텍스트 제약 사항을 설정합니다. GitLab Runner 컨테이너는 이 서비스 계정을 사용합니다.

OpenShift 4.3.8 이전:

oc adm policy add-scc-to-user anyuid -z gitlab-runner-app-sa -n <runner_namespace>

# anyiud SCC가 설정되었는지 확인:
oc get scc anyuid -o yaml

OpenShift 4.3.8 이후:

oc create -f - <
rules:
- apiGroups:
  - security.openshift.io
  resourceNames:
  - anyuid
  resources:
  - securitycontextconstraints
  verbs:
  - use
EOF

oc create -f - <
subjects:
  - kind: ServiceAccount
    name: gitlab-runner-app-sa
roleRef:
  kind: Role
  name: scc-anyuid
  apiGroup: rbac.authorization.k8s.io
EOF

헬퍼 컨테이너와 빌드 컨테이너의 사용자 ID 및 그룹 ID 일치#

GitLab Runner Operator 디플로이먼트는 기본 헬퍼 이미지로 registry.gitlab.com/gitlab-org/ci-cd/gitlab-runner-ubi-images/gitlab-runner-helper-ocp를 사용합니다. 이 이미지는 보안 컨텍스트에 의해 명시적으로 수정되지 않는 한 1001:1001의 사용자 ID 및 그룹 ID로 실행됩니다.

빌드 컨테이너의 사용자 ID가 헬퍼 이미지의 사용자 ID와 다를 경우 빌드 중 권한 관련 오류가 발생할 수 있습니다. 다음은 일반적인 오류 메시지입니다:

fatal: detected dubious ownership in repository at '/builds/gitlab-org/gitlab-runner'

이 오류는 저장소가 사용자 ID 1001(헬퍼 컨테이너)에 의해 복제되었지만 빌드 컨테이너의 다른 사용자 ID가 이에 액세스하려고 함을 나타냅니다.

해결 방법: 빌드 컨테이너의 보안 컨텍스트를 헬퍼 컨테이너의 사용자 ID 및 그룹 ID와 일치하도록 구성합니다:

[runners.kubernetes.build_container_security_context]
run_as_user = 1001
run_as_group = 1001

추가 참고 사항:

• 이러한 설정은 저장소를 복제하는 컨테이너와 빌드하는 컨테이너 간에 일관된 파일 소유권을 보장합니다.
• 헬퍼 이미지를 다른 사용자 ID 또는 그룹 ID로 사용자 정의한 경우 해당 값을 적절히 조정합니다.
• OpenShift 디플로이먼트의 경우 이러한 보안 컨텍스트 설정이 클러스터의 보안 컨텍스트 제약 사항(SCC)을 준수하는지 확인합니다.

SETFCAP 구성#

RHOCP(Red Hat OpenShift Container Platform) 4.11 이상을 사용하는 경우 다음 오류 메시지가 발생할 수 있습니다:

error reading allowed ID mappings:error reading subuid mappings for user

일부 작업(예: buildah)은 올바르게 실행하기 위해 SETFCAP 기능이 필요합니다. 이 문제를 해결하려면:

1. GitLab Runner가 사용하는 보안 컨텍스트 제약 사항에 SETFCAP 기능을 추가합니다(gitlab-scc를 GitLab Runner 포드에 할당된 보안 컨텍스트 제약 사항으로 교체):

   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. 수정하려는 Runner를 수정하여 최근에 생성한 ConfigMap을 가리키는 config: 매개변수를 추가합니다(my-runner를 올바른 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 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 Self-Managed를 호스트 이름 대신 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 Self-Managed 서버에서 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. 이 새 인증서를 사용하여 새 시크릿을 생성합니다.

패치 구조#

각 스펙 패치는 다음 속성으로 구성됩니다:

동일한 스펙 구성에서 patchFile과 patch를 동시에 설정할 수 없습니다.

Runner 포드 템플릿 패치#

포드 스펙 패치는 Operator가 생성한 Kubernetes 디플로이먼트에 패치를 적용하여 GitLab Runner가 배포되는 방식을 사용자 정의할 수 있게 해줍니다. 패치는 포드 템플릿의 스펙(deployment.spec.template.spec)에 적용됩니다.

다음과 같은 포드 수준 설정을 제어할 수 있습니다:

• 리소스 요청 및 제한
• 보안 컨텍스트
• 볼륨 마운트 및 볼륨
• 환경 변수
• 노드 셀렉터 및 어피니티 규칙
• 톨러레이션
• 호스트 이름 및 DNS 구성

Runner 디플로이먼트 템플릿 패치#

디플로이먼트 스펙 패치는 Operator가 생성한 Kubernetes 디플로이먼트에 패치를 적용하여 GitLab Runner가 배포되는 방식을 사용자 정의할 수 있게 해줍니다. 패치는 디플로이먼트 스펙(deployment.spec)에 적용됩니다.

다음과 같은 디플로이먼트 수준 설정을 제어할 수 있습니다:

• 레플리카 수
• 디플로이먼트 전략 (RollingUpdate, Recreate)
• 리비전 히스토리 제한
• 진행 데드라인 초
• 레이블 및 어노테이션

패치 순서#

디플로이먼트 스펙 패치는 포드 스펙 패치 전에 적용됩니다. 즉, 디플로이먼트와 포드 스펙이 동일한 필드를 수정하는 경우 포드 스펙이 우선합니다.

예시#

포드 스펙 패치 예시#

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  podSpec:
    - name: "set-hostname"
      patch: |
        hostname: "custom-hostname"
      patchType: "merge"
    - name: "add-resource-requests"
      patch: |
        containers:
        - name: build
          resources:
            requests:
              cpu: "500m"
              memory: "256Mi"
      patchType: "strategic"

디플로이먼트 스펙 패치 예시#

apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: dev
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
  deploymentSpec:
    - name: "set-replicas"
      patch: |
        replicas: 3
      patchType: "strategic"
    - name: "configure-strategy"
      patch: |
        strategy:
          type: RollingUpdate
          rollingUpdate:
            maxUnavailable: 25%
            maxSurge: 50%
      patchType: "strategic"
    - name: "set-revision-history"
      patch: |
        [{"op": "add", "path": "/revisionHistoryLimit", "value": 10}]
      patchType: "json"

모범 사례#

• 프로덕션 디플로이먼트에 적용하기 전에 비프로덕션 환경에서 패치를 테스트합니다.
• 개별 포드 설정보다 디플로이먼트 동작에 영향을 미치는 설정에는 디플로이먼트 수준 패치를 사용합니다.
• 충돌하는 필드에 대해 포드 스펙 패치가 디플로이먼트 스펙 패치보다 우선한다는 점을 기억합니다.