• 전제 조건
• 백업 및 복원 절차
• 객체 저장소
  • S3로의 백업
  • GCS로의 백업
    • GCS 자격 증명
    • GKE용 Workload Identity Federation 구성
  • Azure Blob Storage로의 백업
• 문제 해결
  • Pod 배치 제거 문제
  • “Bucket not found” 오류
  • GCP에서 “AccessDeniedException: 403” 오류
  • backup-utility를 --backend s3로 실행 시 “ERROR: /home/git/.s3cfg: None” 오류
  • S3 사용 시 “PermissionError: File not writable” 오류
  • 복원 시 저장소 스킵

GitLab 인스턴스의 백업 및 복원

GitLab Helm 차트는 GitLab 인스턴스의 백업 및 복원을 위한 인터페이스 역할을 하는 Toolbox 서브 차트의 유틸리티 파드를 제공합니다. 이는 이 작업을 위해 다른 필요한 파드들과 상호 작용하는 backup-utility 실행 파일을 갖추고 있습니다. 유틸리티가 작동하는 기술적인 세부 정보는 아키텍처 문서에서 찾을 수 있습니다.

전제 조건

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

• 복원 중에 백업 타볼은 디스크에 추출되어야 합니다. 이는 Toolbox 파드가 필요한 크기의 디스크가 사용 가능해야 함을 의미합니다.

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

백업 및 복원 절차

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

객체 저장소

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

S3로의 백업

Toolbox는 객체 저장소에 연결할 때 기본적으로 s3cmd를 사용합니다. 다른 s3 도구를 지정하려면 다른 s3 도구를 지정해야 합니다. 외부 객체 저장소에 대한 연결성을 구성하려면 gitlab.toolbox.backups.objectStorage.config.secret가 .s3cfg 파일을 포함하는 쿠버네티스 시크릿을 가리키도록 지정해야 합니다. gitlab.toolbox.backups.objectStorage.config.key는 config의 기본값과 다를 경우 지정해야 합니다. 이는 .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

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

백업 유틸리티는 이러한 버킷에 액세스해야 합니다. 액세스 권한을 부여할 수 있는 두 가지 방법이 있습니다:

• 쿠버네티스 시크릿에 자격 증명 지정.
• GKE용 Workload Identity Federation 구성.

GCS 자격 증명

먼저, gitlab.toolbox.backups.objectStorage.config.gcpProject를 사용하여 객체를 포함하는 GCP 프로젝트의 프로젝트 ID를 설정해야 합니다.

사용 중인 스토리지 버킷에 대해 storage.admin 역할을 가진 서비스 계정에 대한 활성 서비스 계정 JSON 키 내용을 담은 쿠버네티스 시크릿을 생성해야 합니다. 여기서 서비스 계정은 백업에 사용할 버킷의 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

다음과 같이 Helm 차트를 구성하여 서비스 계정 키를 사용하여 GCS에 인증합니다:

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용 Workload Identity Federation 구성

GKE를 위한 Workload Identity Federation을 사용하는 방법을 확인하세요.

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

백업의 경우 Google의 애플리케이션 기본 자격 증명을 사용해야 합니다. 이를 위해 gitlab.toolbox.backups.objectStorage.config.secret 및 gitlab.toolbox.backups.objectStorage.config.key가 설정되지 않았는지 확인해야 합니다.

Azure Blob Storage로의 백업

azure로 설정하여 Azure Blob Storage를 사용하여 백업을 저장할 수 있습니다. 이를 통해 Toolbox는 백업 파일을 전송하고 검색하기 위해 포함된 azcopy를 사용할 수 있습니다.

Azure Blob Storage를 사용하려면 기존 리소스 그룹에서 스토리지 계정을 생성해야 합니다. 스토리지 계정의 이름, 액세스 키 및 Blob 호스트로 구성 시크릿을 만들어야 합니다.

매개변수를 포함하는 구성 파일을 생성하세요:

# azure-backup-conf.yaml
azure_storage_account_name: <저장소 계정>
azure_storage_access_key: <액세스 키 값>
azure_storage_domain: blob.core.windows.net # 선택 사항

다음 kubectl 명령을 사용하여 쿠버네티스 시크릿을 생성할 수 있습니다:

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의 경우, 자격 증명은 ~/.s3cfg에 저장됩니다. 다음을 실행하세요:

  s3cmd ls
  

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

  gsutil ls
  

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

GCP에서 “AccessDeniedException: 403” 오류

[Error] AccessDeniedException: 403 <GCP Account>에 대한 오류가 보통 GitLab 인스턴스의 백업이나 복원 중에 발생합니다. 이는 권한이 부족하기 때문입니다.

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

1. Toolbox pod를 찾으세요:

   kubectl get pods -lrelease=RELEASE_NAME,app=toolbox
   

2. Pod 환경의 모든 버킷을 가져오세요. 실제 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>/
   

backup-utility를 --backend s3로 실행 시 “ERROR: /home/git/.s3cfg: None” 오류

이 오류는 .s3cfg 파일을 포함하는 쿠버네티스 시크릿이 gitlab.toolbox.backups.objectStorage.config.secret 값을 통해 지정되지 않았을 때 발생합니다.

해당하는 경우, S3로 백업 문서의 지침을 따르세요.

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

`[Error] WARNING: <file> not writable: Operation not permitted`와 같은 오류는 버킷 아이템의 저장된 권한과 일치하는 파일에 대한 쓰기 권한이 없는 경우 발생합니다.

이를 방지하려면 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