GitLab 인스턴스의 백업 및 복원
GitLab Helm 차트는 GitLab 인스턴스를 백업하고 복원하는 목적으로 동작하는 Toolbox 하위 차트의 유틸리티 pod을 제공합니다. backup-utility 실행 파일을 갖추고 있어 이 작업을 수행하기 위해 다른 필요한 pod과 상호 작용합니다.
유틸리티가 작동하는 기술적인 세부 정보는 아키텍처 문서에서 찾을 수 있습니다.
전제 조건
-
여기서 설명된 백업 및 복원 절차는 S3 호환 API에서만 테스트되었습니다. Google Cloud Storage와 같은 다른 객체 리포지터리 서비스 지원은 향후 개정에서 테스트될 예정입니다.
-
복원 중에 백업 타르볼을 디스크에 추출해야 합니다. 이는 Toolbox pod이 필요한 크기의 디스크를 사용할 수 있어야 함을 의미합니다.
-
이 차트는
artifacts,uploads,packages,registry및lfs객체에 대해 객체 리포지터리의 사용을 전제로 하며, 현재 이러한 객체를 복원 중에 마이그레이션하지 않습니다. 다른 인스턴스에서 백업을 복원하는 경우, 백업을 수행하기 전에 기존 인스턴스를 객체 리포지터리를 사용하도록 마이그레이션해야 합니다. 이슈 646을 참조하세요.
백업 및 복원 절차
객체 리포지터리
우리는 외부 객체 리포지터리가 지정되지 않은 한 이 차트 사용 시 기본적으로 MinIO 인스턴스를 제공합니다. Toolbox는 명시적 설정이 없는 경우 기본적으로 포함된 MinIO에 연결합니다. Toolbox는 Amazon S3 또는 Google Cloud Storage (GCS)로 백업하는 것으로 구성될 수도 있습니다.
S3로 백업
기본적으로 Toolbox는 객체 리포지터리에 연결할 때 s3cmd를 사용합니다. 다른 s3 도구를 사용하도록 지정하지 않은 경우에 외부 객체 리포지터리에 연결하는 방법을 구성하려면 gitlab.toolbox.backups.objectStorage.config.secret를 지정해야 합니다. 이는 .s3cfg 파일을 포함하는 쿠버네티스 시크릿을 가리킵니다. 다른 기본값 config인 gitlab.toolbox.backups.objectStorage.config.key도 지정해야 합니다.
다음과 같이 보여야 합니다:
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
백업 유틸리티에는 이러한 버킷에 대한 액세스가 필요합니다. 액세스를 부여하는 두 가지 방법이 있습니다:
- 쿠버네티스 시크릿에 자격 증명 지정.
- GKE용 Workload Identity Federation 구성.
GCS 자격 증명
먼저, gitlab.toolbox.backups.objectStorage.config.gcpProject를 사용하는 현재 저장 버킷을 포함하는 GCP 프로젝트의 프로젝트 ID로 설정해야 합니다.
백업에 사용할 리포지터리에 대해 storage.admin 역할을 갖는 서비스 계정이 포함된 유효한 서비스 계정 JSON 키의 내용으로 쿠버네티스 시크릿을 생성해야 합니다. 아래는 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 구성
GitLab 차트를 사용한 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 리포지터리로 백업
gitlab.toolbox.backups.objectStorage.backend를 azure로 설정하여 Azure blob 리포지터리를 사용하여 백업을 저장할 수 있습니다. 이렇게 하면 Toolbox가 백업 파일을 Azure blob 리포지터리에 전송하고 검색할 때 azcopy의 포함된 복사본을 사용합니다.
Azure blob 리포지터리를 사용하려면 기존 리소스 그룹에 리포지터리 계정을 만들어야 합니다. 리포지터리 계정의 이름, 액세스 키 및 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 오류가 표시되는 경우, 자격 증명이 버킷에 구성되어 있는지 확인하세요.
이 명령은 클라우드 서비스 공급업체에 따라 달라집니다:
-
AWS S3의 경우, 자격 증명은
~/.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 계정이 모든 버킷(디렉터리, 읽기 및 쓰기)에 액세스할 수 있는지 확인하세요:
-
Toolbox pod를 찾으세요:
kubectl get pods -lrelease=RELEASE_NAME,app=toolbox -
파드 환경의 모든 버킷을 가져옵니다.
<toolbox-pod-name>을 실제 Toolbox pod 이름으로 바꾸되, “BUCKET_NAME”은 그대로 둡니다:kubectl describe pod <toolbox-pod-name> | grep "BUCKET_NAME" -
환경의 모든 버킷에 액세스할 수 있는지 확인하세요:
# 디렉터리 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 파일을 포함한 Kubernetes 시크릿이 gitlab.toolbox.backups.objectStorage.config.secret 값을 통해 지정되지 않았을 때 발생합니다.
이 문제를 해결하려면 S3로 백업의 지침에 따르세요.
S3 사용 시 “PermissionError: File not writable” 오류
[Error] WARNING: <file> not writable: Operation not permitted와 같은 오류는 툴박스 사용자가 버킷 아이템의 저장된 권한과 일치하는 파일을 쓸 수 있는 권한이 없는 경우 발생합니다.
이를 방지하려면 s3cmd에서 파일 소유자, 모드 및 타임스탬프를 유지하지 않도록 .s3cfg 파일에 다음 플래그를 추가하세요. 이 플래그는 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
도움말