• GitLab Runner Operator에 속성 전달
• Operator 속성
• 캐시 속성
  • S3 캐시
  • GCS 캐시
  • Azure 캐시
• 프록시 환경 구성
• 구성 템플릿을 사용한 config.toml 사용자 정의
• 사용자 정의 TLS 인증서 구성
• 러너 파드의 CPU 및 메모리 크기 구성
• 클러스터 리소스에 기반한 러너 당 작업 동시성 구성
• 문제 해결
  • 루트 vs. 비루트
    • 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. 자세한 내용은 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 사용자 정의

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

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

2. custom-config.toml 파일에서 custom-config-toml이름의 config.toml를 생성합니다:

    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 클러스터의 스케줄러 용량이 작업을 스케줄링하는 시기를 결정합니다.

문제 해결

루트 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 기능이 부여되어야 합니다. 이 문제를 해결하려면 다음을 수행합니다:

1. GitLab 러너가 사용하는 SCC에 SETFCAP 기능을 추가합니다. (gitlab-scc를 사용 중인 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. 이 config.toml을 GitLab 러너가 배포된 네임스페이스에 사용하여 configmap을 생성합니다:

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

4. 수정하려는 러너에 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

이 문제를 해결하려면:

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

   # 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. 이 새로운 인증서를 사용하여 새로운 시크릿을 생성하세요.