[GitLab] Helm Chart - Backup 설정하기

728x90

GitLab을 Helm Chart를 이용해 Kubernetes 클러스터(EKS)에 배포하는 경우, 주기적인 백업이 필요합니다.

이를 위해 GitLab의 Toolbox 컨테이너를 활용하여 백업을 수행할 수 있으며, 백업 데이터를 S3에 저장하도록 설정할 수 있습니다.

이 글에서는 GitLab Helm Chart에서 Backup을 설정하는 방법을 설명하고, 백업 수행 후 S3 업로드까지의 과정을 진행합니다.

Helm Chart Version : 8.7.0
GitLab App Version : v17.7.0

GitLab Toolbox를 활용한 백업 설정

1. Toolbox란?
- GitLab Toolbox는 GitLab에서 제공하는 다양한 유지보수 및 관리 작업을 수행하는 컨테이너입니다.
- 해당 컨테이너의 주요 작업으로는 백업, 복원, Git 저장소 정리 및 기타 관리 작업이 포함됩니다.
- Toolbox는 GitLab Helm Chart에서 기본적으로 제공되며, 주로 toolbox Pod에서 실행됩니다.
- Toolbox를 활용하면 GitLab 인스턴스의 백업을 자동화하고, 필요할 때 복원할 수 있습니다. 특히 Helm Chart로 배포된 GitLab 환경에서는 CronJob을 이용하여 주기적인 백업을 설정할 수 있습니다.

2. Toolbox를 이용한 GitLab 백업 설정 기능
- 백업 자동화: 정해진 스케줄에 따라 백업이 수행됨
- 백업 실패 시 재시도: 지정된 횟수만큼 실패 시 재시도 가능
- 백업 스토리지 연동: AWS S3 등의 오브젝트 스토리지에 백업 가능

GitLabToolbox를 활용한 백업 설정

GitLab의 Helm values.yaml 파일에서 Toolbox의 Backup 관련 설정을 추가합니다.

Toolbox의 백업 관련 설정을 추가하여 자동 백업을 활성화할 수 있습니다.
아래와 같이 설정하면 매주 토요일 새벽 1시(KST)에 백업이 실행되며, 백업 데이터는 S3에 저장됩니다.
또한, GitLab 백업이 S3로 저장되며, 백업 실행 중 오류가 발생하면 자동으로 재시도합니다.

gitlab:
  appConfig:
    object_store:
      enabled: true
      proxy_download: true
      storage_options: {}
        # server_side_encryption:
        # server_side_encryption_kms_key_id
      connection:  
        secret: gitlab-rails-storage
        key: connection
    lfs:
      enabled: true
      proxy_download: true
      bucket: isvsa-gitlab-lfs-storage
    artifacts:
      enabled: true
      proxy_download: true
      bucket: isvsa-gitlab-artifacts-storage
    uploads:
      enabled: true
      proxy_download: true
      bucket: isvsa-gitlab-uploads-storage
    packages:
      enabled: true
      proxy_download: true
      bucket: isvsa-gitlab-packages-storage
    externalDiffs:
      enabled: true
      proxy_download: true
      bucket: isvsa-gitlab-externaldiffs-storage
    terraformState:
      enabled: false
      bucket: isvsa-gitlab-terraformstate-storage
    ciSecureFiles:
      enabled: false
      bucket: isvsa-gitlab-cisecure-storage
    dependencyProxy:
      enabled: false
      bucket: isvsa-gitlab-dependencyproxy-storage
    backups:
      bucket: isvsa-gitlab-backups-storage

  toolbox:
    backups:
      cron:
        enabled: true                       
        timeZone: "Asia/Seoul"
        concurrencyPolicy: Replace         
        successfulJobsHistoryLimit: 5      
        failedJobsHistoryLimit: 5          
        schedule: "0 1 * * 6"              
        successfulJobsHistoryLimit: 2      
        suspend: false                     
        backoffLimit: 20                   
        restartPolicy: "OnFailure"         
        extraArgs: --skip artifacts --skip lfs --skip packages --skip uploads
      objectStorage:
        backend: s3
        config: 
          secret: gitlab-rails-storage
          key: connection

옵션 값 설명

옵션	값	설명
enabled	true	백업 자동 실행 활성화
timeZone	Asia/Seoul	백업 스케줄의 기준 시간대 설정
concurrencyPolicy	Replace	기존 백업이 실행 중이면 새로운 백업을 실행하지 않음
successfulJobsHistoryLimit	5	성공한 백업 작업의 기록을 최대 5개까지 보관
failedJobsHistoryLimit	5	실패한 백업 작업의 기록을 최대 5개까지 보관
schedule	0 1 * * 6	백업 실행 스케줄 (매주 토요일 01:00 KST)
suspend	false	true로 설정하면 백업 스케줄을 비활성화
backoffLimit	20	백업이 실패했을 경우 최대 20번까지 재시도
restartPolicy	OnFailure	백업 작업이 실패하면 자동으로 재시작
extraArgs	--skip artifacts --skip lfs --skip packages --skip uploads	불필요한 데이터 제외
backend	s3	백업 데이터를 저장할 백엔드 (Amazon S3)
config.secret	gitlab-rails-storage	S3 접근을 위한 Kubernetes Secret 이름
config.key	connection	Secret 내부에서 S3 설정이 저장된 키

설정 적용 및 CronJob 확인

위 설정을 values.yaml에 추가한 후 Helm을 이용하여 배포합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab -n gitlab

배포가 완료되면 CronJob이 생성되었는지 확인할 수 있습니다.

kubectl get cronjob -n gitlab gitlab-toolbox-backup

출력 결과:

NAME                    SCHEDULE    TIMEZONE     SUSPEND   ACTIVE   LAST SCHEDULE   AGE
gitlab-toolbox-backup   0 1 * * 6   Asia/Seoul   False     0        0m              167m

정상적으로 CronJob이 설정되었다면, 실제로 백업이 실행되는지 확인해야 합니다.

CronJob을 즉시 실행하여 해당 기능 디버깅

⚠️ 이 과정은 테스트용이며, 실제 운영 환경에서는 cronjob.batch를 통해 자동으로 실행됩니다.

설정이 정상적으로 적용되었는지 확인하려면 CronJob을 수동으로 실행하여 백업이 정상적으로 동작하는지 테스트할 수 있습니다.
기존 CronJob을 기반으로 새로운 Job을 수동으로 실행하는 명령어를 실행합니다.

kubectl create job --from=cronjob/gitlab-toolbox-backup gitlab-toolbox-backup-debug -n gitlab

배포가 완료되면 CronJob이 생성되었는지 확인할 수 있습니다.
실행 중인 백업 Job을 확인 명령어를 실행합니다.

kubectl get jobs -n gitlab | grep gitlab-toolbox-backup

Job이 실행 중이라면 로그를 확인할 수 있습니다.

kubectl logs -f -l job-name=gitlab-toolbox-backup-debug -n gitlab

로그 출력 예시:

Defaulted container "toolbox-backup" out of: toolbox-backup, certificates (init), configure (init)
Begin parsing .erb templates from /var/opt/gitlab/templates
Writing /srv/gitlab/config/cable.yml
Writing /srv/gitlab/config/database.yml
Writing /srv/gitlab/config/gitlab.yml
Writing /srv/gitlab/config/resque.yml
Writing /srv/gitlab/config/session_store.yml
Begin parsing .tpl templates from /var/opt/gitlab/templates
Copying other config files found in /var/opt/gitlab/templates to /srv/gitlab/config
Copying smtp_settings.rb into /srv/gitlab/config
Attempting to run '/bin/bash -c cp /etc/gitlab/.s3cfg $HOME/.s3cfg && backup-utility --skip artifacts --skip lfs --skip packages --skip uploads' as a main process
2025-03-04 15:02:29 +0900 -- Dumping database ... 
2025-03-04 15:02:29 +0900 -- Dumping PostgreSQL database gitlabhq_production ... 
2025-03-04 15:03:27 +0900 -- [DONE]
2025-03-04 15:03:27 +0900 -- Dumping database ... done
2025-03-04 15:03:27 +0900 -- Deleting backup and restore PID file at [/srv/gitlab/tmp/backup_restore.pid] ... done
2025-03-04 15:04:42 +0900 -- Dumping repositories ...

...
...
...

2025-03-04 15:05:01 +0900 -- Dumping repositories ... done
2025-03-04 15:05:01 +0900 -- Deleting backup and restore PID file at [/srv/gitlab/tmp/backup_restore.pid] ... done
Dumping registry ...
done
Dumping external_diffs ...
done
Dumping terraform_state ...
empty
Bucket not found: gitlab-pages. Skipping backup of pages ...
Dumping ci_secure_files ...
empty
WARNING: Active Record does not support composite primary key.

security_findings has composite primary key. Composite primary key is ignored.
Packing up backup tar
WARNING: Ignoring invalid line in '/home/git/.s3cfg': provider: AWS

WARNING: Ignoring invalid line in '/home/git/.s3cfg': region: ap-northeast-2

WARNING: Ignoring invalid line in '/home/git/.s3cfg': use_iam_profile: true

WARNING: Ignoring invalid line in '/home/git/.s3cfg': endpoint: https://s3.ap-northeast-2.amazonaws.com
WARNING: Module python-magic is not available. Guessing MIME types based on file extensions.
[DONE] Backup can be found at s3://isvsa-gitlab-backups-storage/1741068067_2025_03_04_17.7.0-ee_gitlab_backup.tar

S3에 백업이 정상적으로 업로드되었는지 확인합니다.

aws s3 ls s3://isvsa-gitlab-backups-storage/

개인 정리

기존 Omnibus 설치 방식에서는 Crontab을 이용한 백업 자동화가 가능했지만, Helm Chart 환경에서는 Toolbox 컨테이너 내부에서 실행되는 CronJob을 통해 백업이 관리된다는 점이 차이점 존재!!

초기에는 timeZone 설정이 적용되지 않아 UTC 기준으로 백업이 실행되었으며, 백업 스케줄과 실행 환경을 정확히 조정하는 과정에서 몇 가지 시행착오를 겪음... 특히, CronJob이 올바르게 스케줄링되었는지 확인하는 과정과 실제 백업 데이터가 S3에 정상적으로 업로드되는지 검증하는 과정에서 추가적인 조치가 필요...

values.yaml 설정을 조정하여 KST(Asia/Seoul) 시간대를 적용하고, 백업이 매주 토요일 오전 1시에 실행되도록 구성하였고 패키지, 아티팩트 같은 경우 이미 S3에 대한 백엔드를 적용해놓았기에, extraArgs 옵션을 활용해 필요하지 않은 백업 항목을 제외하고 최적화된 백업을 수행할 수 있도록 설정 완료

Helm Chart 환경에서는 Toolbox 컨테이너 내부에서 실행되는 CronJob을 통해 백업이 관리된다는 점이 있어 기존 Omnibus 설치 방식에서의 Crontab 보다 개인적으로는 편하게 설정할 수 있는 것 같음... 물론 정상 구동 되도록 구성이 되었다는 가정하에

728x90

저작자표시 비영리 변경금지 (새창열림)

'GitLab' 카테고리의 다른 글

[GitLab Runner] Helm Chart 설치 (AWS IRSA 적용) (1)	2025.03.09
[GitLab] Keycloak OIDC - 그룹 기반 인증 연동 설정 (w. terraform) (2)	2024.10.13
[GitLab] Okta SAML연동을 통한 SSO(Single Sign-On) 설정하기 (0)	2024.06.23

준호의 발자취

[GitLab] Helm Chart - Backup 설정하기

GitLab Toolbox를 활용한 백업 설정

GitLabToolbox를 활용한 백업 설정

설정 적용 및 CronJob 확인

CronJob을 즉시 실행하여 해당 기능 디버깅

개인 정리

'GitLab' 카테고리의 다른 글

티스토리툴바

[GitLab] Helm Chart - Backup 설정하기

GitLab Toolbox를 활용한 백업 설정

GitLabToolbox를 활용한 백업 설정

설정 적용 및 CronJob 확인

CronJob을 즉시 실행하여 해당 기능 디버깅

개인 정리

'GitLab' 카테고리의 다른 글

'GitLab' Related Articles

티스토리툴바

GitLab Toolbox를 활용한 백업 설정

GitLabToolbox를 활용한 백업 설정

설정 적용 및 CronJob 확인

CronJob을 즉시 실행하여 해당 기능 디버깅