tigris-s3-migration

S3/GCS/Azure から Tigris への移行

ダウンタイムなしでオブジェクトストレージを Tigris に移行します。Tigris は S3 互換のため、ほとんどのアプリではエンドポイントと認証情報を変更するだけで済みます。シャドウバケットを使えば、事前にデータを移動せずに透過的に移行できます。

前提条件

ほかの作業を始める前に、まだ利用できない場合は Tigris CLI をインストールしてください。

tigris help || npm install -g @tigrisdata/cli

インストールが必要な場合は、ユーザーに「Tigris オブジェクトストレージを操作するため、Tigris CLI（@tigrisdata/cli）をインストールします。」と伝えてください。

移行方法

方法	ダウンタイム	最適な用途
シャドウバケット	なし	本番アプリ — Tigris はデータが見つからない場合に S3 から読み取り、自動でバックフィルします
一括コピー	短時間	小規模なデータセット、シンプルな切り替え
差分同期	なし	大規模なデータセット、段階的な移行

---

シャドウバケット（推奨）

Tigris はキャッシュミス時に既存の S3 バケットから読み取り、データを段階的にバックフィルします。事前のデータ移動は不要です。

# Create a Tigris bucket
tigris buckets create my-app-uploads
# Point the Tigris bucket at the source S3 bucket
tigris buckets set-migration my-app-uploads \
  --bucket my-existing-s3-bucket \
  --endpoint https://s3.us-east-1.amazonaws.com \
  --region us-east-1 \
  --access-key AKIA_YOUR_AWS_KEY \
  --secret-key YOUR_AWS_SECRET

--write-through を追加すると、新しい書き込みもソースバケットに同期されます。移行期間中に安全にロールバックできるようにしたい場合に便利です。

仕組み：

1. リクエストは Tigris に送られます
2. オブジェクトが Tigris に存在する場合、そのまま配信されます
3. 存在しない場合、Tigris は S3 から取得して配信し、キャッシュします

すべてを事前に移行する（任意）：

遅延移行では、オブジェクトはリクエストされたときにのみコピーされます。残りのオブジェクトをすべてサーバー側で積極的に移行するには、次を実行します。

# Migrate every unmigrated object in the bucket
tigris buckets migrate my-app-uploads

# Or scope to a key prefix
tigris buckets migrate my-app-uploads/images/

コマンドはフォアグラウンドで実行され、進行状況を随時報告するため、切り替え前にソースを完全に空にできます。

移行完了後：

# Disable migration (makes Tigris the sole source)
tigris buckets set-migration my-app-uploads --disable

---

一括コピー

小規模なデータセットの場合や、シンプルに切り替えたい場合：

Google Cloud Storage から

gsutil -m cp -r gs://my-gcs-bucket /tmp/migration/
tigris cp /tmp/migration/ t3://my-app-uploads/ -r

Azure Blob Storage から

az storage blob download-batch -d /tmp/migration/ -s my-container
tigris cp /tmp/migration/ t3://my-app-uploads/ -r

---

SDK のコード変更

移行前後の例を確認するには、使用する言語のリソースファイルを参照してください。

• Node.js / TypeScript — AWS SDK から Tigris SDK への移行については ./resources/sdk-nodejs.md を参照してください
• Go — AWS SDK から Tigris SDK への移行については ./resources/sdk-go.md を参照してください
• Python — boto3 から tigris-boto3-ext への移行については ./resources/sdk-python.md を参照するか、移行後の開発者エクスペリエンス（Django、スナップショット、フォーク、Bundle API）には tigris-python-sdk スキルを使用してください
• Ruby — aws-sdk-s3 のエンドポイント変更については ./resources/sdk-ruby.md を参照してください
• PHP — aws-sdk-php のエンドポイント変更については ./resources/sdk-php.md を参照してください

---

環境変数の変更

# Before (AWS)
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
S3_BUCKET=my-bucket

# After (Tigris)
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy
AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
S3_BUCKET=my-bucket  # bucket name can stay the same

Tigris 固有の環境変数を使用するフレームワークの場合：

TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_yyy
TIGRIS_STORAGE_ENDPOINT=https://t3.storage.dev
TIGRIS_STORAGE_BUCKET=my-bucket

---

検証チェックリスト

• ソースと Tigris のオブジェクト数が一致している
• ファイルをいくつかダウンロードして、内容とチェックサムを確認する
• 署名付き URL の生成をテストする（エンドポイントは Tigris を指している必要があります）
• ブラウザーからのアップロードを使用する場合は CORS をテストする（Tigris バケットで再設定してください）
• ステージング環境ですべてのアップロード／ダウンロードのコードパスをテストする
• CloudFront などを使用している場合は CDN のオリジンを更新する（Tigris を指定してください）
• カスタムドメインを使用している場合は DNS を更新する

---

ロールバック戦略

1. 移行中はソースバケットを読み取り専用にしておきます（データを削除しないでください）
2. 検証中は両方のシステムを並行稼働させます
3. Tigris が完全に動作することを確認してから、ソースデータを削除します
4. シャドウバケットを使用している場合、シャドウソースの削除が後戻りできない時点となります

---

よくある間違い

間違い	修正
署名付き URL のエンドポイントを更新し忘れた	署名付き URL には S3 ではなく、Tigris のエンドポイントを使用する必要があります
Tigris で CORS が設定されていない	CORS ルールを再作成します：tigris buckets cors set
リージョンが us-east-1 に固定されている	Tigris では auto を使用します
path_style が設定されていない	force_path_style: true（Ruby/Rails）または use_path_style_endpoint: true（PHP）を追加します
カスタムドメインの DNS がまだ S3 を指している	CNAME を Tigris を指すように更新します

---

関連スキル

• file-storage — CLI のセットアップと SDK のリファレンス
• tigris-security-access-control — CORS とアクセスキーのセットアップ

公式ドキュメント

• S3 互換性：https://www.tigrisdata.com/docs/sdks/s3/
• シャドウバケットと移行：https://www.tigrisdata.com/docs/migration/
• CLI：tigris buckets set-migration — https://www.tigrisdata.com/docs/cli/buckets/set-migration
• CLI：tigris buckets migrate — https://www.tigrisdata.com/docs/cli/buckets/migrate