GitLabインスタンスのバックアップとリストア

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

GitLab Helmチャートは、GitLabインスタンスをバックアップおよびリストアする目的で、インターフェースとして機能するToolboxサブチャートからユーティリティポッドを提供します。このタスクに必要な他のポッドとやり取りするbackup-utility実行可能ファイルが搭載されています。ユーティリティの動作方法に関する技術的な詳細は、アーキテクチャドキュメントに記載されています。

前提要件

ここに記載されているバックアップとリストアの手順は、S3互換APIでのみテストされています。Google Cloud Storageなどの他のオブジェクトストレージサービスのサポートは、今後のリビジョンでテストされる予定です。
リストア中、バックアップtarballをディスクに展開する必要があります。つまり、Toolboxポッドには、必要なサイズのディスクが必要です。
このチャートは、artifacts、uploads、packages、registry、lfsオブジェクトにオブジェクトストレージを使用しており、リストア中にこれらを移行することはありません。別のインスタンスから取得したバックアップをリストアする場合は、バックアップを実行する前に、既存のインスタンスをオブジェクトストレージを使用するように移行する必要があります。issue 646を参照してください。

バックアップとリストアの手順

オブジェクトストレージ

外部オブジェクトストレージが指定されていない限り、このチャートを使用すると、すぐにMinIOインスタンスが提供されます。特定の設定が行われていない限り、Toolboxはデフォルトで含まれているMinIOに接続します。Toolboxは、Amazon S3またはGoogle Cloud Storage（GCS）にバックアップするように設定することもできます。

S3へのバックアップ

別のS3ツールを使用するように指定しない限り、Toolboxはデフォルトでs3cmdを使用してオブジェクトストレージに接続します。外部オブジェクトストレージへの接続を構成するには、gitlab.toolbox.backups.objectStorage.config.secretファイルを格納するKubernetesシークレットを指す.s3cfgを指定する必要があります。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 .

さらに、2つのバケットの場所を構成する必要があります。バックアップを格納するための場所と、バックアップのリストア時に使用される一時バケットです。

--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

バックアップユーティリティは、これらのバケットにアクセスする必要があります。アクセスを許可する方法は2つあります:

Kubernetesシークレットで認証情報を指定します。
GKEのワークロードID連携を構成します。

GCS認証情報

まず、gitlab.toolbox.backups.objectStorage.config.gcpProjectを、ストレージバケットを含むGCPプロジェクトのプロジェクトIDに設定します。

バックアップに使用するバケットのstorage.adminロールを持つサービスアカウントがアクティブなサービスアカウントJSONキーの内容を含むKubernetesシークレットを作成する必要があります。次に、シークレットを作成するために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のワークロードID連携の設定

GitLabチャートを使用したGKEのワークロードID連携に関するドキュメントを参照してください。

Kubernetes ServiceAccountを参照するIAM許可ポリシーを作成する場合は、roles/storage.objectAdminロールを付与します。

バックアップの場合、gitlab.toolbox.backups.objectStorage.config.secret、gitlab.toolbox.backups.objectStorage.config.key、gitlab.toolbox.backups.objectStorage.config.gcpProjectが設定されていないことを確認して、Googleのアプリケーションデフォルト認証情報が使用されていることを確認します。

Azure BLOBストレージへのバックアップ

gitlab.toolbox.backups.objectStorage.backendをazureに設定すると、Azure BLOBストレージにバックアップを格納するためにAzure BLOBストレージを使用できます。これにより、Toolboxは、含まれているazcopyのコピーを使用して、バックアップファイルをAzure BLOBストレージに送信および取得できます。

Azure BLOBストレージを使用するには、既存のリソースグループにストレージアカウントを作成する必要があります。ストレージアカウントの名前、アクセスキー、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 # optional

次のkubectlコマンドを使用して、Kubernetesシークレットを作成できます:

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

シークレットが作成されると、デプロイされた値にバックアップ設定を追加するか、Helmコマンドラインで設定を指定することにより、GitLab 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）トークンを生成および更新するために使用されます。

さらに、2つのバケット/コンテナを事前に作成する必要があります。バックアップを格納するためのコンテナと、バックアップのリストア時に使用される一時バケットです。値または設定にバケット名を追加します。例:

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

トラブルシューティング

ポッドの削除イシュー

バックアップはオブジェクトストレージターゲットの外部でローカルにアセンブルされるため、一時的なディスク容量が必要です。必要なスペースは、実際のバックアップアーカイブのサイズを超える可能性があります。デフォルトの設定では、Toolboxポッドのファイルシステムを使用して一時データを格納します。ポッドのリソース不足によりポッドが削除された場合は、一時データを保持するために永続ボリュームをポッドにアタッチする必要があります。GKEで、次の設定をHelmコマンドに追加します:

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

バックアップが、含まれているバックアップcronジョブの一部として実行されている場合は、cronジョブの永続性を有効にすることをお勧めします:

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

他のプロバイダーの場合は、永続ボリュームを作成する必要がある場合があります。これを行う方法の例については、ストレージドキュメントを参照してください。

「バケットが見つかりません」というエラー

バックアップ中にBucket not foundエラーが表示される場合は、バケットの認証情報が構成されていることを確認してください。

コマンドは、クラウドストレージサービスプロバイダーによって異なります:

AWS S3の場合、認証情報は~/.s3cfgのToolboxポッドに格納されます。以下を実行します:
```
s3cmd ls
```
GCP GCSの場合は、次を実行します:
```
gsutil ls
```

使用可能なバケットのリストが表示されます。

「AccessDeniedException: GCPでの403」エラー

通常、GitLabインスタンスのバックアップまたはリストア中に[Error] AccessDeniedException: 403 <GCP Account> does not have storage.objects.list access to the Google Cloud Storage bucket.のようなエラーが発生します。認証情報がないためです。

バックアップおよびリストア操作は環境内のすべてのバケットを使用するため、環境内のすべてのバケットが作成されていること、およびGCPアカウントがすべてのバケットにアクセス（リスト、読み取り、書き込み）できることを確認します:

Toolboxポッドを見つけます:

kubectl get pods -lrelease=RELEASE_NAME,app=toolbox

ポッドの環境内のすべてのバケットを取得します。<toolbox-pod-name>を実際のToolboxポッド名に置き換えますが、"BUCKET_NAME"はそのままにします:
```
kubectl describe pod <toolbox-pod-name> | grep "BUCKET_NAME"
```

環境内のすべてのバケットへのアクセス権があることを確認します:

# List
gsutil ls gs://<bucket-to-validate>/

# Read
gsutil cp gs://<bucket-to-validate>/<object-to-get> <save-to-location>

# Write
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へのバックアップの手順に従ってください。

「PermissionError: S3を使用した「ファイルが書き込み可能ではありません」というエラー

Toolboxユーザーが、バケットアイテムの格納されている権限と一致するファイルを書き込む権限を持っていない場合、[Error] WARNING: <file> not writable: Operation not permittedのようなエラーが発生します。

これを防ぐには、gitlab.toolbox.backups.objectStorage.config.secretを介して参照される.s3cfgファイルに次のフラグを追加して、ファイルオーナー、モード、タイムスタンプを保持しないようにs3cmdを構成します。

preserve_attrs = False

リストア時にスキップされたリポジトリ

GitLab 16.6/Chart 7.6以降では、バックアップアーカイブの名前が変更された場合、リストア時にリポジトリがスキップされる場合があります。これを回避するには、バックアップアーカイブの名前を変更せず、バックアップの名前を元の名前に変更します（{backup_id}_gitlab_backup.tar）。

元のバックアップIDは、リポジトリバックアップディレクトリ構造から抽出できます: repositories/@hashed/*/*/*/{backup_id}/LATEST