S3

RustFS は、一般的なオブジェクトストレージのワークロード向けに、S3 互換の REST API を公開します。AWS Signature Version 4（SigV4）に対応しており、RustFS のエンドポイント、リージョン、認証情報、アドレス指定方式を設定すれば、AWS CLI、AWS SDK、その他の S3 クライアントから利用できます。

概要Copy Anchor Link

S3 はデータをバケットとオブジェクトに整理します。既定のパススタイルアクセスでは、RustFS の URL は次のようにストレージへ対応します。

http://localhost:9000/my-bucket/path/to/hello.txt
                      | bucket | |---- object key ----|

RustFS は、アプリケーション、バックアップツール、SDK が使う一般的な S3 データプレーンを対象とします。

認証されたクライアントは、アクセスキーとシークレットキーでリクエストに署名します。匿名リクエストは、適用されるバケットポリシーに対して評価されます。

設定Copy Anchor Link

S3 API は、RustFS のメインリスナーで有効です。別のプロトコル切り替えは不要です。

アプリケーションにはルート認証情報ではなく、IAM ユーザーまたはサービスアカウントを使い、必要な S3 アクションだけを許可します。

パススタイルアクセスCopy Anchor Link

パススタイルアクセスが既定であり、DNS の設定は不要です。バケット名は、リクエストパスの先頭の要素です。

http://localhost:9000/my-bucket/hello.txt

クライアントには、次を設定します。

• エンドポイント: http://localhost:9000
• リージョン: us-east-1
• アクセスキー: <your-access-key>
• シークレットキー: <your-secret-key>
• アドレス指定方式: パススタイルアクセス

一部のクライアントは、既定で仮想ホスト形式のリクエストを使います。パススタイルのオプションを有効にします。例として、AWS SDK の設定では force_path_style=true、Terraform では s3_use_path_style = true があります。

仮想ホスト形式Copy Anchor Link

仮想ホスト形式では、バケット名をホスト名に含めます。RustFS に認識させるベースドメインを、それぞれ RUSTFS_SERVER_DOMAINS に設定します。

export RUSTFS_SERVER_DOMAINS="s3.example.com"

同じオブジェクトは、次のアドレスになります。

https://my-bucket.s3.example.com/hello.txt

*.s3.example.com のようなワイルドカード DNS が、RustFS のエンドポイントへ解決するよう設定します。HTTPS では、証明書がバケットのホスト名もカバーする必要があります。ドットを含むバケット名では、単一ラベルのワイルドカードが複数ラベルにまたがらないため、証明書名を明示する必要がある場合があります。

TLS とネットワークアクセスCopy Anchor Link

本番では、rustfs_cert.pem と rustfs_key.pem を含むディレクトリを RUSTFS_TLS_PATH に設定し、https:// のエンドポイントを使います。クライアントが、発行元の認証局を信頼するようにします。

設定した S3 API のポートを、ホストのファイアウォールとロードバランサーで許可します。既定は TCP ポート 9000 です。このリスナーは RustFS の管理トラフィックとノード間トラフィックも運ぶため、適切なネットワーク制御と IAM 制御がないまま、制限なく公開しないでください。

使い方Copy Anchor Link

次の例では、標準のローカルエンドポイントとともに AWS CLI を使います。続ける前に、AWS CLI をインストールして設定します。

AWS CLI を設定するCopy Anchor Link

aws configure

求められたら、次の値を入力します。

AWS Access Key ID [None]: <your-access-key>
AWS Secret Access Key [None]: <your-secret-key>
Default region name [None]: us-east-1
Default output format [None]: json

すべてのコマンドに RustFS のエンドポイントを渡します。カスタムエンドポイントにより、これらの例は AWS S3 ではなく RustFS を対象にします。

export RUSTFS_ENDPOINT="http://localhost:9000"

バケットを作成して一覧するCopy Anchor Link

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

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api list-buckets

オブジェクトをアップロードして一覧するCopy Anchor Link

printf 'Hello from RustFS\n' > hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 cp \
	hello.txt s3://my-bucket/path/to/hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 ls \
	s3://my-bucket/path/to/

AWS CLI は、転送設定が大きなオブジェクトに対してマルチパートを選んだ場合、自動的にマルチパートアップロードを使います。RustFS は、標準のマルチパートの create、upload-part、complete、list、abort の各ワークフローに対応しています。

オブジェクトをダウンロードして確認するCopy Anchor Link

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 cp \
	s3://my-bucket/path/to/hello.txt ./downloaded-hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api head-object \
	--bucket my-bucket \
	--key path/to/hello.txt

署名付き URL を作成するCopy Anchor Link

認証情報を公開せずにオブジェクトをダウンロードできる、有効期限付きの URL を生成します。

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 presign \
	s3://my-bucket/path/to/hello.txt \
	--expires-in 3600

受け取り側が使うホスト名、スキーム、ポート、リージョン、オブジェクトパスは、URL の署名に使った値と一致する必要があります。別のマシン向けの URL を生成するときは、外部から到達できるエンドポイントを使います。

オブジェクトとバケットを削除するCopy Anchor Link

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 rm \
	s3://my-bucket/path/to/hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api delete-bucket \
	--bucket my-bucket

S3 バケットは、削除する前に空である必要があります。

既知の互換性の違いCopy Anchor Link

現在の RustFS の互換性テストは、上で説明した一般的なワークフローを対象としています。次の領域は、AWS S3 または MinIO と同等ではありません。

• バケットアクセスログとバケット所有者コントロールは、完成した機能ではなく、未実装（予定）です。
• ACL による認可は、意図的にサポートしていません。既定 ACL のヘッダーには部分的な互換がありますが、XML の grant ポリシーは NotImplemented を返します。IAM とバケットポリシーを優先することを推奨します。
• POST Object のフォームアップロードは実装されていますが、そのワークフローのチェックサム処理は完了していません。
• マルチパートアップロードの一覧とパート検索における一部の境界条件は、既定の互換性検証（ゲート）の対象外です。
• S3 Select は、現時点では非圧縮の入力だけを受け付けます。
• Access Point と Outposts のコピーソース形式は、実装されていません。
• MinIO の管理 API は別の互換範囲であり、S3 データプレーンの対応から推測しないでください。

ツールが AWS 固有のサービス、ストレージクラス、アカウントの所有権制御、エンドポイント検出を前提としている場合、クライアントの動作が異なることもあります。RustFS のエンドポイントは常に明示して設定し、アプリケーションが使う操作そのものをテストします。

次のステップCopy Anchor Link

• 一連の手順は、AWS CLI の例に従います。
• アプリケーション連携には、S3 SDKを選びます。
• 認証情報とアクセスポリシーを設定します。
• 信頼できるネットワークの外へエンドポイントを公開する前に、TLSを有効にします。