sealos-s3

Sealos S3

識別と検出

• 所有者： sealos-s3（/sealos-s3 およびバケット、オブジェクト、ポリシー、認証情報、署名付き URL、またはクォータに関するリクエスト）。
• クラス： sealos-cli s3 を介した cloud-local-mutation。必要に応じて、秘匿情報を削除したデプロイ引き継ぎを行います。
• カナリア： S3-PRIVATE-REUSE、S3-CONFIRM-PUBLIC、S3-REDACT-OBJECT。

範囲と境界

プロジェクトのパスとオブジェクトストレージの意図を受け取ります。まず分析し、既存のバケットを一覧表示して、プライベートストレージを作成または再利用します。必要な場合にのみ認証情報を初期化し、既存の最小限の環境変数キーセットを接続します。ローカルの MinIO／Compose フォールバックを維持します。パブリックポリシー、ローテーション、削除、破壊的なオブジェクト変更には引き続きゲートを設けます。

リスクと確認

バケットはデフォルトでプライベートにします。パブリックポリシー、稼働中のアプリの認証情報のローテーション、バケット／オブジェクトの削除、ストレージ設定の置き換えを行う前に確認を求めます。シークレットキー、認証情報ブロック全体、kubeconfig、認証ファイル、コピーした環境変数の値を表示しないでください。テーブルからシークレットをスクレイピングするのではなく、JSON 出力を解析してください。

ライフサイクルのワークフロー

各リクエストについて、プロジェクトを特定し、ストレージの必要性を分析して、CLI／認証／リージョン／ワークスペースを確認します。作成または再利用の前に一覧表示し、認証情報の準備が整うまで待ってから、既存のキーを接続します。認証済みのアップロード／読み取り、または署名付き URL の経路を実証し、一時オブジェクトをクリーンアップして、ポリシーの状態を報告します。リクエストごとに success、stopped、または error を出力します。既存のプライベート優先ワークフローは、以下のドメイン拡張として維持されます。ワークスペースが曖昧な場合、認証情報の準備ができていない場合、または対象の環境変数が追跡対象の場合は、変更を加える前にリクエストを停止します。

リクエストの契約

input:
  project: local path or repository source
  intent: bucket purpose, object path, and sharing requirement
  policy: private by default; publicRead/publicReadwrite only after confirmation
preconditions:
  - analyzer evidence identifies the storage adapter and env keys
  - sealos-cli/auth/region/workspace are resolved
  - bucket list and credential status are available

アクションの順序は analyze -> resolve account/workspace -> list -> create or reuse -> wait for secret -> wire -> object-flow -> cleanup です。バケットの識別情報、ポリシー、名前空間、環境変数の変更はリクエスト単位で扱います。

段階的な情報開示

各フェーズに到達したら、アナライザー、バケット、ポリシー、認証情報、オブジェクトフロー、クリーンアップの手順を一段階だけ読み込みます。CLI の詳細を示す前に、プライベートポリシー、確認、秘匿情報の削除に関するカナリアを見える状態にしておきます。

出力、停止、エラーの状態

• success：バケットの識別情報／ポリシー／準備状況、ワークスペース、環境変数キー名、認証済みオブジェクトまたは署名付き URL の実証、クリーンアップの状態、秘匿情報の削除状況。
• stopped：ワークスペースの曖昧さ、認証情報の準備ができていないこと、対象の環境変数が追跡対象であること、パブリックポリシー、ローテーション、置き換え、または破壊的操作の確認境界。安全なプライベート／署名付き URL の代替手段も示します。ゲート対象の操作を実行したとは報告しません。
• error：アナライザー、CLI、ポリシー、認証情報、オブジェクト、または環境変数の書き込み手順でのエラー、サニタイズ済みの診断カテゴリ、影響を受けた成果物、認証情報、エンドポイント、接続値を秘匿した復旧手順。

引き継ぎ

必要に応じたデプロイ引き継ぎでは、以下の完全なタプルを使用します。引き継ぎ先は、デプロイの範囲と実行時の証拠を再確認します。

target: sealos-deploy
inputArtifact: private bucket identity, policy, approved env-key contract, credential-readiness state, and object-flow proof
allowedAction: consume approved ObjectStorageBucket/Secret wiring within the selected deployment scope
failureReturn: sanitized analyzer, CLI, policy, credential, object, or env diagnostic with the failed phase
responseOwner: sealos-s3

S3 への直接のリクエストでは target: none を使用し、同じ証拠フィールドを維持します。

検証

analyze-project-s3.mjs、sealos-cli s3 の JSON 出力、認証済みオブジェクトフローの証拠、ベースラインケース s3-positive-private-round-trip および s3-violating-unconfirmed-public-or-rotation を使用します。成功とする前に、プライベートポリシー、環境変数の保持、秘匿情報の削除を検証してください。

このスキルを使うと、sealos-cli s3 を通じてプロジェクトに実際の Sealos オブジェクトストレージを提供できます。デフォルトの結果は、アプリのオブジェクトストレージの必要性を特定し、バケットを作成または再利用し、必要な場合にのみ認証情報を初期化し、必要最小限で安全なローカル環境変数を接続して、プロジェクトのアップロード／ダウンロードまたは署名付き URL の経路を検証することです。

このスキルは、s3 コマンドを登録し、バケットの CRD 操作と S3 互換オブジェクト操作を実装した zjy365/sealos-cli#28 に基づいています。

安全ルール

1. 最終回答にシークレットキー、完全な S3 認証情報ブロック、またはコピーした環境変数の値を決して出力しないでください。
2. 既存の環境変数の値を、確認または元の値を保持せずに上書きしないでください。
3. .env、.env.local、S3 アクセスキー、シークレットキー、kubeconfig、Sealos 認証ファイルをコミットしないでください。
4. バケットを公開する前に確認してください。デフォルトのバケットポリシーは private です。
5. 破壊的な操作を行う前に確認してください：s3 delete-bucket、s3 delete、稼働中のアプリの認証情報ローテーション、またはアプリのストレージ設定の置き換え。
6. デフォルトでは sealos-cli の JSON 出力を使い、テーブル出力をスクレイピングするのではなく、JSON を解析してください。
7. CLI で出力できる場合でも、s3 secret の出力は機密情報として扱ってください。

ワークフロー

1. 対象プロジェクトを特定する

pwd または git rev-parse --show-toplevel で作業ディレクトリを確認してください。

プロジェクトディレクトリが利用可能な場合は、アナライザーを実行してください：

node <SKILL_DIR>/scripts/analyze-project-s3.mjs <project-dir>

アナライザーの結果を出発点とし、編集する前に、そこで示された実際のファイルを確認してください。アナライザーは意図的にシークレットの値を出力しません。

2. sealos-cli を確認する

既存の sealos-cli バイナリがあれば、そちらを優先してください：

sealos-cli --version
sealos-cli s3 --help
sealos-cli whoami

インストールされていない場合は、単発のコマンドに npx -y sealos-cli@latest ... を使ってください。グローバルインストールは事前に確認してください。

認証情報がない、または期限切れの場合は、次を実行してください：

sealos-cli login <region>
sealos-cli workspace list
sealos-cli workspace current

ユーザーが想定するワークスペースを使用してください。複数のワークスペースがあり、対象を特定できない場合は、プロビジョニングする前に確認してください。sealos-cli s3 はアクティブな kubeconfig の名前空間からオブジェクトストレージユーザーを特定するため、誤ったワークスペースを使用すると、バケットと認証情報も誤ったものになります。

3. 新規作成するか、既存のものを再利用するかを選ぶ

まず既存のバケットを一覧表示してください：

sealos-cli s3 buckets -o json

用途とポリシーが一致する既存のバケットがあれば再利用してください。プロジェクトに適したバケットがない場合、またはユーザーが新しいバケットを求めている場合は、新規作成してください：

sealos-cli s3 create-bucket <bucket-name> --policy private -o json

ユーザーが明示的にパブリック読み取りまたは書き込みを必要としていない限り、private を使用してください。PR で受け付けられるバケットポリシーは private、publicRead、publicReadwrite です。public-read のような別名は publicRead に正規化されますが、手順やスクリプトでは正規の値を使用してください。

4. 必要な場合にのみ認証情報を初期化する

アプリの環境変数設定またはオブジェクト操作のために、認証情報を取得してください：

sealos-cli s3 secret -o json

このコマンドは、存在しない場合に ObjectStorageUser を作成し、その後、ステータスが反映されるまで少し待ちます。認証情報が準備できていない場合は、手作業で生の CRD を作成するのではなく、数秒後に再試行してください。

現在のコマンド仕様と応答の処理方法については、references/sealos-cli-s3.md を参照してください。

5. 開発環境を設定する

プロジェクトがすでに使用しているキーだけを対応付けてください。一般的な設定先は次のとおりです：

プロジェクトの兆候	推奨する環境変数キー
AWS SDK / 汎用 S3	S3_ENDPOINT、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY、S3_BUCKET
AWS 形式の設定	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION、S3_BUCKET
MinIO の置き換え	既存の MINIO_* キーを使用するか、アプリが対応している場合に限り既存の S3 キーへ移行する
アップロードライブラリ	アダプター／設定ファイルが読み込むキー

ローカルのラップトップでの開発には、secret.external のエンドポイントを使用してください。アプリが Sealos/Devbox 内で実行され、実行環境から内部エンドポイントに到達できる場合に限り、secret.internal を使用してください。

環境変数ファイルを編集する前に、references/env-integration.md を読んでください。

6. アプリのストレージ動作を検証する

オブジェクトストレージが機能することを証明するため、実際のプロジェクトで最小限の処理を実行してください：

1. 利用可能であれば、オブジェクトをアップロードして読み取るリポジトリのスクリプトまたはテストを実行します。
2. それ以外の場合は、sealos-cli s3 upload で小さなローカルテストファイルをアップロードし、一覧表示して、一時パスにダウンロードした後、テストオブジェクトを削除します。
3. 署名付き URL 機能の場合は、sealos-cli s3 presign <bucket> <key> --expires 3600 -o json を実行し、それが依頼されたワークフローに含まれる場合に限り、URL を確認してください。

Sealos 以外の S3 互換エンドポイントに接続する場合に限り、--endpoint、--access-key、--secret-key をまとめて使用してください。一部の上書きオプションだけを混在させないでください。

7. 結果を報告する

以下をまとめます。

1. バケット名、ポリシー、リージョン／ワークスペース、および準備状況。
2. 更新した環境ファイルとキー。シークレットの値は明かしません。
3. 検証コマンドとその結果。
4. 公開ポリシー、認証情報のローテーション、またはクリーンアップに関するフォローアップ。

よくあるタスク

既存のプロジェクトを Sealos オブジェクトストレージに接続する

1. アナライザーを実行します。
2. アナライザーが示した環境／設定ファイルを確認します。
3. 既存のバケットを一覧表示します。
4. 条件に合うバケットを作成するか、既存のものを再利用します。
5. s3 secret で認証情報を取得します。
6. アプリが読み込む環境キーだけを書き込みます。
7. アプリのストレージパスを検証します。

開発環境のローカル MinIO を置き換える

1. MinIO または S3 互換サービスを参照しているアプリサービスの環境変数を特定します。
2. Sealos のプライベートバケットを作成するか、既存のものを再利用します。
3. ユーザーから MinIO の削除を求められない限り、Compose ファイルではなく、アプリのローカル環境ファイルだけを更新します。
4. 元の MinIO サービスは引き続き利用できる状態にして、ローカル Compose から簡単にロールバックできるようにします。

プロジェクトのアセットをアップロードまたは共有する

1. 対象のバケットとオブジェクトキーのプレフィックスを確認します。
2. sealos-cli s3 upload <bucket> <file> --key <key> -o json でアップロードします。
3. 可能な場合は、パブリックバケットポリシーではなく、presign を使って一時的に共有します。
4. 検証後、一時的なテストオブジェクトを削除します。

参考資料

• scripts/analyze-project-s3.mjs - プロジェクトのオブジェクトストレージ利用意図を読み取り専用で分析するツール。
• references/sealos-cli-s3.md - PR #28 の sealos-cli s3 コマンド仕様。
• references/env-integration.md - 環境ファイルを安全に編集する方法と、S3 環境キーのマッピング。