S3/S3互換ストレージ

S3サブコマンドは、Amazon S3だけでなく、S3互換プロトコルをサポートする様々なストレージサービスに対応します。

対応ストレージ

Amazon S3 - Amazon Web Servicesの標準的なオブジェクトストレージ
MinIO - オープンソースのS3互換オブジェクトストレージ（セルフホスト可能）
Wasabi - 高速・低コストのクラウドストレージ
その他 - S3 APIをサポートする任意のストレージサービス

Amazon S3の基本的な使い方

コマンドライン:

# ACL指定（推奨）
lightfile-batch s3 \
  --s3-bucket my-bucket \
  --s3-region ap-northeast-1 \
  --s3-acl private \
  --s3-access-key AKIAIOSFODNN7EXAMPLE \
  --s3-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

YAML設定ファイル:

s3:
  bucket: my-bucket
  region: ap-northeast-1
  acl: private                    # ACL設定（必須）
  accessKeyId: AKIAIOSFODNN7EXAMPLE
  secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

注意: --s3-acl オプションは必須です。

ACL（アクセス制御）について

S3バケットへのアップロード時のACLを指定します。ACLは必須設定項目です。

利用可能なACL

ACL	説明
`private`	オーナーのみ読み書き可能
`public-read`	全員が読み取り可能
`public-read-write`	全員が読み書き可能
`authenticated-read`	認証されたAWSユーザーが読み取り可能
`bucket-owner-read`	バケットオーナーが読み取り可能
`bucket-owner-full-control`	バケットオーナーがフルコントロール
`_keep`	既存ファイルのACLを保持（Amazon S3のみ）

`_keep` モードについて（Amazon S3専用）

_keep は、既存オブジェクトの複雑なACL設定を保持するための特殊なモードです。

動作:

既存ファイルのACLを詳細に取得
上書き保存後に取得したACLを可能な限り再現

使用するケース:

オブジェクトのACL設定が複雑な場合
既存のACL設定を維持する必要がある場合

注意点:

API呼び出し回数が大幅に増加 - パフォーマンスが低下します
Amazon S3専用 - S3互換ストレージでは使用できません
推奨: 可能な限り private や public-read などの事前定義されたACLを使用してください

コマンドライン:

# 既存ファイルのACLを保持（非推奨：API呼び出しが増加）
lightfile-batch s3 \
  --s3-bucket my-bucket \
  --s3-region ap-northeast-1 \
  --s3-acl _keep \
  --s3-access-key AKIAIOSFODNN7EXAMPLE \
  --s3-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

YAML設定ファイル:

s3:
  bucket: my-bucket
  region: ap-northeast-1
  acl: _keep                      # 既存ファイルのACLを保持（非推奨）
  accessKeyId: AKIAIOSFODNN7EXAMPLE
  secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

S3互換ストレージ（MinIO）

S3互換ストレージを使用する場合、endpoint でカスタムエンドポイントを指定します。

forcePathStyle について

一部のS3互換ストレージ（MinIO等）では、forcePathStyle を true に設定する必要があります。

Virtual-Hosted Style (Amazon S3のデフォルト): https://bucket-name.s3.amazonaws.com/key
Path Style (MinIOなどで必要): https://s3.example.com/bucket-name/key

MinIOなどのPath-Styleエンドポイントを使用するストレージでは、--s3-force-path-style オプション（またはYAMLで forcePathStyle: true）を指定してください。

MinIOの接続例

コマンドライン:

lightfile-batch s3 \
  --s3-endpoint https://minio.example.com \
  --s3-bucket my-bucket \
  --s3-region us-east-1 \
  --s3-acl private \
  --s3-force-path-style \
  --s3-access-key minioadmin \
  --s3-secret-key minioadmin

YAML設定ファイル:

s3:
  endpoint: https://minio.example.com
  bucket: my-bucket
  region: us-east-1
  acl: private                # 必須（MinIOではACLが無視される可能性あり）
  accessKeyId: minioadmin
  secretAccessKey: minioadmin
  forcePathStyle: true        # MinIOでは必須

注意:

MinIOなどの一部のS3互換ストレージは、ACLをサポートしない場合があります
その場合でも設定上はACL値（通常は private）を指定する必要がありますが、実際には無視されます

目次