GitHub Actions の外部ストレージの移行

外部ストレージ GitHub Actions 移行について

クラウドアカウントの統合、常駐要件の満たす場合、またはストレージテナントの再構成を行うときに、外部ストレージ GitHub Actions 同じプロバイダー上の新しいバケット、アカウント、またはリージョンに移行できます。

GitHub Actionsは、バケットまたはアカウント名ではなく、バケットまたはコンテナー内のキー (パス) によって格納されているオブジェクトを識別するため、移行が機能します。内部キーレイアウトを保持し、新しい場所を指すように構成を更新する限り、既存のワークフローログと成果物は中断することなくアクセスできます。

Considerations

開始する前に、次の制約を確認します。それぞれが移行アプローチを形作り、無視された場合にデータ損失を引き起こす可能性があります。

同じプロバイダーのみ。 この手順では、同じ種類のストレージプロバイダー内での移行をサポートします。たとえば、Amazon S3 から Amazon S3、Azure Blob から Azure Blob、Google Cloud Storage から Google Cloud Storage、または MinIO から MinIO への移行です。クロスプロバイダー移行については、ここでは説明しません。クロスプロバイダー移行については、 GitHub Enterprise サポートにお問い合わせください。
移行中に認証方法を変更しないでください。 現在、資格情報ベースの認証を使用している場合は、移行先の構成でも資格情報ベースの認証を使用する必要があります。 OpenID Connect にも同じことが当てはまります。ストレージ構成の変更中に認証方法を切り替えると、データが失われる可能性があります。詳細については、「GitHub Actions ストレージの資格情報の更新」を参照してください。認証方法を変更するには、最初にストレージの移行を完了してから、別の変更を計画します。
バケットまたはコンテナー内のキーレイアウトは保持する必要があります。 ソースバケットまたはコンテナー内のオブジェクトキー (パス) は、コピー先で同じままにする必要があります。宛先バケット名、ストレージアカウント、リージョン、およびその他の��続パラメーターが変更される可能性があります。これらは、カットオーバー時に [Management Console] で更新します。ほとんどのネイティブプロバイダーコピーツールでは、バケットまたはコンテナー全体をコピーするときにキーレイアウトが自動的に保持されますが、コピー先がソースと一致することをカットオーバーする前に確認してください。
GitHub Packages には追加の制約があります。 GitHub Packagesも使用する場合は、開始する前に、以下の「GitHub Packagesに関する考慮事項」セクションを参照してください。

前提条件

お使いの GitHub Enterprise Server インスタンスへのサイト管理者アクセス権があります。
目的のアカウント、リージョン、またはテナントで、移行元と同じプロバイダーに移行先ストレージをプロビジョニングしました。
宛先が空です。
宛先は、ソースと同じアクセス許可お使いの GitHub Enterprise Server インスタンス付与します。必要なアクセス許可については、関連する構成記事を参照してください。
すべてのソースオブジェクトを読み取り、宛先に書き込むのに十分な、ソースストレージと移行先ストレージの両方の管理者資格情報があります。
お使いの GitHub Enterprise Server インスタンスの最近のバックアップがあります。詳細については、「バックアップユーティリティを使用したインスタンスでのバックアップの構成」を参照してください。
ステージング環境で移行をリハーサルしました。次のセクションを参照してください。

運用環境に対して移行を実行する前に、ステージングインスタンスで完全な手順をリハーサルします。最近の運用バックアップからステージング GitHub Enterprise Server インスタンスをプロビジョニングし、目的の運用先をミラー化する使い捨て先にポイントし、この記事のすべての手順をエンドツーエンドで実行します。詳細については、「ステージングインスタンスのセットアップ」および「ステージング環境を使用する」を参照してください。

ステージングリハーサルでは、次のことが検証されます。

宛先のプロバイダー側のアクセス許可、ネットワークアクセス、およびポリシーは正しいです。
選択したコピーツールは、代表的なデータボリュームに対して正常に完了します。
予想されるオブジェクト数と合計サイズは、ソースと宛先の間で一致します。
既存のワークフロー実行ログと成果物は、カットオーバー後に UI を介して取得できます。

警告

ステージングインスタンスでは、実稼働インスタンスとは異なるストレージを使用する必要があります。ストレージ構成を変更しないと、ステージングインスタンスが実稼働ストレージに書き込み、データが失われる可能性があります。詳細については、「ステージング環境を使用する」を参照してください。

移行の実行

次の手順を順番に実行します。 GitHub Actions は、メンテナンスモードを有効にするまでトラフィックの提供を続行できます。

初期データコピーを実行します。 プロバイダーネイティブツールを使用して、ソースからコピー先にすべてのオブジェクトをコピーします。コピー中にソースに書き込まれた新しいオブジェクトは、カットオーバー後の最終的な差分同期によってキャプチャされます。

サンプルコマンドを開始点として使用します。資格情報、暗号化、スループットのチューニングなど、オプションの完全なセットについては、アップストリームのドキュメントを参照してください。

Amazon S3は、AWS コマンドラインインターフェイスからaws s3 syncを使用します。最初にドライランを実行して操作を検証し、次にコピーを実行します。

aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET --dryrun
aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET

Azure Blob Storageの場合は、ソースの共有アクセス署名でazcopy copyを使用します。

azcopy copy 'https://SOURCE-STORAGE-ACCOUNT-NAME.blob.core.windows.net/CONTAINER?SAS-TOKEN' 'https://DESTINATION-STORAGE-ACCOUNT-NAME.blob.core.windows.net/CONTAINER' --recursive

Google Cloud Storageは、Google Cloud コマンドラインインターフェイスからgcloud storage rsyncを使用します。

gcloud storage rsync --recursive gs://SOURCE-BUCKET gs://DESTINATION-BUCKET

MinIOは、MinIO クライアントからmc mirrorを使用します。

mc mirror SOURCE-ALIAS/SOURCE-BUCKET DESTINATION-ALIAS/DESTINATION-BUCKET

コピーが完了したら、プロバイダーの標準登録情報ツールを使用して、コピー先のオブジェクト数と合計サイズを確認します。続行する前に、不一致を調査します。

メンテナンスモードを有効にします。 カットオーバー中に新しいオブジェクトがソースに書き込まれないようにするには、お使いの GitHub Enterprise Server インスタンスでメンテナンスモードを有効にします。これにより、エンドユーザーのインスタンスが簡単にオフラインになります。詳細については、「メンテナンスモードの有効化とスケジューリング」を参照してください。
最終的な差分同期を実行します。 メンテナンスモードを有効にした場合は、最初のコピー手順から同じコピーコマンドをもう一度実行します。これにより、最初のコピーの開始後にソースに書き込まれたオブジェクトがキャプチャされます。

たとえば、Amazon S3:
```
aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET
```
ストレージ構成を更新します。 新しいストレージの場所をポイントするようにお使いの GitHub Enterprise Server インスタンスを更新します。以前と同じ認証方法を使用してください。
1. [Management Console] にサインインします。詳細については、「管理コンソールへのアクセス」を参照してください。
2. 「設定」サイドバーで、「 アクション」をクリックします。
3. 「Artifact & Log Storage」の下で、たとえばバケット名、アカウント名、リージョン、��ール ARN、接続文字列など、保存場所を識別するフィールドを更新します。認証方法は変更しないでください。
4. [ ストレージ設定のテスト ] をクリックして、新しい構成を検証します。
  
  警告
  
  テストが失敗した場合は、設定を保存しないでください。失敗を調査し、続行する前に再テストします。無効なストレージ構成を保存すると、停止が発生する可能性があります。
5. [ 設定の保存] をクリックし、サービスが完全に再起動するまで待ちます。
または、資格情報ベースの認証に ghe-actions-precheck を使用して、コマンドラインから構成を更新することもできます。詳細については、「コマンドラインユーティリティ」を参照してください。
移行を検証します。 構成を変更した後、 GitHub Actions が新しいストレージの場所から読み取ることができることを確認します。
1. メンテナンスモードを無効にします。詳細については、「メンテナンスモードの有効化とスケジューリング」を参照してください。
2. お使いの GitHub Enterprise Server インスタンスの Web UI で、移行前に完了した最近のワークフロー実行を開きます。次の点を確認します。
  - ワークフロー実行ログの読み込み。
  - ビルド成果物は正常にダウンロードされます。
3. 新しいワークフロー実行をトリガーし、次の点を確認します。
  - 実行は正常に完了します。
  - 実行によって生成されたログと成果物が表示されます。
これらの検証チェックのいずれかが失敗した場合は、ソースストレージを保持し、後述の「ロールバック」セクションを参照してください。
ソースストレージの使用を停止します。 検証が正常に完了し、新しいストレージの場所が正常であることを確信するのに十分な時間を許可した後にのみ続行します。ガイドラインとして、ソースストレージを削除する前に、少なくとも 1 回の完全バックアップサイクルの読み取り専用状態を維持します。

ソースストレージを削除する準備ができたら、バケットまたはコンテナーを削除するためのプロバイダーの標準手順に従います。

ロールバック

検証に失敗した場合、またはカットオーバー後に問題が発生した場合は、お使いの GitHub Enterprise Server インスタンスをソースストレージの場所に戻してロールバックしてください。ソースストレージは、正常動作が確認済みの複製です。ロールバックの一環として、宛先からソースへデータをコピーして戻さないでください。切り替えが失敗した際に宛先に書き込まれたデータは、不完全または不整合である可能性があり、それをソースに書き戻すと、唯一の正常なコピーを破損するおそれがあるためです。

警告

ロールバックすると、カットオーバー後に書き込まれたデータまたは削除されたデータが破棄されます。検証に失敗した場合は、拡張トラブルシューティングを試みるのではなく、すぐにロールバックしてください。待つ時間が長いほど、より多くのデータが危険にさらされます。

検証に失敗した場合、または問題が発生した場合:

メンテナンスモードをすぐに有効にします。
[Management Console]で、元のストレージ構成値を復元し、[ストレージ設定のテスト]、[設定の保存] の順にクリックします。
メンテナンスモードを無効にし、元のストレージで検証手順を再実行します。

ロールバックが成功したら、失敗を調査し、新しい移行の試行を計画します。

GitHub Packages の考慮事項

同じ移行アプローチを外部ストレージ GitHub Packages 適用できますが、次の重要な違いがあります。 GitHub Packages が有効になっているインスタンスでストレージを移行する前に、このセクション全体を読んでください。

GitHub Packagesでは OpenID Connect を使用できません。 GitHub Packages では、外部ストレージの資格情報ベースの認証のみがサポートされます。この記事の認証方法の制約は引き続き適用されます。移行中は認証方法を変更しません。
GitHub Packages は、タイミングの不一致の影響を受けやすくなります。 移行期間中にパッケージが発行されると、システムは新しいストレージオブジェクトとデータベースレコードの両方��作成します。不整合を防ぐため、最終差分同期の開始時から新しい構成の検証が正常に完了するまで、メンテナンスモードを有効のままにしてください。
同じプロバイダーが両方の製品を提供する場合は、両方の構成を一緒に更新します。 同じプロバイダーの種類を使用するように GitHub Actions と GitHub Packages を構成し、両方を移行する場合は、1 つのメンテナンス期間としてカットオーバーを計画し、メンテナンスモードを無効にする前に両方の構成を更新します。
GitHub Packages ストレージのクロスプロバイダー移行については、GitHub Enterprise サポートにお問い合わせください。 プロバイダー間の移動については、ここでは説明しません。

ストレージ GitHub Packages 構成の詳細については、エンタープライズ向けの GitHub パッケージの始め方を参照してください。

この機能を使用できるユーザーについて

この記事で