S3 Tables

RustFS S3 Tables は、組み込み REST カタログを通じて Apache Iceberg テーブルを管理します。テーブルデータ、マニフェスト、Iceberg メタデータは、RustFS 内の S3 オブジェクトとして保存されます。このガイドでは、専用テーブルバケットの有効化、クライアント接続、権限、メンテナンスの制限を説明します。

仕組み

Iceberg クライアントは REST カタログを使用してテーブルを検出し、メタデータの変更をコミットします。テーブルファイルの読み書きには S3 API を使用します。どちらのインターフェイスも、RustFS の S3 API ポートで提供されます。

テーブルバケットを有効にしても、既存の Parquet ファイルが自動的に Iceberg テーブルとして登録されるわけではありません。Iceberg クライアントでテーブルを作成または登録します。location を指定しない場合は RustFS が保存先を割り当てます。指定する場合は同じバケット内に置く必要があります。クライアントは返された保存先を使用してください。

デフォルトの object カタログバックエンドは、カタログの状態を RustFS オブジェクトストレージに永続化します。テーブルのコミットでは、基準となるメタデータと参照先オブジェクトを検証してから、現在のメタデータを指すポインターを条件付きで更新します。書き込みが競合した場合、クライアントはテーブルを再読み込みして競合を解決する必要があります。トランザクションの範囲は単一テーブルです。

前提条件

• 上記の S3 Tables エンドポイントを備えた RustFS を起動します。インストールを参照してください。
• AWS CLI と、--aws-sigv4 および --fail-with-body をサポートする curl 7.76 以降をインストールします。
• このチュートリアル専用の新しいバケットを用意します。例では my-bucket を使用します。
• カタログ操作と S3 オブジェクトの両方にアクセスできる既存の管理者アカウントを使用します。組み込みの consoleAdmin ポリシーは、このチュートリアルの操作をカバーします。アプリケーションには、範囲を絞ったポリシーを設定してください。

例では http://localhost:9000 を使用します。サーバーのエンドポイントに置き換え、ローカルテスト環境以外では証明書の検証を有効にした TLS を使用してください。

export RUSTFS_ENDPOINT="http://localhost:9000"
export AWS_ACCESS_KEY_ID="<your-access-key>"
export AWS_SECRET_ACCESS_KEY="<your-secret-key>"
export AWS_DEFAULT_REGION="us-east-1"

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api create-bucket --bucket my-bucket

curl --fail-with-body --silent --show-error \
	--aws-sigv4 "aws:amz:us-east-1:s3" \
	--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
	--header "x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
	--request PUT "$RUSTFS_ENDPOINT/iceberg/v1/buckets/my-bucket"

curl --fail-with-body --silent --show-error \
	--aws-sigv4 "aws:amz:us-east-1:s3" \
	--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
	--header "x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
	"$RUSTFS_ENDPOINT/iceberg/v1/buckets/my-bucket"

{
	"table-bucket": "my-bucket",
	"enabled": true,
	"catalog-type": "iceberg-rest",
	"warehouse": "my-bucket",
	"catalog-entry-present": true
}

権限と認証情報

テーブルバケットの有効化には admin:SetTableBucket、状態の確認には admin:GetTableBucket が必要です。カタログの検出には admin:GetTableCatalog を使用します。名前空間とテーブルの操作には、それぞれ admin:SetTableNamespace、admin:CreateTable、admin:GetTableMetadata、admin:CommitTable などの RustFS 管理アクションがあります。

テーブルファイルの読み書きには、通常の S3 権限も必要です。RustFS はウェアハウス内のオブジェクトパスに対してテーブル権限を確認します。読み取りには対応する admin:GetTableMetadata の認可、書き込みには admin:SetTableMetadata の認可が必要です。カタログのコミット権限だけでは、その前に行う S3 ファイルの書き込みは許可されません。両方のインターフェイスに対して IAM ポリシーを設定してください。

カタログによる認証情報の払い出しは、デフォルトで無効です。有効にした場合、対応クライアントは X-Iceberg-Access-Delegation: vended-credentials を使用してネゴシエーションを行い、呼び出し元にはテーブル認証情報を要求する権限が必要です。カタログへの初回接続にも、認可済みの主体が必要です。リンク先の PyIceberg チュートリアルでは、明示的に設定した認証情報を使用します。

メンテナンスとデータ保護

メタデータの削除とバックグラウンドメンテナンスは、デフォルトで無効です。RustFS は計画の作成、スケジューラーの実行、ワーカーの実行を明示的な操作として提供します。組み込みの定期メンテナンススケジューラーはありません。削除を有効にする前に、メンテナンス計画と保持される参照を確認してください。

テーブルを削除すると、カタログのエントリは削除されますが、基になるオブジェクトは残ります。必要なテーブルメンテナンスは登録解除前に実施します。登録解除後は、メンテナンス操作でテーブルを見つけられなくなります。残ったオブジェクトのクリーンアップには、残存するすべての参照を考慮した別の計画が必要です。スナップショットやほかのメタデータが参照している可能性のある S3 パスを再帰的に削除しないでください。

このチュートリアルでは、デフォルトのカタログバックエンドを使用します。既存のデプロイを durable-strong に切り替えるには、移行前の検査と書き込み元の協調的な遮断を含むカタログ切り替え手順が必要です。

クライアントの互換性と制限

ソースリポジトリで維持されている検証範囲は次のとおりです。

Iceberg フォーマット v1 と v2 をサポートし、デフォルトは v2 です。ステージングによるテーブル作成、テーブル削除時のデータ消去、Iceberg フォーマット v3 はサポートしていません。

RustFS S3 Tables は、SQL 実行エンジン、複数テーブルにまたがるアトミックトランザクション、リージョン間で独立したアクティブ・アクティブ書き込みを提供しません。AWS S3 Tables のコントロールプレーンとの完全な互換性も表明していません。別のエンジンやベンダー固有のプロファイルを使用する前に、サポートマトリクスを確認してください。

次のステップ

• PyIceberg チュートリアルを実行します。
• アプリケーションへのアクセスを許可する前に、IAM ポリシーを確認します。
• リポジトリのクライアント適合性チェックを使用して、ほかのクライアントバージョンを検証します。