Set up AWS S3 storage for Git LFS
Add include here:
Bitbucket の既定の設定では、Git LFS オブジェクトは共有ホーム ファイルシステムに格納されます。ただし、Git LFS オブジェクトを AWS S3 に格納してそこから提供する機能もサポートされています。これにより、格納やリクエストの負荷を AWS S3 バケットにオフロードできるため、Bitbucket そのものに振り分けられる負荷を減らし、優れたスケーラビリティを実現することができます。
このドキュメントでは次の内容について説明します。
Git LFS オブジェクトを AWS S3 に格納するように Bitbucket を設定する
既存の Git LFS オブジェクトを共有ホーム ファイルシステムから AWS S3 に移行する
始める前に
S3 を LFS オブジェクトの格納先として使用する前に、次のことを知っておくことが重要です。
クライアントには AWS へのネットワーク接続が必要 -Bitbucket は署名済みの URL を Git LFS クライアントに提供し、Git LFS クライアントは AWS に直接 HTTP GET (ダウンロード) または PUT (アップロード) リクエストを行います。
AWS S3 には最大ファイル サイズの制限がある - Bitbucket には、使用可能なディスク容量によって示されるもの以外に、最大ファイル サイズの制限はありません。それに対し、AWS S3 には最大ファイル サイズの制限があります。続行する前に、これらを確認し、許容できるかどうかを確認してください。
S3 バケットのバックアップ方法を理解する必要がある - S3 に格納されている Git LFS オブジェクトをバックアップするには、既存のバックアップ方法を更新する必要があります。S3 バケットのバックアップ方法を理解して、バックアップ戦略に組み込んでください。ダウンタイムなしのバックアップがサポートされています (Git LFS オブジェクトは不変であり、アップロードはアトミックであることから堅牢です)。
Bitbucket ミラーは LFS オブジェクトの S3 への格納をサポートしていない - アップストリームで AWS S3 が Git LFS オブジェクトの格納先として設定されている間は、Bitbucket ミラーを使用できますが、ミラーは事実上 LFS オブジェクトのキャッシュ プロキシ サーバーとして機能します。つまり、Git LFS クライアントがミラーから LFS オブジェクトをダウンロードしようとすると、ミラーにすでに存在するオブジェクトのミラーから提供されます。それ以外の場合、ミラーからアップストリームへの問い合わせを経て、AWS S3 バケットから LFS オブジェクトをダウンロードするための URL が提供されます。その後、この URL から LFS オブジェクトがダウンロードされ、オブジェクトをリクエストしたクライアントとローカル ファイルシステムに同時にコンテンツがストリーミングされます。これにより、同じオブジェクトに対する次のクライアント リクエストに対しては直接提供されるようになります。
S3 バケットは Bitbucket 専用にする必要がある - キー名の競合を避けるため、下記のプロセスの一環として作成された S3 バケットは Bitbucket 専用にし、他のアプリのオブジェクトを格納しないようにしてください。
移行の概要
このセクションでは、Git LFS オブジェクトを AWS S3 に格納するように Bitbucket を設定するだけでなく、既存のオブジェクトを共有ホーム ファイルシステムから S3 に移行する方法についても説明します。LFS オブジェクトを AWS S3 に格納するように新しい Bitbucket インスタンスを設定する場合は、移行ツールを使用する必要はありません。移行ツールの機能はオブジェクトをコピーするだけであるためです。既存の Bitbucket インスタンスはあるものの、LFS オブジェクトが格納されていない場合も同様です。この場合のより簡単なプロセスについては、下記の FAQ セクションで詳しく説明しています。ただし、既存のオブジェクトを移行する必要がある場合は、このセクションを読み進めてください。
共有ホーム ファイルシステムに LFS オブジェクトを格納する組み込み LFS オブジェクト ストアから移行する場合は、次の手順が必要です。
移行前
S3 バケットをセットアップします。
Bitbucket Data Center Git LFS S3 ストア移行ツールを使用して初期同期を実行します。
移行
Bitbucket をシャットダウンします。
Bitbucket Data Center Git LFS S3 ストア移行ツールを使用して増分同期を実行します。
AWS S3 が Git LFS オブジェクトのホストに使用されるように Bitbucket の設定を更新します。
Bitbucket を起動します。
移行後
(オプション) 共有ホーム ファイルシステムから LFS オブジェクトを削除します。
移行前
この移行前フェーズでは、S3 バケットを作成し、Bitbucket の共有ホーム ディレクトリに格納されている Git LFS オブジェクトの初期コピーを実行する必要があります。格納されているオブジェクトの合計サイズによっては、この初期コピーには数分から数時間かかる場合があります。後で増分移行が実行されるため、最後の移行ステップのかなり前に実行してかまいません。
AWS の指示に従って
bitbucket-object-storeという名前の S3 バケットを作成します。S3 バケットで次の権限が付与された AWS ユーザーを作成します。
PutObject
GetObject
GetObjectAttributes
DeleteObject
ListBucket
ユーザーのアクセス キーを作成します。
S3 バケットでは、Bitbucket Data Center Git LFS S3 ストア移行ツールを使用して初期コピー/同期を実行できるようになりました。
https://github.com/atlassian-labs/bitbucket-s3-lfs-migration-tool/releases から移行ツールの最新バージョンをダウンロードします。
Bitbucket Data Center が稼働しているいずれかのノード上にそのファイルをコピーします。以下の例では、Bitbucket アプリを実行しているユーザーのホーム ディレクトリにコピーしたと仮定しています。
移行ツールの設定ファイルを作成します。以下の例では、設定ファイルは
config.propertiesという名前で、先ほどと同じく Bitbucket アプリを実行しているユーザーのホーム ディレクトリに作成したと仮定しています。ファイルは次のような内容になります。bitbucket.home=/var/atlassian/application-data/bitbucket s3.bucket=bitbucket-object-stores3.region=us-east-1 s3.access-key=<access key>
s3.secret-key=<access key>
プロパティが適切に設定されていることを確認します。詳細については、https://github.com/atlassian-labs/bitbucket-lfs-s3-migration-tool/blob/master/README.md を参照してください。
移行ツールを実行して最初のコピーを実施します。
java -jar ~/bitbucket-lfs-s3-migration-tool-1.0.0.jar ~/config.properties上記のコマンドを使用して、最初の同期と S3 への実際のカットオーバーの間に移行ツールを実行できます。これにより、最後の移行 (つまり、Bitbucket アプリを停止したときに実行される最後のインクリメンタル同期) の実行にかかる時間を短縮できます。
移行
Bitbucket をシャットダウンします。
最後のインクリメンタル同期を実行するため、Bitbucket インスタンスのすべてのノードをシャットダウンします。
最後の LFS オブジェクト同期を実行する
先ほどと同じ Bitbucket Data Center Git LFS S3 ストア移行ツールとその設定を使用して、同期を再度実行します。これにより、上記の「移行前」セクションで移行ツールの実行後にアップロードした LFS オブジェクトから LFS オブジェクトが移行されます。先ほどと同じ以下の設定とコマンドを使用して再度実行できます。
java -jar ~/bitbucket-lfs-s3-migration-tool-1.0.0.jar ~/config.properties
bitbucket.properties の設定を更新する
$BITBUCKET_HOME/shared/bitbucket.properties で次のプロパティを設定します。
bitbucket.filestoreplugin.bitbucket-filestore-s3.bucketplugin.bitbucket-filestore-s3.regionplugin.bitbucket-filestore-s3.access-keyplugin.bitbucket-filestore-s3.secret-key
上記のプロパティはすべて、設定プロパティ ドキュメントで説明されています。
bitbucket.properties での上記の設定例を次に示します。
# Configure Bitbucket to store LFS objects in AWS S3
bitbucket.filestore=s3
plugin.bitbucket-filestore-s3.bucket=bitbucket-object-store
plugin.bitbucket-filestore-s3.region=us-east-1
plugin.bitbucket-filestore-s3.access-key=<access key>
plugin.bitbucket-filestore-s3.secret-key=<access key>
Start Bitbucket
上記の同期が完了し、新しい設定を bitbucket.properties に追加したら、Bitbucket を再起動できます。
移行後
すべての LFS オブジェクトが S3 に移行され、Bitbucket がこれらのオブジェクトを正常に処理していることを確認したら、shared-home ファイルシステム内の LFS オブジェクトのストアを削除できます。移行が成功していることを確認してから数日後、場合によっては数週間後に行うことをお勧めします。まず、ストア ディレクトリの名前を変更して、それらのファイルが使用されていないことを確認するようお勧めします。たとえば、環境変数 $BITBUCKET_HOME が Bitbucket のホーム ディレクトリを指していると仮定した場合、コマンドは次のようになります。
cd $BITBUCKET_HOME/shared/data/git-lfs/storage
mv storage unused-storage
その後、しばらく待ってから実際に削除します。
cd $BITBUCKET_HOME/shared/data/git-lfs/storagerm -rf unused-storage
よくある質問
既存の LFS オブジェクトを移行する必要がない場合はどうすればいいですか?
LFS オブジェクトを AWS S3 に保存するよう新しい Bitbucket インスタンスを設定する場合、移行ツールを使用する必要はありません。移行ツールはオブジェクトをコピーする機能しか備えていないためです。Bitbucket インスタンスは存在しているが、LFS オブジェクトは保存されていないという場合も同様です。このように LFS オブジェクトが存在しない場合、$BITBUCKET_HOME/data/git-lfs/storage は空になります。
移行を省略できる場合、LFS オブジェクトを AWS S3 に保存するよう Bitbucket を設定するには、$BITBUCKET_HOME/shared/bitbucket.properties で次のプロパティを設定し、Bitbucket インスタンスを再起動して変更を有効にするだけです。
bitbucket.filestoreplugin.bitbucket-filestore-s3.bucketplugin.bitbucket-filestore-s3.regionplugin.bitbucket-filestore-s3.access-keyplugin.bitbucket-filestore-s3.secret-key
上記のプロパティはすべて、設定プロパティ ドキュメントで説明されています。
bitbucket.properties での上記の設定例を次に示します。
# Configure Bitbucket to store LFS objects in AWS S3bitbucket.filestore=s3plugin.bitbucket-filestore-s3.bucket=bitbucket-object-storeplugin.bitbucket-filestore-s3.region=us-east-1plugin.bitbucket-filestore-s3.access-key=<access key>plugin.bitbucket-filestore-s3.secret-key=<secret key>
Git LFS クライアントには、AWS への直接接続が必要ですか?
はい。Bitbucket が、LFS オブジェクトを AWS S3 に保存するように設定されている場合、Bitbucket は Git LFS クライアントにアップロード URL とダウンロード URL を提供します。その後、クライアントは HTTP 経由で S3 に直接アップロード/ダウンロードします。
現実的な例で考えてみましょう。Git LFS オブジェクトを取得する必要のあるクライアントは、Git LFS Batch API を介して Bitbucket にリクエストを行い、1 つ以上の Git LFS オブジェクトのダウンロード URL を要求します。Bitbucket は、署名済みのダウンロード URL のリストを返し、要求された特定のオブジェクトのダウンロードをクライアントに許可します (それ以外のことは許可しません)。その後、Git LFS クライアントは AWS S3 に HTTP GET リクエストを行ってオブジェクトをダウンロードします。
bitbucket.properties ファイルの AWS シークレットを保護するにはどうすればいいですか?
bitbucket.properties ファイルに対しては、読み取りアクセスを Bitbucket の実行ユーザーだけに制限する所有権と権限を常に設定しておく必要があります。また Bitbucket は bitbucket.propertes のシークレットの暗号化をサポートしています。詳細については、「Bitbucket の設定プロパティを保護する」を参照してください。