S3 Express Mode

MinIO AIStor supports running in S3 Express Mode, an AWS S3 API surface for ultra-low latency, single-zone storage. This mode enables directory bucket behavior for optimized hierarchical storage structures, implementing the specific directory bucket behaviors documented by AWS.

Add the --api parameter to the MINIO_OPTS parameter list in /etc/default/minio:

# /etc/default/minio
MINIO_OPTS="--api='S3Express' ..."

Append the parameter to the existing list of options passed to the minio process.

S3 Express mode supports the following API operations:

Bucket operations:

• CreateBucket, DeleteBucket
• GetBucketPolicy, PutBucketPolicy, DeleteBucketPolicy
• GetBucketEncryption, PutBucketEncryption, DeleteBucketEncryption
• GetBucketLocation
• ListBuckets

Object operations:

• GetObject, PutObject, DeleteObject
• AppendObject (S3 Express mode only)
• HeadObject, HeadBucket
• GetObjectAttributes
• CopyObject

Multipart operations:

• CreateMultipartUpload
• UploadPart, UploadPartCopy
• CompleteMultipartUpload, AbortMultipartUpload
• ListMultipartUploads, ListParts

Encryption:

• Server-Side Encryption with S3-managed keys (SSE-S3)
• Server-Side Encryption with KMS (SSE-KMS)

The following S3 API operations are rejected with an error when S3 Express mode is enabled. Applications that depend on these operations must use the standard S3 API mode instead.

Bucket operations:

• GetBucketVersioning, PutBucketVersioning
• GetBucketTagging, PutBucketTagging, DeleteBucketTagging
• GetBucketCORS, PutBucketCORS, DeleteBucketCORS
• GetBucketACL, PutBucketACL
• GetObjectLockConfiguration, PutObjectLockConfiguration
• GetBucketReplication, PutBucketReplication, DeleteBucketReplication
• GetBucketNotification, PutBucketNotification
• GetBucketWebsite, DeleteBucketWebsite
• ListObjectVersions
• ListObjects (ListObjectsV1, legacy)

Object operations:

• GetObjectACL, PutObjectACL
• GetObjectTagging, PutObjectTagging, DeleteObjectTagging
• GetObjectRetention, PutObjectRetention
• GetObjectLegalHold, PutObjectLegalHold
• SelectObjectContent (S3 Select)
• RestoreObject

PutBucketWebsite is not supported in any mode. Use IAM policies instead of bucket and object ACLs.

The following MinIO AIStor features are disabled in S3 Express mode:

S3 Express is a newer, more performant API optimized for upload workloads:

• ListObjectsV2 prefix: Prefix must end with /.
• Multipart upload ordering: Parts must be uploaded in sequential order (1, 2, 3, …), enabling optimized write paths.
• Encryption: Supports SSE-S3 and SSE-KMS. Does not support SSE-C (customer-provided keys).
• Part retrieval: The partNumber parameter is not supported on GetObject or HeadObject. You cannot retrieve or inspect an individual part of a multipart object in S3 Express mode.

S3 Express mode supports appending data to an existing object through the AppendObject behavior. Appending is available only when S3 Express mode is enabled.

To append data, issue a PutObject (HTTP PUT) request that includes the x-amz-write-offset-bytes header. Set the header value to the current size of the object in bytes, which is the byte offset at which the new data is appended.

PUT /<bucket>/<object> HTTP/1.1
x-amz-write-offset-bytes: <current-object-size-in-bytes>

<data to append>

Use S3 Express mode when you require AWS S3 Express One Zone API compatibility or your application is built specifically for S3 Express.

Use the standard S3 API mode (the default) when you need replication, tiering, lifecycle transitions, bucket quotas, QoS, or full S3 API compatibility.

S3 Express mode works with all MinIO AIStor deployment architectures: standalone, distributed multi-node, and pooled deployments.

Before enabling S3 Express mode:

1. Remove any existing replication configurations.
2. Remove lifecycle rules with transitions.
3. Remove bucket quotas.
4. Verify that applications use only the supported APIs listed above.