`gitlab-backup-cli`로 GitLab 백업 및 복원

요약

이 도구는 개발 중이며 궁극적으로 GitLab 백업 및 복원에 사용되는 Rake 태스크를 대체하기 위한 것입니다. 도구에 대한 피드백은 피드백 이슈에서 환영합니다. 현재 GitLab 설치의 백업을 수행하려면: Google Cloud만 지원됩니다.

히스토리

GitLab 17.0에서 도입되었습니다. 이 기능은 실험적이며 GitLab 테스팅 계약의 적용을 받습니다.

이 도구는 개발 중이며 궁극적으로 GitLab 백업 및 복원에 사용되는 Rake 태스크를 대체하기 위한 것입니다. 이 도구의 개발은 에픽에서 확인할 수 있습니다: 차세대 확장 가능한 백업 및 복원.

도구에 대한 피드백은 피드백 이슈에서 환영합니다.

백업 수행#

현재 GitLab 설치의 백업을 수행하려면:

sudo gitlab-backup-cli backup all

오브젝트 스토리지 백업#

Google Cloud만 지원됩니다. 더 많은 공급업체 추가 계획은 에픽 11577을 참조하세요.

GCP#

gitlab-backup-cli는 Google Cloud Storage Transfer Service를 사용하여 GitLab 데이터를 별도의 백업 버킷으로 복사하는 작업을 생성하고 실행합니다.

사전 요구 사항:

서비스 계정으로 인증하려면 서비스 계정 개요를 검토하세요.
이 문서에서는 백업 관리를 위해 전용 Google Cloud 서비스 계정을 설정하고 사용한다고 가정합니다.
다른 자격 증명이 제공되지 않고 Google Cloud 내에서 실행 중인 경우, 도구는 실행 중인 인프라의 액세스를 사용하려고 시도합니다. 보안상의 이유로, 별도의 자격 증명으로 도구를 실행하고 애플리케이션에서 생성된 백업에 대한 액세스를 제한해야 합니다.

백업을 생성하려면:

역할 생성:

다음 정의로 role.yaml 파일을 생성합니다:

---
description: Role for backing up GitLab object storage
includedPermissions:
   - storagetransfer.jobs.create
   - storagetransfer.jobs.get
   - storagetransfer.jobs.run
   - storagetransfer.jobs.update
   - storagetransfer.operations.get
   - storagetransfer.projects.getServiceAccount
stage: GA
title: GitLab Backup Role

역할 적용:

gcloud iam roles create --project=  --file=role.yaml

백업용 서비스 계정을 생성하고 역할에 추가합니다:

gcloud iam service-accounts create "gitlab-backup-cli" --display-name="GitLab Backup Service Account"
# 다음 명령의 출력에서 서비스 계정 이메일 가져오기
gcloud iam service-accounts list
# 이전에 생성된 역할에 계정 추가
gcloud projects add-iam-policy-binding  --member="serviceAccount:" --role="roles/"

서비스 계정으로 인증하려면 서비스 계정 자격 증명을 참조하세요. 자격 증명은 파일에 저장하거나 미리 정의된 환경 변수에 저장할 수 있습니다.
Google Cloud Storage에서 백업할 대상 버킷을 생성합니다. 여기서 옵션은 요구 사항에 따라 크게 달라집니다.
백업 실행:
```
sudo gitlab-backup-cli backup all --backup-bucket=
```
컨테이너 레지스트리 버킷도 백업하려면 --registry-bucket= 옵션을 추가합니다.
백업은 버킷의 각 오브젝트 스토리지 유형에 대해 backups// 아래에 백업을 생성합니다.

백업 디렉터리 구조#

백업 디렉터리 구조 예시:

backups
└── 1714053314_2024_04_25_17.0.0-pre
    ├── artifacts.tar.gz
    ├── backup_information.json
    ├── builds.tar.gz
    ├── ci_secure_files.tar.gz
    ├── db
    │   ├── ci_database.sql.gz
    │   └── database.sql.gz
    ├── lfs.tar.gz
    ├── packages.tar.gz
    ├── pages.tar.gz
    ├── registry.tar.gz
    ├── repositories
    │   ├── default
    │   │   ├── @hashed
    │   │   └── @snippets
    │   └── manifests
    │       └── default
    ├── terraform_state.tar.gz
    └── uploads.tar.gz

db 디렉터리는 pg_dump를 사용하여 GitLab PostgreSQL 데이터베이스를 백업하는 데 사용되며 SQL 덤프를 생성합니다. pg_dump의 출력은 압축된 SQL 파일을 생성하기 위해 gzip을 통해 파이프됩니다.

repositories 디렉터리는 GitLab 데이터베이스에서 찾은 Git 리포지터리를 백업하는 데 사용됩니다.

백업 ID#

백업 ID는 개별 백업을 식별합니다. 여러 백업을 사용할 수 있는 경우 GitLab을 복원해야 할 때 백업 아카이브의 백업 ID가 필요합니다.

백업은 config/gitlab.yml 파일에 지정된 backup_path에 설정된 디렉터리에 저장됩니다.

기본적으로 백업은 /var/opt/gitlab/backups에 저장됩니다.
기본적으로 백업 디렉터리는 backup_id의 이름을 따르며 여기서 <backup-id>는 백업이 생성된 시간과 GitLab 버전을 식별합니다.

예를 들어, 백업 디렉터리 이름이 1714053314_2024_04_25_17.0.0-pre이면 생성 시간은 1714053314_2024_04_25로 표시되고 GitLab 버전은 17.0.0-pre입니다.

백업 메타데이터 파일 (`backup_information.json`)#

히스토리

메타데이터 버전 2는 GitLab 16.11에서 도입되었습니다.

backup_information.json은 백업 디렉터리에서 찾을 수 있으며 백업에 대한 메타데이터를 저장합니다. 예를 들면:

{
  "metadata_version": 2,
  "backup_id": "1714053314_2024_04_25_17.0.0-pre",
  "created_at": "2024-04-25T13:55:14Z",
  "gitlab_version": "17.0.0-pre"
}

백업 복원#

히스토리

GitLab 17.6에서 도입되었습니다.

사전 요구 사항:

gitlab-backup-cli를 사용하여 생성된 백업의 백업 ID가 있어야 합니다.

현재 GitLab 설치의 백업을 복원하려면:

다음 명령을 실행합니다:

sudo gitlab-backup-cli restore all <backup_id>

오브젝트 스토리지 데이터 복원#

Google Cloud Storage에서 데이터를 복원할 수 있습니다. 에픽 11577에서 다른 공급업체 지원 추가를 제안하고 있습니다.

사전 요구 사항:

gitlab-backup-cli를 사용하여 생성된 백업의 백업 ID가 있어야 합니다.
복원 위치에 필요한 권한을 구성했습니다.
gitlab.rb 또는 gitlab.yml 파일에서 오브젝트 스토리지 구성을 설정하였으며 백업 환경과 일치합니다.
스테이징 환경에서 복원 프로세스를 테스트했습니다.

오브젝트 스토리지 데이터를 복원하려면:

다음 명령을 실행합니다:
```
sudo gitlab-backup restore <backup_id>
```

복원 프로세스:

대상 버킷을 먼저 비우지 않습니다.
대상 버킷에서 동일한 파일 이름을 가진 기존 파일을 덮어씁니다.
복원되는 데이터의 양에 따라 상당한 시간이 걸릴 수 있습니다.

복원 중에 항상 시스템 리소스를 모니터링하세요. 복원이 성공적으로 완료되었는지 확인할 때까지 원본 파일을 유지하세요.

알려진 문제#

gitlab-backup-cli로 작업할 때 다음 문제가 발생할 수 있습니다.

아키텍처 호환성#

1K 아키텍처 이외의 아키텍처에서 gitlab-backup-cli 도구를 사용하면 문제가 발생할 수 있습니다. 이 도구는 1K 아키텍처에서만 지원되며 관련 환경에만 권장됩니다.

백업 전략#

백업 중 기존 파일의 변경은 GitLab 인스턴스에서 문제를 일으킬 수 있습니다. 이 문제는 도구의 초기 버전이 복사 전략을 사용하지 않기 때문에 발생합니다.

이 문제의 해결 방법은 다음 중 하나입니다:

GitLab 인스턴스를 유지보수 모드로 전환합니다.
백업 중 인스턴스 리소스를 보존하기 위해 서버에 대한 트래픽을 제한합니다.

복사 전략의 대안을 조사 중입니다. 이슈 428520을 참조하세요.

백업되는 데이터는?#

Git 리포지터리 데이터
데이터베이스
블롭

백업되지 않는 데이터는?#

시크릿 및 구성
- 시크릿 및 구성 백업 방법에 대한 문서를 따르세요.
임시 및 캐시 데이터
- Redis: 캐시
- Redis: Sidekiq 데이터
- 로그
- Elasticsearch
- 관측 데이터 / Prometheus 메트릭

보안 고려 사항#

동일한 자격 증명을 사용하는 대신, 백업 수행에 필요한 권한만 가진 별도의 사용자 계정을 생성해야 합니다. 애플리케이션과 동일한 자격 증명으로 백업을 실행하는 것은 여러 이유로 좋지 않은 보안 관행입니다:

최소 권한의 원칙 - 백업 프로세스는 일반 애플리케이션 운영에서 필요한 것보다 더 광범위한 권한(모든 데이터에 대한 읽기 액세스 등)이 필요합니다. 사용자 또는 프로세스는 해당 기능을 수행하는 데 필요한 최소한의 액세스만 가져야 합니다.
침해 위험 - 애플리케이션 자격 증명이 침해된 경우, 공격자는 애플리케이션과 모든 백업 데이터에 액세스하여 과거 데이터도 노출시킬 수 있습니다.
직무 분리 - 백업 및 애플리케이션에 별도의 자격 증명을 사용하면 직무 분리를 유지하는 데 도움이 됩니다. 이 분리는 단일 침해된 계정이 광범위한 피해를 입히기 어렵게 만듭니다.
감사 추적 - 백업을 위한 별도의 자격 증명은 일반 애플리케이션 운영과 독립적으로 백업 활동을 추적하고 감사하는 것을 더 쉽게 만듭니다.
세분화된 액세스 제어 - 다른 자격 증명은 보다 세분화된 액세스 제어를 허용합니다. 백업 자격 증명은 데이터에 대한 읽기 전용 액세스를 부여할 수 있지만, 애플리케이션 자격 증명은 특정 테이블이나 스키마에 대한 읽기-쓰기 액세스가 필요할 수 있습니다.
규정 준수 요구 사항 - 많은 규제 표준 및 규정 준수 프레임워크(GDPR, HIPAA, PCI-DSS 등)는 별도의 자격 증명으로 더 쉽게 달성할 수 있는 직무 분리와 액세스 제어를 요구하거나 강력히 권장합니다.
라이프사이클 관리 용이성 - 애플리케이션과 백업 프로세스는 서로 다른 라이프사이클을 가질 수 있습니다. 별도의 자격 증명을 사용하면 이러한 라이프사이클을 독립적으로 관리하기가 더 쉽습니다. 예를 들어, 다른 프로세스에 영향을 주지 않고 자격 증명을 교체하거나 취소할 수 있습니다.
애플리케이션 취약점으로부터 보호 - 애플리케이션에 SQL 인젝션이나 다른 형태의 무단 데이터 액세스를 허용하는 취약점이 있는 경우, 별도의 백업 자격 증명을 사용하면 백업 프로세스에 대한 추가적인 보호 계층이 추가됩니다.

`gitlab-backup-cli`로 GitLab 백업 및 복원

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

히스토리

GitLab 17.0에서 도입되었습니다. 이 기능은 실험적이며 GitLab 테스팅 계약의 적용을 받습니다.

도구에 대한 피드백은 피드백 이슈에서 환영합니다.

백업 수행#

현재 GitLab 설치의 백업을 수행하려면:

sudo gitlab-backup-cli backup all

오브젝트 스토리지 백업#

Google Cloud만 지원됩니다. 더 많은 공급업체 추가 계획은 에픽 11577을 참조하세요.

GCP#

gitlab-backup-cli는 Google Cloud Storage Transfer Service를 사용하여 GitLab 데이터를 별도의 백업 버킷으로 복사하는 작업을 생성하고 실행합니다.

사전 요구 사항:

서비스 계정으로 인증하려면 서비스 계정 개요를 검토하세요.
이 문서에서는 백업 관리를 위해 전용 Google Cloud 서비스 계정을 설정하고 사용한다고 가정합니다.
다른 자격 증명이 제공되지 않고 Google Cloud 내에서 실행 중인 경우, 도구는 실행 중인 인프라의 액세스를 사용하려고 시도합니다. 보안상의 이유로, 별도의 자격 증명으로 도구를 실행하고 애플리케이션에서 생성된 백업에 대한 액세스를 제한해야 합니다.

백업을 생성하려면:

역할 생성:

다음 정의로 role.yaml 파일을 생성합니다:

---
description: Role for backing up GitLab object storage
includedPermissions:
   - storagetransfer.jobs.create
   - storagetransfer.jobs.get
   - storagetransfer.jobs.run
   - storagetransfer.jobs.update
   - storagetransfer.operations.get
   - storagetransfer.projects.getServiceAccount
stage: GA
title: GitLab Backup Role

역할 적용:

gcloud iam roles create --project=  --file=role.yaml

백업용 서비스 계정을 생성하고 역할에 추가합니다:

gcloud iam service-accounts create "gitlab-backup-cli" --display-name="GitLab Backup Service Account"
# 다음 명령의 출력에서 서비스 계정 이메일 가져오기
gcloud iam service-accounts list
# 이전에 생성된 역할에 계정 추가
gcloud projects add-iam-policy-binding  --member="serviceAccount:" --role="roles/"

서비스 계정으로 인증하려면 서비스 계정 자격 증명을 참조하세요. 자격 증명은 파일에 저장하거나 미리 정의된 환경 변수에 저장할 수 있습니다.
Google Cloud Storage에서 백업할 대상 버킷을 생성합니다. 여기서 옵션은 요구 사항에 따라 크게 달라집니다.
백업 실행:
```
sudo gitlab-backup-cli backup all --backup-bucket=
```
컨테이너 레지스트리 버킷도 백업하려면 --registry-bucket= 옵션을 추가합니다.
백업은 버킷의 각 오브젝트 스토리지 유형에 대해 backups// 아래에 백업을 생성합니다.

백업 디렉터리 구조#

백업 디렉터리 구조 예시:

backups
└── 1714053314_2024_04_25_17.0.0-pre
    ├── artifacts.tar.gz
    ├── backup_information.json
    ├── builds.tar.gz
    ├── ci_secure_files.tar.gz
    ├── db
    │   ├── ci_database.sql.gz
    │   └── database.sql.gz
    ├── lfs.tar.gz
    ├── packages.tar.gz
    ├── pages.tar.gz
    ├── registry.tar.gz
    ├── repositories
    │   ├── default
    │   │   ├── @hashed
    │   │   └── @snippets
    │   └── manifests
    │       └── default
    ├── terraform_state.tar.gz
    └── uploads.tar.gz

repositories 디렉터리는 GitLab 데이터베이스에서 찾은 Git 리포지터리를 백업하는 데 사용됩니다.

백업 ID#

백업 ID는 개별 백업을 식별합니다. 여러 백업을 사용할 수 있는 경우 GitLab을 복원해야 할 때 백업 아카이브의 백업 ID가 필요합니다.

백업은 config/gitlab.yml 파일에 지정된 backup_path에 설정된 디렉터리에 저장됩니다.

기본적으로 백업은 /var/opt/gitlab/backups에 저장됩니다.
기본적으로 백업 디렉터리는 backup_id의 이름을 따르며 여기서 <backup-id>는 백업이 생성된 시간과 GitLab 버전을 식별합니다.

예를 들어, 백업 디렉터리 이름이 1714053314_2024_04_25_17.0.0-pre이면 생성 시간은 1714053314_2024_04_25로 표시되고 GitLab 버전은 17.0.0-pre입니다.

백업 메타데이터 파일 (`backup_information.json`)#

히스토리

메타데이터 버전 2는 GitLab 16.11에서 도입되었습니다.

backup_information.json은 백업 디렉터리에서 찾을 수 있으며 백업에 대한 메타데이터를 저장합니다. 예를 들면:

{
  "metadata_version": 2,
  "backup_id": "1714053314_2024_04_25_17.0.0-pre",
  "created_at": "2024-04-25T13:55:14Z",
  "gitlab_version": "17.0.0-pre"
}

백업 복원#

히스토리

GitLab 17.6에서 도입되었습니다.

사전 요구 사항:

gitlab-backup-cli를 사용하여 생성된 백업의 백업 ID가 있어야 합니다.

현재 GitLab 설치의 백업을 복원하려면:

다음 명령을 실행합니다:

sudo gitlab-backup-cli restore all <backup_id>

오브젝트 스토리지 데이터 복원#

Google Cloud Storage에서 데이터를 복원할 수 있습니다. 에픽 11577에서 다른 공급업체 지원 추가를 제안하고 있습니다.

사전 요구 사항:

gitlab-backup-cli를 사용하여 생성된 백업의 백업 ID가 있어야 합니다.
복원 위치에 필요한 권한을 구성했습니다.
gitlab.rb 또는 gitlab.yml 파일에서 오브젝트 스토리지 구성을 설정하였으며 백업 환경과 일치합니다.
스테이징 환경에서 복원 프로세스를 테스트했습니다.

오브젝트 스토리지 데이터를 복원하려면:

다음 명령을 실행합니다:
```
sudo gitlab-backup restore <backup_id>
```

복원 프로세스:

대상 버킷을 먼저 비우지 않습니다.
대상 버킷에서 동일한 파일 이름을 가진 기존 파일을 덮어씁니다.
복원되는 데이터의 양에 따라 상당한 시간이 걸릴 수 있습니다.

복원 중에 항상 시스템 리소스를 모니터링하세요. 복원이 성공적으로 완료되었는지 확인할 때까지 원본 파일을 유지하세요.

알려진 문제#

gitlab-backup-cli로 작업할 때 다음 문제가 발생할 수 있습니다.

아키텍처 호환성#

백업 전략#

이 문제의 해결 방법은 다음 중 하나입니다:

GitLab 인스턴스를 유지보수 모드로 전환합니다.
백업 중 인스턴스 리소스를 보존하기 위해 서버에 대한 트래픽을 제한합니다.

복사 전략의 대안을 조사 중입니다. 이슈 428520을 참조하세요.

백업되는 데이터는?#

Git 리포지터리 데이터
데이터베이스
블롭

백업되지 않는 데이터는?#

시크릿 및 구성
- 시크릿 및 구성 백업 방법에 대한 문서를 따르세요.
임시 및 캐시 데이터
- Redis: 캐시
- Redis: Sidekiq 데이터
- 로그
- Elasticsearch
- 관측 데이터 / Prometheus 메트릭

보안 고려 사항#

최소 권한의 원칙 - 백업 프로세스는 일반 애플리케이션 운영에서 필요한 것보다 더 광범위한 권한(모든 데이터에 대한 읽기 액세스 등)이 필요합니다. 사용자 또는 프로세스는 해당 기능을 수행하는 데 필요한 최소한의 액세스만 가져야 합니다.
침해 위험 - 애플리케이션 자격 증명이 침해된 경우, 공격자는 애플리케이션과 모든 백업 데이터에 액세스하여 과거 데이터도 노출시킬 수 있습니다.
직무 분리 - 백업 및 애플리케이션에 별도의 자격 증명을 사용하면 직무 분리를 유지하는 데 도움이 됩니다. 이 분리는 단일 침해된 계정이 광범위한 피해를 입히기 어렵게 만듭니다.
감사 추적 - 백업을 위한 별도의 자격 증명은 일반 애플리케이션 운영과 독립적으로 백업 활동을 추적하고 감사하는 것을 더 쉽게 만듭니다.
세분화된 액세스 제어 - 다른 자격 증명은 보다 세분화된 액세스 제어를 허용합니다. 백업 자격 증명은 데이터에 대한 읽기 전용 액세스를 부여할 수 있지만, 애플리케이션 자격 증명은 특정 테이블이나 스키마에 대한 읽기-쓰기 액세스가 필요할 수 있습니다.
규정 준수 요구 사항 - 많은 규제 표준 및 규정 준수 프레임워크(GDPR, HIPAA, PCI-DSS 등)는 별도의 자격 증명으로 더 쉽게 달성할 수 있는 직무 분리와 액세스 제어를 요구하거나 강력히 권장합니다.
라이프사이클 관리 용이성 - 애플리케이션과 백업 프로세스는 서로 다른 라이프사이클을 가질 수 있습니다. 별도의 자격 증명을 사용하면 이러한 라이프사이클을 독립적으로 관리하기가 더 쉽습니다. 예를 들어, 다른 프로세스에 영향을 주지 않고 자격 증명을 교체하거나 취소할 수 있습니다.
애플리케이션 취약점으로부터 보호 - 애플리케이션에 SQL 인젝션이나 다른 형태의 무단 데이터 액세스를 허용하는 취약점이 있는 경우, 별도의 백업 자격 증명을 사용하면 백업 프로세스에 대한 추가적인 보호 계층이 추가됩니다.

`gitlab-backup-cli`로 GitLab 백업 및 복원

백업 수행#

오브젝트 스토리지 백업#

GCP#

백업 디렉터리 구조#

백업 ID#

백업 메타데이터 파일 (backup_information.json)#

백업 복원#

오브젝트 스토리지 데이터 복원#

알려진 문제#

아키텍처 호환성#

백업 전략#

백업되는 데이터는?#

백업되지 않는 데이터는?#

보안 고려 사항#

백업 수행#

오브젝트 스토리지 백업#

GCP#

백업 디렉터리 구조#

백업 ID#

백업 메타데이터 파일 (backup_information.json)#

백업 복원#

오브젝트 스토리지 데이터 복원#

알려진 문제#

아키텍처 호환성#

백업 전략#

백업되는 데이터는?#

백업되지 않는 데이터는?#

보안 고려 사항#

백업 메타데이터 파일 (`backup_information.json`)#

백업 메타데이터 파일 (`backup_information.json`)#