Sealos S3

Sealos S3

Use this skill to give a project real Sealos object storage through sealos-cli s3. The default outcome is: identify the app's object-storage need, create or reuse a bucket, initialize credentials only when needed, wire the smallest safe set of local env vars, and verify the project's upload/download or presigned URL path.

This skill is grounded in zjy365/sealos-cli#28, which registered the s3 command and implemented bucket CRD operations plus S3-compatible object operations.

Safety Rules

1. Never print secret keys, full S3 credential blocks, or copied env values in the final answer. 2. Do not overwrite an existing env value without confirming or preserving the old value. 3. Do not commit .env, .env.local, S3 access keys, secret keys, kubeconfig, or Sealos auth files. 4. Ask before making a bucket public. Default bucket policy is private. 5. Ask before destructive operations: s3 delete-bucket, s3 delete, credential rotation for an active app, or replacing app storage configuration. 6. Use JSON output from sealos-cli by default and parse it instead of scraping table output. 7. Treat s3 secret output as sensitive even though the CLI can print it.

Workflow

1. Resolve the target project

Confirm the working directory with pwd or git rev-parse --show-toplevel.

Run the analyzer when a project directory is available:

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

Use the analyzer result as a starting point, then inspect the real files it cites before editing anything. It intentionally avoids printing secret values.

2. Check sealos-cli

Prefer an existing sealos-cli binary:

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

If it is not installed, use npx -y sealos-cli@latest ... for one-off commands. Ask before installing it globally.

If auth is missing or expired, run:

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

Use the workspace the user expects. If multiple workspaces exist and the target is ambiguous, ask before provisioning. sealos-cli s3 derives the object-storage user from the active kubeconfig namespace, so a wrong workspace means wrong buckets and credentials.

3. Choose create or reuse

List existing buckets first:

sealos-cli s3 buckets -o json

Reuse an existing bucket when its purpose and policy match. Create a new one when the project has no suitable bucket or the user asks for a fresh bucket:

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

Use private unless the user explicitly needs public reads or writes. Bucket policies accepted by the PR are private, publicRead, and publicReadwrite; aliases such as public-read normalize to publicRead, but use canonical values in instructions and scripts.

4. Initialize credentials only when needed

For app env wiring or object operations, fetch credentials:

sealos-cli s3 secret -o json

The command creates the ObjectStorageUser if it does not exist, then waits briefly for status. If credentials are not ready, retry after a few seconds instead of creating raw CRDs by hand.

Use references/sealos-cli-s3.md for the current command contract and response handling.

5. Wire the development environment

Map only the keys the project already uses. Common targets:

Use endpoint from secret.external for local laptop development. Use secret.internal only when the app runs inside Sealos/Devbox and the runtime can reach the internal endpoint.

Read references/env-integration.md before editing env files.

6. Verify application storage behavior

Run the smallest real project path that proves object storage works:

1. Run a repo script or test that uploads and reads an object if available. 2. Otherwise upload a small local test file with sealos-cli s3 upload, list it, download it to a temp path, and delete the test object. 3. For presigned URL features, run sealos-cli s3 presign <bucket> <key> --expires 3600 -o json and verify the URL only when that is part of the requested workflow.

Use --endpoint, --access-key, and --secret-key together only when connecting to a non-Sealos S3-compatible endpoint. Do not mix partial overrides.

7. Report the result

Summarize:

1. Bucket name, policy, region/workspace, and readiness. 2. Env file and keys updated, without revealing secret values. 3. Verification command and outcome. 4. Any public policy, credential rotation, or cleanup follow-up.

Common Tasks

Connect an existing project to Sealos object storage

1. Run the analyzer. 2. Inspect the env/config files it cites. 3. List existing buckets. 4. Create or reuse the matching bucket. 5. Fetch credentials with s3 secret. 6. Write only the env keys the app reads. 7. Verify the app's storage path.

Replace local MinIO for development

1. Identify the app service env vars that point at MinIO or an S3-compatible service. 2. Create or reuse a private Sealos bucket. 3. Update only the app's local env file, not the compose file, unless the user asks to remove MinIO. 4. Keep local Compose rollback simple: the original MinIO service remains available.

Upload or share project assets

1. Confirm the target bucket and object key prefix. 2. Upload with sealos-cli s3 upload <bucket> <file> --key <key> -o json. 3. Use presign for temporary sharing instead of public bucket policy when possible. 4. Delete temporary test objects after verification.

References

• scripts/analyze-project-s3.mjs - read-only project object-storage intent analyzer.
• references/sealos-cli-s3.md - PR #28 sealos-cli s3 command contract.
• references/env-integration.md - safe env-file editing and S3 env-key mapping.

S3 Environment Integration

Use this reference when wiring Sealos object storage credentials into a development project.

File Choice

Prefer the project's existing convention:

1. .env.local for Next.js and similar local-only app config. 2. .env when the repo already uses it for local development and it is ignored by git. 3. Framework-specific files such as .dev.vars, .env.development, or apps/*/.env.local when the code already reads them. 4. .env.example only for placeholder documentation. Never write real secrets into example files.

Before writing secrets, verify the file is ignored:

git check-ignore .env .env.local .env.development .dev.vars

If the target file is tracked or not ignored, stop and choose an ignored local env file instead.

Env Key Mapping

Prefer keys already used by the app.

If multiple keys exist, update the one read by the runtime entry point or storage adapter config. Do not create extra aliases unless the app needs them.

Values From sealos-cli s3 secret

Map fields conservatively:

secret.CONSOLE_ACCESS_KEY -> access key env
secret.CONSOLE_SECRET_KEY -> secret key env
secret.external           -> local laptop endpoint
secret.internal           -> Sealos/Devbox internal endpoint
bucket name               -> bucket env
region                    -> us-east-1
path style                -> true, when the app exposes such a setting

sealos-cli s3 itself uses the AWS SDK with forcePathStyle: true and region us-east-1. Prefer the same settings when a project asks for region or path-style options.

Editing Rules

1. Preserve comments, blank lines, and unrelated keys. 2. Replace only the selected keys. 3. If a key exists and has a non-empty value, preserve the old value in chat as "replaced existing local value" without printing it. 4. Quote values only if the project's env files already use quotes or the value contains characters that the loader requires quoted. 5. Never print the full resulting credential set in the final answer. 6. Do not write CONSOLE_ACCESS_KEY and CONSOLE_SECRET_KEY unless the project already expects those exact names; they are CLI response field names, not generally app env names.

Bucket and Endpoint Choices

Use a private bucket for app uploads unless the user explicitly wants public reads. Prefer presigned URLs for temporary sharing.

Use secret.external for local-machine development and secret.internal for apps running inside Sealos/Devbox when that runtime can reach the internal endpoint.

Do not switch a project from local MinIO to Sealos by editing Docker Compose unless the user asks. Updating local env keeps rollback easy.

Verification

Use the project's own path when available:

• Next.js / Node: run the upload route test, storage service test, or smallest script that calls the configured S3 client.
• Rails: run the Active Storage smoke path or a targeted storage test.
• Django: run a storage backend smoke test or targeted test.
• Generic app: upload a small object, list it, download it to a temp path, then delete the test object.

Fallback CLI smoke test:

printf 'sealos-s3-smoke\n' > /tmp/sealos-s3-smoke.txt
sealos-cli s3 upload <bucket> /tmp/sealos-s3-smoke.txt --key smoke/sealos-s3-smoke.txt -o json
sealos-cli s3 list <bucket> --prefix smoke/ -o json
sealos-cli s3 download <bucket> smoke/sealos-s3-smoke.txt /tmp/sealos-s3-smoke.out -o json
sealos-cli s3 delete <bucket> smoke/sealos-s3-smoke.txt -o json

Do not leave temporary objects behind after verification.

sealos-cli S3 Reference

Use sealos-cli s3 as the execution layer for Sealos object storage work. This reference is based on zjy365/sealos-cli#28 (feat: add s3 object storage commands), which registered s3 in src/main.ts and implemented it in src/commands/s3/index.ts.

Install and Auth

Prefer an existing binary:

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

Use one-off execution when the binary is missing:

npx -y sealos-cli@latest s3 --help

Authenticate and choose the workspace:

sealos-cli login https://usw-1.sealos.io
sealos-cli workspace list
sealos-cli workspace switch <workspace-id-or-team-name>
sealos-cli workspace current

sealos-cli s3 reads the active kubeconfig and uses the current context namespace. If the context has no namespace, the CLI tells the user to run sealos-cli login or sealos-cli workspace switch.

Implementation Model

Bucket and credential commands talk to Kubernetes custom resources in the active namespace:

• ObjectStorageBucket in API group objectstorage.sealos.io/v1
• ObjectStorageUser in API group objectstorage.sealos.io/v1

The object storage user name is derived from the namespace by removing a leading ns-. For example, namespace ns-private maps to user private.

Object operations use the AWS SDK S3 client against the S3-compatible endpoint returned in ObjectStorageUser.status.external, with forcePathStyle: true and region us-east-1.

Bucket Names and Policies

Bucket CR names are stored without the workspace prefix. Formatted bucket names include the namespace-derived prefix:

namespace ns-private + CR name assets -> bucket name private-assets

The CLI accepts either the displayed bucket name or the CR name for bucket CRD operations and normalizes away the namespace prefix.

Supported canonical policies:

• private
• publicRead
• publicReadwrite

Accepted aliases include readonly, read, public-read, readwrite, read-write, public-readwrite, and public-read-write. Do not use public; the PR tests require it to fail.

Bucket Commands

Use JSON for automation:

sealos-cli s3 buckets -o json
sealos-cli s3 create-bucket <name> --policy private -o json
sealos-cli s3 get-bucket <name> -o json
sealos-cli s3 update-bucket <name> --policy publicRead -o json
sealos-cli s3 delete-bucket <name> -o json

Aliases:

sealos-cli s3 list-buckets -o json
sealos-cli s3 rm-bucket <name> -o json

create-bucket updates the policy if the bucket already exists. Ask before changing a bucket from private to publicRead or publicReadwrite.

Formatted bucket output includes:

{
  "name": "private-assets",
  "crName": "assets",
  "policy": "private",
  "isComplete": true,
  "createdAt": "2026-05-27T00:00:00Z",
  "uid": "bucket-uid"
}

buckets -o json wraps the list as { "list": [...] }.

Credentials and Quota

Initialize or read credentials:

sealos-cli s3 secret -o json

JSON shape:

{
  "secret": {
    "CONSOLE_ACCESS_KEY": "<access-key>",
    "CONSOLE_SECRET_KEY": "<secret-key>",
    "internal": "<internal-endpoint>",
    "external": "<external-endpoint>",
    "specVersion": 0,
    "version": 0
  }
}

Treat every field in secret as sensitive except endpoint hostnames. Do not print the access key or secret key in final answers.

Rotate credentials:

sealos-cli s3 rotate-secret -o json

The response is asynchronous:

{
  "success": true,
  "action": "rotate-secret",
  "resource": "s3-user",
  "name": "<object-storage-user>",
  "specVersion": 123456789,
  "status": "updating"
}

After rotation, rerun sealos-cli s3 secret -o json and update dependent env values only after the new status is ready.

Check quota:

sealos-cli s3 quota -o json

Response shape:

{
  "quota": {
    "total": 10737418240,
    "used": 1024,
    "count": 1
  }
}

Fields can be null if status is not populated.

Object Commands

Object commands initialize Sealos credentials automatically unless all three overrides are provided:

--endpoint <url>
--access-key <key>
--secret-key <key>

Provide all three override flags together or none.

List objects:

sealos-cli s3 list <bucket> --prefix images/ --delimiter / --max-keys 100 --token <continuation-token> -o json

--max-keys must be a positive integer. JSON output:

{
  "prefixes": ["images/"],
  "objects": [
    {
      "key": "images/logo.png",
      "size": 1234,
      "lastModified": "2026-05-27T00:00:00.000Z",
      "eTag": "\"etag\"",
      "storageClass": null
    }
  ],
  "isTruncated": false,
  "nextContinuationToken": null
}

Upload:

sealos-cli s3 upload <bucket> <file> --key <object-key> --content-type image/png -o json

If --key is omitted, the CLI uses the local file path as the object key. Prefer passing an explicit key for reproducible app assets.

Download:

sealos-cli s3 download <bucket> <key> <file> -o json

Delete an object:

sealos-cli s3 delete <bucket> <key> -o json
sealos-cli s3 rm <bucket> <key> -o json

Presign:

sealos-cli s3 presign <bucket> <key> --expires 3600 --method get -o json
sealos-cli s3 presign <bucket> <key> --expires 3600 --method put -o json

--expires must be a positive integer. --method must be get or put.

Response Handling

Every registered action command defaults -o, --output to json in PR #28. Keep using JSON for automation and table only for human inspection.

Credential initialization and rotation are asynchronous around ObjectStorageUser.status. If s3 secret says the user secret is not ready, retry after a few seconds. If rotate-secret returns status: "updating", poll s3 secret before updating applications.

PR #28 Evidence Points

The PR tests assert:

• Top-level help exposes s3.
• s3 --help documents create-bucket, rotate-secret, and presign.
• Subcommands are buckets, create-bucket, get-bucket, update-bucket, delete-bucket, secret, rotate-secret, quota, list, upload, download, delete, and presign.
• Aliases are list-buckets, rm-bucket, and rm.
• All action commands default to JSON output.
• public is not a supported bucket policy alias.