Sealos S3

Identity and Discovery

Owner:
```
sealos-s3
```
(
```
/sealos-s3
```
and bucket, object, policy, credentials, presign, or quota requests).
Class:
```
cloud-local-mutation
```
through
```
sealos-cli s3
```
, with an optional redacted deployment handoff.

Canaries:

S3-PRIVATE-REUSE

S3-CONFIRM-PUBLIC

, and

S3-REDACT-OBJECT

Scope and Boundaries

Accept a project path and object-storage intent. Analyze first, list existing buckets, create or reuse private storage, initialize credentials only when needed, and wire the smallest existing env-key set. Preserve local MinIO/Compose fallback; public policy, rotation, deletion, and destructive object changes remain gated.

Risk and Confirmation

Keep buckets private by default. Ask before public policy, credential rotation for an active app, bucket/object deletion, or replacing storage configuration. Never print secret keys, full credential blocks, kubeconfig, auth files, or copied env values; parse JSON output rather than scraping secrets from tables.

Lifecycle Workflow

For each request, resolve the project, analyze storage need, confirm CLI/auth/region/workspace, list before create/reuse, wait for credential readiness, wire existing keys, prove an authenticated upload/read or presign path, clean temporary objects, and report policy state. Emit request-scoped

success

stopped

, or

error

; the existing private-first workflow remains the domain extension below. Workspace ambiguity, missing credential readiness, or a tracked env target stops the request before mutation.

Request Contract

yaml

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

The ordered action is

analyze -> resolve account/workspace -> list -> create or reuse -> wait for secret -> wire -> object-flow -> cleanup

. Bucket identity, policy, namespace, and env mutation remain request-scoped.

Progressive Disclosure

Load analyzer, bucket, policy, credential, object-flow, and cleanup procedures one level deep when their phase is reached. Keep private policy, confirmation, and redaction canaries visible before the CLI detail.

Output, Stop, and Error States

```
success
```
: bucket identity/policy/readiness, workspace, env key names, authenticated object or presign proof, cleanup state, and redaction status.
```
stopped
```
: ambiguous workspace, unavailable credential readiness, tracked env target, public policy, rotation, replacement, or destructive confirmation boundary with the safe private/presign alternative; no gated operation is claimed.
```
error
```
: analyzer, CLI, policy, credential, object, or env-write step, sanitized diagnostic category, affected artifact, and recovery action with credentials, endpoints, and connection values redacted.

Handoffs

An optional deployment handoff uses the complete tuple below. The receiver re-checks deployment scope and runtime evidence.

yaml

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

Direct S3 requests use

target: none

and keep the same evidence fields.

Verification

Use

analyze-project-s3.mjs

sealos-cli s3

JSON output, authenticated object-flow evidence, and baseline cases

s3-positive-private-round-trip

and

s3-violating-unconfirmed-public-or-rotation

. Verify private policy, env preservation, and redaction before success.

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

Never print secret keys, full S3 credential blocks, or copied env values in the final answer.
Do not overwrite an existing env value without confirming or preserving the old value.
Do not commit
```
.env
```
,
```
.env.local
```
, S3 access keys, secret keys, kubeconfig, or Sealos auth files.
Ask before making a bucket public. Default bucket policy is
```
private
```
.
Ask before destructive operations:
```
s3 delete-bucket
```
,
```
s3 delete
```
, credential rotation for an active app, or replacing app storage configuration.
Use JSON output from
```
sealos-cli
```
by default and parse it instead of scraping table output.
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

git rev-parse --show-toplevel

Run the analyzer when a project directory is available:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

Project signal	Preferred env keys
AWS SDK / S3 generic	`S3_ENDPOINT` , `S3_ACCESS_KEY_ID` , `S3_SECRET_ACCESS_KEY` , `S3_BUCKET`
AWS-style config	`AWS_ACCESS_KEY_ID` , `AWS_SECRET_ACCESS_KEY` , `AWS_REGION` , `S3_BUCKET`
MinIO replacement	existing `MINIO_*` keys or migrate to existing S3 keys only if the app supports them
Upload libraries	the keys read by the adapter/config file

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:

Run a repo script or test that uploads and reads an object if available.
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.
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:

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

Common Tasks

Connect an existing project to Sealos object storage

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

Replace local MinIO for development

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

Upload or share project assets

Confirm the target bucket and object key prefix.

Upload with

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

Use
```
presign
```
for temporary sharing instead of public bucket policy when possible.
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.

sealos-s3

NPX Install

Tags

SKILL.md Content

Sealos S3

Identity and Discovery

Scope and Boundaries

Risk and Confirmation

Lifecycle Workflow

Request Contract

Progressive Disclosure

Output, Stop, and Error States

Handoffs

Verification

Safety Rules

Workflow

1. Resolve the target project

2. Check
`sealos-cli`

3. Choose create or reuse

4. Initialize credentials only when needed

5. Wire the development environment

6. Verify application storage behavior

7. Report the result

Common Tasks

Connect an existing project to Sealos object storage

Replace local MinIO for development

Upload or share project assets

References