Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Use S2 as an observable application service instead of an opaque file container.

​
Prerequisites

  • An existing S2 bucket
  • A StackShift API token

​
Workflow

1
Create a managed event subscription for the object events and key patterns the application needs.
2
Pull pending deliveries, process them idempotently, and acknowledge success or request a retry.
3
Use access logs and analytics to investigate traffic, errors, bandwidth, and busy prefixes.
4
Create CSV or JSONL inventory exports when a workload needs a full object manifest.
5
Enable website settings and verify a custom domain when the bucket should serve static content.

​
Managed object events

  • Event types are object.created, object.overwritten, and object.deleted.
  • Subscriptions can filter by object-key prefix and suffix.
  • S2 stores deliveries in a managed queue; clients pull batches and acknowledge each delivery.
  • Acknowledgement can mark processing complete or request another attempt after a recoverable failure.
  • Pull and acknowledgement operations remain tenant- and bucket-authorized through the StackShift control plane.

​
Analytics and access logs

Bucket analytics report stored bytes, object count, request count, errors, bandwidth, and the most active prefixes. The default analytics window is the previous 30 days, or you can provide an RFC 3339 start time. Access logs record the operation, object key, status, bytes in and out, request identifier, access key when available, and occurrence time. Use them to distinguish authentication, quota, application, and service failures.

​
Inventory exports and catalogs

Inventory exports produce CSV or JSONL manifests and can be limited to one prefix. Each export has a durable status, row count, and authenticated download operation. Catalogs expose object metadata through an Iceberg-compatible metadata document. The bounded query API supports selected columns from the object inventory with an optional key-prefix filter and a limit up to 1,000 rows.

​
Static websites and custom domains

Website mode serves the configured index object for root and directory requests and can use a configured error object for missing content. Configure cache-control headers on uploaded objects to control browser and intermediary caching. Custom domains use the StackShift domain-verification flow. After verification, attach the active domain through bucket settings and keep DNS aligned with the target returned by StackShift.

​
Expected result

Object changes can drive durable application work, operators can explain storage activity, and static buckets can be published intentionally.

​
Common failures

  • Processing an event more than once without an idempotency key. Consumers must tolerate delivery retries.
  • Subscribing without a prefix or suffix filter when only one class of objects should trigger work.
  • Enabling website mode before uploading the configured index and error documents.
  • Attaching a custom domain before its ownership verification reaches an active state.

S3 operations and presigned access

Use the supported S3 operations, conditional requests, object metadata, tags, multipart uploads, and presigned URLs.

Versioning, lifecycle, and retention

Protect object history, restore earlier versions, automate aging policies, and prevent protected objects from being deleted too early.

Capacity, monitoring, and recovery

Monitor bucket usage, handle temporary service responses, protect critical objects, and validate application recovery.