2. GitLab이란? / GitLab Runner 개념 및 설치

CI/CD 파이프라인이 구성된 GitLab 리포지토리에 코드 변경 사항을 푸시하면 GitLab은 하나 이상의 작업이 포함된 새 파이프라인을 생성한다.
GitLab Runner는 GitLab 서버에서 실행할 새 작업을 주기적으로 확인한다. 작업을 사용할 수 있는 경우 러너는 작업을 선택하고 실행을 시작한다.
Runner는 프로젝트의 .gitlab-ci.yml 파일에 정의된 작업 단계(예: 빌드, 테스트 또는 배포)를 실행한다. 이러한 단계에는 코드를 빌드, 테스트 및 배포하는 데 필요한 스크립트, 명령 및 기타 작업이 포함될 수 있다.
Runner가 작업을 실행하면 실시간 상태 업데이트, 로그 및 생성된 모든 아티팩트를 GitLab 서버로 다시 보낸다. 이를 통해 파이프라인 및 해당 작업의 진행 상황을 모니터링하고 검토할 수 있다.
작업이 완료되면 Runner는 최종 상태(성공 또는 실패)를 GitLab 서버에 보고한다. 이를 통해 코드 또는 파이프라인에서 해결해야 하는 문제 또는 개선 사항을 식별할 수 있다.

GitLab Runner의 종류

공유 러너(Shared Runner)

이러한 실행기는 GitLab 인스턴스 내의 모든 프로젝트에서 사용할 수 있다. GitLab 관리자가 구성하고 관리하며 동일한 GitLab 인스턴스의 모든 프로젝트에서 사용할 수 있다. Shared Runner는 여러 프로젝트 및 팀에 공통 빌드 환경을 제공하려는 경우에 유용하다.

그룹 러너(Group Runner)

그룹 러너는 GitLab 인스턴스 내의 특정 프로젝트 그룹 전용이다. 그룹 관리자가 구성하고 관리할 수 있으며 해당 그룹 내의 프로젝트에서만 사용할 수 있다. Group Runner를 사용하면 GitLab 인스턴스의 다른 프로젝트에 영향을 주지 않고 특정 프로젝트 그룹의 CI/CD 리소스를 관리할 수 있다.

개인화 러너(Specific Runner)

Project Runner라고도 하는 특정 Runner는 단일 프로젝트 전용이다. 해당 Runner는 프로젝트의 CI/CD 파이프라인에 특별히 사용되는 리소스 및 환경에 대한 제어를 제공한다. 다른 프로젝트와 공유해서는 안 되는 프로젝트에 대한 고유한 요구 사항이나 리소스가 있을 때 유용할 수 있다.

GitLab Group Runner 설정

나머지 설정방법과 거의 동일하다.

1. Gitlab menu - Group - Your Group

2. 원하는 Group 선택

3. Settings - CI/CD

CI/CD 메뉴에서 Runners로 접근하면 Group runners에 등록할 URl과 토큰 정보가 보인다.

이 값은 서버에서 runner를 생성할 때 필요하다.

GitLab Runner 설치(Helm)

Group Runner를 사용할 것이다. 그리고 Kubernetes에 구성할 것이다.

Step 1. 사전준비

gitlabUrl - 러너를 등록할 GitLab 서버 전체 URL (예: http://gitlab.example.com)
runnerRegistrationToken - GitLab에 새 러너를 추가하기 위한 등록 토큰이다. (CICD - Runner Tab 등록)

Step 2. GitLab Repo 추가

$ helm repo add gitlab https://charts.gitlab.io/

$ helm repo list
NAME                    URL
stable                  https://charts.helm.sh/stable
gitlab                  https://charts.gitlab.io/

# 최신 chart 확인
$helm repo update

Step 3. role / rolebinging yaml 파일 추가(최신버전에서는 필요X)

$ cat gitlab-runner-role.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gitlab-runner-role
rules:
  - apiGroups: ["extensions", "apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["pods","services","secrets","pods/exec", "serviceaccounts"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

$ cat gitlab-runner-role-binding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gitlab-runner-role-binding
subjects:
- kind: ServiceAccount
  name: default
roleRef:
  kind: Role
  name: gitlab-runner-role
  apiGroup: rbac.authorization.k8s.io

Step 4. overide values.yaml 작성(최신버전v.2024-05-31)

values.yaml이 변경되었다. 해당 내용을 참고하면 된다.

image:
  registry: registry.gitlab.com
  image: gitlab-org/gitlab-runner
  tag: alpine-v17.0.0

imagePullPolicy: IfNotPresent

imagePullSecrets:
   - name: "somaz-secret" # your image registry secrets
   
replicas: 3

gitlabUrl: http://gitlab.somaz.link/

runnerToken: "glrt-xxxxx_Xxxxxxa-xxxxx" # token 값이 변경되었다.

rbac:
  create: true
  
  rules: 
    - apiGroups: ["extensions", "apps"]
      resources: ["deployments"]
      verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
    - apiGroups: [""]
      resources: ["pods", "pods/exec", "pods/attach", "services", "secrets", "serviceaccounts"]
      verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "attach"]

  clusterWideAccess: false

  podSecurityPolicy:
    enabled: false
    resourceNames:
    - gitlab-runner

  config: |
    [[runners]]
      [runners.kubernetes]
        namespace = "{{.Release.Namespace}}"
        image = "ubuntu:22.04"

  tags: "build-image"

securityContext:
  allowPrivilegeEscalation: true  # Permits elevating privileges; similar to 'sudo'.
  readOnlyRootFilesystem: false   # The root filesystem can be written to.
  runAsNonRoot: false             # Allows the process to run as the root user.
  privileged: true                # Grants the container almost all the same privileges as the host.
  capabilities:
    drop: []                      # No Linux capabilities are dropped; retains all.

Step 4. overide values.yaml 작성(최신버전v.2025-09-03)

## GitLab Runner Image
##
## By default it's using registry.gitlab.com/gitlab-org/gitlab-runner:alpine-v{VERSION}
## where {VERSION} is taken from Chart.yaml from appVersion field
##
## ref: https://gitlab.com/gitlab-org/gitlab-runner/container_registry/29383?orderBy=NAME&sort=asc&search[]=alpine-v&search[]=
##
## Note: If you change the image to the ubuntu release
##       don't forget to change the securityContext;
##       these images run on different user IDs.
##
image:
  registry: registry.gitlab.com
  image: gitlab-org/gitlab-runner
  # tag: alpine-v{{.Chart.AppVersion}}

## How many runner pods to launch.
##
replicas: 2

## How many old ReplicaSets for this Deployment you want to retain
revisionHistoryLimit: 5

## The GitLab Server URL (with protocol) that want to register the runner against
## ref: https://docs.gitlab.com/runner/commands/index.html#gitlab-runner-register
##
gitlabUrl: http://gitlab.somaz.link/

## The Runner Token for adding new Runners to the GitLab Server. This must
## be retrieved from your GitLab instance. It is the token of an already registered runner.
## ref: (we don't have docs for that yet, but we want to use an existing token)
##
runnerToken: "glrt-xxxxxxx"

## Configure the maximum number of concurrent jobs
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
concurrent: 10

## Number of seconds until the forceful shutdown operation times out and exits the process.
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
shutdown_timeout: 0

## Defines in seconds how often to check GitLab for new builds
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
checkInterval: 3

## For RBAC support:
rbac:
  ## Specifies whether a Role and RoleBinding should be created
  ## If this value is set to `true`, `serviceAccount.create` should also be set to either `true` or `false`
  ##
  create: true
  ## Define the generated serviceAccountName when create is set to true
  ## It defaults to "gitlab-runner.fullname" if not provided
  ## DEPRECATED: Please use `serviceAccount.name` instead
  generatedServiceAccountName: ""

  ## Define list of rules to be added to the rbac role permissions.
  ## Each rule supports the keys:
  ## - apiGroups: default "" (indicates the core API group) if missing or empty.
  ## - resources: default "*" if missing or empty.
  ## - verbs: default "*" if missing or empty.
  ##
  ## Read more about the recommended rules on the following link
  ##
  ## ref: https://docs.gitlab.com/runner/executors/kubernetes/index.html#configure-runner-api-permissions
  ##
  rules:
    - apiGroups: ["extensions", "apps"]
      resources: ["deployments"]
      verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
    - apiGroups: [""]
      resources: ["pods","services","secrets","pods/exec", "serviceaccounts", "pods/attach"]
      verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
    # - resources: ["events"]
    #   verbs: ["list", "watch"]
    # - resources: ["namespaces"]
    #   verbs: ["create", "delete"]
    # - resources: ["pods"]
    #   verbs: ["create","delete","get"]
    # - apiGroups: [""]
    #   resources: ["pods/attach","pods/exec"]
    #   verbs: ["get","create","patch","delete"]
    # - apiGroups: [""]
    #   resources: ["pods/log"]
    #   verbs: ["get","list"]
    # - resources: ["secrets"]
    #   verbs: ["create","delete","get","update"]
    # - resources: ["serviceaccounts"]
    #   verbs: ["get"]
    # - resources: ["services"]
    #   verbs: ["create","get"]

  ## Use podSecurity Policy
  ## ref: https://kubernetes.io/docs/concepts/policy/pod-security-policy/
  podSecurityPolicy:
    enabled: true
    resourceNames:
      - gitlab-runner

  ## Specify one or more imagePullSecrets used for pulling the runner image
  ##
  ## ref: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account
  ##
  ## DEPRECATED: Please use `serviceAccount.imagePullSecrets` instead
  ##
  imagePullSecrets: []

serviceAccount:
  ## Specifies whether a ServiceAccount should be created
  ##
  ## TODO: Set default to `false`
  create: true

## Configuration for the Pods that the runner launches for each new job
##
runners:
  # runner configuration, where the multi line string is evaluated as a
  # template so you can specify helm values inside of it.
  #
  # tpl: https://helm.sh/docs/howto/charts_tips_and_tricks/#using-the-tpl-function
  # runner configuration: https://docs.gitlab.com/runner/configuration/advanced-configuration.html
  config: |
    [[runners]]
      [runners.kubernetes]
        namespace = "{{.Release.Namespace}}"
        image = "alpine"

  ## DEPRECATED: Specify the tags associated with the runner. Comma-separated list of tags.
  ##
  ## ref: https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html
  ##
  tags: "build-image"

## Configure securitycontext for the main container
## ref: https://kubernetes.io/docs/concepts/security/pod-security-standards/
##
securityContext:
  allowPrivilegeEscalation: true  # 권한 확대를 허용합니다.
  readOnlyRootFilesystem: false   # 루트 파일 시스템에 쓸 수 있게 합니다.
  runAsNonRoot: false             # 루트로 실행할 수 있게 합니다.
  privileged: true               # 권한이 부여된 모드로 실행을 허용합니다.
  capabilities:
    drop: []                      # 모든 리눅스 캡 능성을 유지합니다.
  
persistentVolumes:
  enabled: false

persistentVolumeClaims:
  enabled: false

Step 5. GitLab Runner 설치

# Before installing, it's a good practice to check the available versions of the GitLab Runner Helm Chart.
helm search repo -l gitlab/gitlab-runner

# Decide on a dedicated namespace for GitLab Runner. Replace <namespace> with your desired namespace name.
kubectl create namespace <namespace>

# If you have specific security configurations or access controls, you may need to set up roles and role bindings. If you've determined it's necessary, apply the provided role and role binding configurations.
# To install
helm install -n <namespace> <release name> -f <helm values file>.yaml gitlab/gitlab-runner

# To upgrade
helm upgrade -n <namespace> <release nam> -f <helm values file>.yaml gitlab/gitlab-runner

GitLab Runner 설치(Helmfile)

Kubernetes에 Gitlab Runner를 설치한다. Helmfile 을 사용하여 설치해 볼 것이다.

Helmfile에 대한 설명은 아래의 글을 참고하면 된다.

2025.05.29 - [Container Orchestration/Kubernetes] - Helmfile 완전 정복: 실무에서 Helm을 선언적으로 관리하는 방법

helmfile 구조

├── Chart.yaml
├── README.md
├── helmfile.yaml
├── values
│   ├── build.yaml
│   ├── deploy.yaml
│   └── old-gitlab-runner.yaml
└── values.yaml

`helmfile.yaml` - v2025.09.03 기준

repositories:
  - name: gitlab
    url: https://charts.gitlab.io

releases:
  - name: build-image
    namespace: gitlab-runner
    chart: gitlab/gitlab-runner
    version: 0.80.0
    values:
      - values/build.yaml

  - name: deploy-image
    namespace: gitlab-runner
    chart: gitlab/gitlab-runner
    version: 0.80.0
    values:
      - values/deploy.yaml

  - name: old-build-deploy-image
    namespace: gitlab-runner
    chart: gitlab/gitlab-runner
    version: 0.70.3
    values:
      - values/old-gitlab-runner.yaml 

  # # test
  # - name: projectm-client-build-image
  #   namespace: gitlab-runner
  #   chart: . # Use local Chart directory
  #   version: 0.71.0
  #   values:
  #     - values/projectm-client-build.yaml

helmfile 배포 방법

# Compare with current state
helmfile diff

# Deploy or update
helmfile apply

# Deploy specific release
helmfile -l name=build-image sync

# Delete all releases
helmfile destroy

# Delete specific release
helmfile -l name=old-build-deploy-image destroy  # Destroy single release

마무리

이번 글에서는 GitLab Runner의 개념과 Helm, Helmfile을 사용한 설치 방법을 정리해 보았다. CI/CD 자동화를 위해 GitLab Runner를 사용하면 코드 변경 사항을 빠르고 효율적으로 배포할 수 있다.

특히 Helmfile을 활용하면 여러 환경의 GitLab Runner를 선언적으로 관리할 수 있어 운영 효율성을 크게 높일 수 있다. 다양한 버전의 차트를 동시에 운영하거나, 환경별로 다른 설정을 적용하는 것도 간편하게 처리할 수 있다.

다음 시간에는 GitLab CI/CD 구동 방식과 GitLab 문법에 대해 자세히 공부해보려고 한다.

Reference

GitLab Runner Docs

GitLab Runner Configure

Gitlab Runner Setting(인포그랩)

참고 기술 블로그(사람인)

Offical GitLab Runner Helm Chart

GitLab Runner documentation for Kubernetes installation

https://github.com/somaz94/cicd-monitoring/tree/main/gitlab-runner

728x90

'IaC > CI CD Tool' 카테고리의 다른 글

2. Github Action (With Syntax) (0)	2023.05.22
1. Github Action이란? (0)	2023.05.19
ArgoCD란? (0)	2023.05.17
3. GitLab이란? / GitLab CI/CD (0)	2023.04.24
1. GitLab이란? / 개념 및 설치 (0)	2023.04.20

현재글2. GitLab이란? / GitLab Runner 개념 및 설치

Somaz의 IT 공부 일지