• 사전 요구 사항
• 백업 및 복원 절차
• 객체 저장소
  • S3에 백업
  • Google Cloud Storage(GCS)에 백업
    • GCS 자격 증명
    • GKE에 대한 워크로드 아이덴티티 연합 구성하기
  • Azure blob storage에 백업
• 문제 해결
  • Pod 종료 문제
  • “Bucket not found” 오류
  • GCP에서 “AccessDeniedException: 403” 오류
  • “ERROR: /home/git/.s3cfg: None” 오류가 --backend s3로 backup-utility를 실행할 때 발생
  • S3 사용 시 “PermissionError: File not writable” 오류
  • 복원 시 건너뛴 리포지토리

GitLab 인스턴스 백업 및 복원

GitLab Helm 차트는 GitLab 인스턴스를 백업하고 복원하기 위한 인터페이스로 작동하는 Toolbox 서브 차트의 유틸리티 포드를 제공합니다. 이 포드는 이 작업을 위해 필요한 다른 포드와 상호작용하는 backup-utility 실행 파일이 장착되어 있습니다. 유틸리티 작동에 대한 기술 세부사항은 아키텍처 문서에서 확인할 수 있습니다.

사전 요구 사항

• 이곳에 설명된 백업 및 복원 절차는 S3 호환 API에서만 테스트되었습니다. Google Cloud Storage와 같은 다른 객체 저장 서비스에 대한 지원은 향후 수정에서 테스트될 예정입니다.

• 복원하는 동안 백업 tarball은 디스크에 추출해야 합니다. 이는 Toolbox 포드가 필요한 크기의 디스크를 사용할 수 있어야 함을 의미합니다.

• 이 차트는 artifacts, uploads, packages, registry 및 lfs 객체를 위한 객체 저장소 사용에 의존하며, 현재 복원 시 이를 자동으로 마이그레이션하지 않습니다. 다른 인스턴스에서 생성된 백업을 복원하는 경우, 백업을 생성하기 전에 기존 인스턴스를 객체 저장소를 사용하도록 마이그레이션해야 합니다. 이슈 646을 참조하세요.

백업 및 복원 절차

• GitLab 설치 백업
• GitLab 설치 복원

객체 저장소

이 차트를 사용할 때 외부 객체 저장소(external object storage)가 지정되지 않는 한, 기본적으로 MinIO 인스턴스를 제공합니다. Toolbox는 특정 설정이 주어지지 않는 한 기본적으로 포함된 MinIO에 연결됩니다. Toolbox는 또한 Amazon S3 또는 Google Cloud Storage(GCS)에 백업하도록 구성할 수 있습니다.

S3에 백업

Toolbox는 기본적으로 객체 저장소에 연결하기 위해 s3cmd를 사용하며, 다른 S3 도구를 사용하도록 지정하지 않는 한 유지됩니다. 외부 객체 저장소에 연결을 구성하려면 gitlab.toolbox.backups.objectStorage.config.secret를 지정해야 하며, 이는 .s3cfg 파일을 포함하는 Kubernetes 비밀을 가리킵니다. 기본값인 config와 다르다면 gitlab.toolbox.backups.objectStorage.config.key를 지정해야 합니다. 이는 .s3cfg 파일의 내용을 포함하는 키입니다.

다음과 같이 보여야 합니다:

helm install gitlab gitlab/gitlab \
  --set gitlab.toolbox.backups.objectStorage.config.secret=my-s3cfg \
  --set gitlab.toolbox.backups.objectStorage.config.key=config .

s3cmd .s3cfg 파일 문서는 여기에서 확인할 수 있습니다.

또한 두 개의 버킷 위치를 구성해야 합니다. 하나는 백업 저장용이고, 하나는 백업 복원 시 사용되는 임시 버킷입니다.

--set global.appConfig.backups.bucket=gitlab-backup-storage  
--set global.appConfig.backups.tmpBucket=gitlab-tmp-storage  

Google Cloud Storage(GCS)에 백업

GCS에 백업하려면 먼저 gitlab.toolbox.backups.objectStorage.backend를 gcs로 설정해야 합니다. 이는 Toolbox가 객체를 저장하고 검색할 때 gsutil CLI를 사용하도록 보장합니다.

또한 두 개의 버킷 위치를 구성해야 합니다. 하나는 백업 저장용이고, 하나는 백업 복원 시 사용되는 임시 버킷입니다.

--set global.appConfig.backups.bucket=gitlab-backup-storage  
--set global.appConfig.backups.tmpBucket=gitlab-tmp-storage  

백업 유틸리티는 이러한 버킷에 접근할 수 있어야 합니다. 접근을 부여하는 방법은 두 가지가 있습니다:

• Kubernetes 비밀에서 자격 증명을 지정합니다.
• GKE를 위한 워크로드 아이덴티티 연합을 구성합니다.

GCS 자격 증명

먼저, gitlab.toolbox.backups.objectStorage.config.gcpProject를 저장소 버킷이 포함된 GCP 프로젝트의 프로젝트 ID로 설정합니다.

활성 서비스 계정 JSON 키 내용을 포함하는 Kubernetes 비밀을 생성해야 하며, 서비스 계정은 백업에 사용할 버킷에 대한 storage.admin 역할을 가져야 합니다. 아래는 gcloud 및 kubectl을 사용하여 비밀을 생성하는 예입니다.

export PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create gitlab-gcs --display-name "Gitlab Cloud Storage"
gcloud projects add-iam-policy-binding --role roles/storage.admin ${PROJECT_ID} --member=serviceAccount:gitlab-gcs@${PROJECT_ID}.iam.gserviceaccount.com
gcloud iam service-accounts keys create --iam-account gitlab-gcs@${PROJECT_ID}.iam.gserviceaccount.com storage.config
kubectl create secret generic storage-config --from-file=config=storage.config

백업을 위해 GCS에 인증하는 데 서비스 계정 키를 사용하도록 Helm 차트를 다음과 같이 구성합니다:

helm install gitlab gitlab/gitlab \
  --set gitlab.toolbox.backups.objectStorage.config.secret=storage-config \
  --set gitlab.toolbox.backups.objectStorage.config.key=config \
  --set gitlab.toolbox.backups.objectStorage.config.gcpProject=my-gcp-project-id \
  --set gitlab.toolbox.backups.objectStorage.backend=gcs

GKE에 대한 워크로드 아이덴티티 연합 구성하기

GKE에 대한 워크로드 아이덴티티 연합에 대한 문서를 참조하세요.

Kubernetes ServiceAccount를 참조하는 IAM 허용 정책을 만들 때, roles/storage.objectAdmin 역할을 부여합니다.

백업을 위해 Google의 애플리케이션 기본 자격 증명이 사용되도록 하려면 gitlab.toolbox.backups.objectStorage.config.secret와 gitlab.toolbox.backups.objectStorage.config.key가 설정되지 않도록 해야 합니다.

Azure blob storage에 백업

Azure blob storage는 gitlab.toolbox.backups.objectStorage.backend를 azure로 설정하여 백업을 저장하는 데 사용할 수 있습니다. 이렇게 하면 Toolbox는 포함된 azcopy를 사용하여 Azure blob storage에 백업 파일을 전송하고 검색할 수 있습니다.

Azure blob storage를 사용하려면 기존 리소스 그룹에 저장소 계정을 생성해야 합니다. 저장소 계정의 이름, 액세스 키 및 blob 호스트를 포함하는 구성 비밀을 생성합니다.

다음 매개변수를 포함하는 구성 파일을 만듭니다:

# azure-backup-conf.yaml
azure_storage_account_name: <storage account>
azure_storage_access_key: <access key value>
azure_storage_domain: blob.core.windows.net # 선택 사항

다음 kubectl 명령어를 사용하여 Kubernetes 비밀을 생성할 수 있습니다:

kubectl create secret generic backup-azure-creds \
  --from-file=config=azure-backup-conf.yaml

비밀이 생성되면 GitLab Helm 차트를 구성하여 배포된 값에 백업 설정을 추가하거나 Helm 명령줄에서 설정을 제공할 수 있습니다. 예를 들어:

helm install gitlab gitlab/gitlab \
  --set gitlab.toolbox.backups.objectStorage.config.secret=backup-azure-creds \
  --set gitlab.toolbox.backups.objectStorage.config.key=config \
  --set gitlab.toolbox.backups.objectStorage.backend=azure

비밀의 액세스 키는 저장소 계정에 액세스하기 위해 더 짧은 기간 동안 유효한 공유 액세스 서명(SAS) 토큰을 생성하고 갱신하는 데 사용됩니다.

또한, 백업을 저장하기 위한 하나와 백업 복원 시 사용할 임시 버킷을 위한 하나의 총 두 개의 버킷/컨테이너를 미리 생성해야 합니다. 버킷 이름을 값 또는 설정에 추가하세요. 예를 들면 다음과 같습니다:

--set global.appConfig.backups.bucket=gitlab-backup-storage
--set global.appConfig.backups.tmpBucket=gitlab-tmp-storage

문제 해결

Pod 종료 문제

백업이 객체 저장소 대상 외부에 로컬로 구성되므로 임시 디스크 공간이 필요합니다. 필요한 공간은 실제 백업 아카이브의 크기를 초과할 수 있습니다.

기본 구성은 Toolbox pod의 파일 시스템을 사용하여 임시 데이터를 저장합니다. 리소스 부족으로 인해 pod가 종료되는 경우, 임시 데이터를 저장하기 위해 pod에 영구 볼륨을 연결해야 합니다.

GKE에서는 Helm 명령에 다음 설정을 추가하세요:

--set gitlab.toolbox.persistence.enabled=true

백업이 포함된 백업 크론 작업의 일환으로 실행되는 경우, 크론 작업에도 지속성을 활성화해야 합니다:

--set gitlab.toolbox.backups.cron.persistence.enabled=true

다른 공급자에 대해서는 영구 볼륨을 생성해야 할 수도 있습니다. 이를 수행하는 방법에 대한 가능한 예는 저장소 문서를 참조하세요.

“Bucket not found” 오류

백업 중에 Bucket not found 오류가 발생하면,
버킷에 대한 자격 증명이 구성되어 있는지 확인하세요.

명령은 클라우드 서비스 공급자에 따라 다릅니다:

• AWS S3의 경우, 자격 증명은 toolbox pod의 ~/.s3cfg에 저장됩니다. 다음을 실행하세요:

  s3cmd ls
  

• GCP GCS의 경우, 다음을 실행하세요:

  gsutil ls
  

사용 가능한 버킷 목록이 표시되어야 합니다.

GCP에서 “AccessDeniedException: 403” 오류

[Error] AccessDeniedException: 403 <GCP Account> does not have storage.objects.list access to the Google Cloud Storage bucket.와 같은 오류는
GitLab 인스턴스의 백업 또는 복원 중에 발생하며, 권한 부족으로 인한 것입니다.

백업 및 복원 작업은 환경의 모든 버킷을 사용하므로
환경의 모든 버킷이 생성되었는지, GCP 계정이 모든 버킷에 접근(목록, 읽기 및 쓰기)할 수 있는지 확인하세요:

1. toolbox pod를 찾으세요:

   kubectl get pods -lrelease=RELEASE_NAME,app=toolbox
   

2. pod의 환경에 있는 모든 버킷을 가져옵니다. <toolbox-pod-name>을 실제 toolbox pod 이름으로 바꾸고 "BUCKET_NAME"은 그대로 두세요:

   kubectl describe pod <toolbox-pod-name> | grep "BUCKET_NAME"
   

3. 환경의 모든 버킷에 접근할 수 있는지 확인하세요:

   # 목록
   gsutil ls gs://<bucket-to-validate>/
   
   # 읽기
   gsutil cp gs://<bucket-to-validate>/<object-to-get> <save-to-location>
   
   # 쓰기
   gsutil cp -n <local-file> gs://<bucket-to-validate>/
   

“ERROR: /home/git/.s3cfg: None” 오류가 --backend s3로 backup-utility를 실행할 때 발생

이 오류는 .s3cfg 파일을 포함하는 Kubernetes 비밀이 gitlab.toolbox.backups.objectStorage.config.secret 값을 통해 지정되지 않았을 때 발생합니다.

이를 해결하려면 S3로 백업하기의 지침을 따르세요.

S3 사용 시 “PermissionError: File not writable” 오류

[Error] WARNING:<file> not writable: Operation not permitted와 같은 오류는 toolbox 사용자가
버킷 항목의 저장된 권한과 일치하는 파일을 쓸 수 있는 권한이 없을 때 발생합니다.

이를 방지하기 위해 s3cmd가 파일 소유자, 모드 및 타임스탬프를 보존하지 않도록 다음 플래그를
gitlab.toolbox.backups.objectStorage.config.secret를 통해 참조되는 .s3cfg 파일에 추가하세요.

preserve_attrs = False

복원 시 건너뛴 리포지토리

GitLab 16.6/Chart 7.6부터 백업 아카이브의 이름이 변경된 경우 복원 시 리포지토리가 건너뛰어질 수 있습니다.

이를 피하려면 백업 아카이브의 이름을 변경하지 말고 백업을 원래 이름({backup_id}_gitlab_backup.tar)으로 변경하세요.

원래의 백업 ID는 리포지토리 백업 디렉토리 구조에서 추출할 수 있습니다: repositories/@hashed/*/*/*/{backup_id}/LATEST