Wei-Chiu Chuang created HDDS-16564:
--------------------------------------
Summary: [Docs] Refresh S3 API user guide to match S3 Gateway
implementation
Key: HDDS-16564
URL: https://issues.apache.org/jira/browse/HDDS-16564
Project: Apache Ozone
Issue Type: Improvement
Components: documentation
Reporter: Wei-Chiu Chuang
h2. Problem
The user guide page *S3 API*
(https://ozone.apache.org/docs/next/user-guide/client-interfaces/s3/s3-api) and
in-repo source {{hadoop-hdds/docs/content/interface/S3.md}} are out of date
compared to the S3 Gateway implementation in {{hadoop-ozone/s3gateway}}.
Several APIs are implemented but not listed; several notes describe behavior
that no longer matches the code (or is incomplete).
h2. Scope
* Primary file: {{hadoop-hdds/docs/content/interface/S3.md}} (and {{S3.zh.md}}
if parity required)
* Cross-check against handler chains in {{BucketEndpoint}} / {{ObjectEndpoint}}
and audit actions in {{S3GAction}}
* Related design docs:
[HDDS-13117|https://issues.apache.org/jira/browse/HDDS-13117] (conditional
requests), lifecycle (HDDS-8342), ozone-sts design doc
h2. Items to update
h3. Correct stale or misleading content
# *Conditional requests*: Remove "planned / HDDS-13117" wording; document
*partial* support via {{S3ConditionalRequest}} (GET/HEAD 304, CopyObject source
preconditions, DeleteObject {{If-Match}}, PutObject/CompleteMultipartUpload
{{If-Match}} and {{If-None-Match: *}} only—not arbitrary ETag on create-only).
# *Lifecycle*: Move out of "roadmap / being implemented"; document
GET/PUT/DELETE {{?lifecycle}} (expiration, {{AbortIncompleteMultipartUpload}},
filters/tags)—not transitions/Glacier.
# *ACLs*: Split bucket vs object—{{GetBucketAcl}}/{{PutBucketAcl}} implemented
(user grantees; *Group* → NOT_IMPLEMENTED); {{PutObjectAcl}} NOT_IMPLEMENTED;
{{x-amz-acl}} on PutObject still ignored.
# *GetObject/HeadObject errors*: Re-verify; {{OS3ExceptionMapper}} returns
structured XML—remove or narrow "generic 404 without XML" note if no longer
true.
# *DeleteObject*: Fix note—missing key returns *204 No Content* (AWS idempotent
delete), not a client error; {{If-Match}} on missing key → 412.
# *Multipart auto-abort*: Replace "7 days" global default with OM config
{{ozone.om.open.mpu.expire.threshold}} (default *30d*); 7 days only via
lifecycle rule {{DaysAfterInitiation}}.
# *ListBuckets*: Document {{max-buckets}} + {{continuation-token}} pagination
(unpaginated call still returns all buckets).
# *ListObjects*: Same {{GET /{bucket}}} serves {{list-type=1}} and
{{list-type=2}}; document {{fetch-owner}} behavior for v2.
h3. Add missing supported APIs (new table rows or sections)
# Get/Put/Delete *BucketTagging* ({{?tagging}})
# Get/Put/Delete *BucketLifecycle* ({{?lifecycle}})
# Get/Put *BucketAcl* ({{?acl}})—with group grantee limitation
# *GetObjectAttributes* ({{?attributes}})—note {{Checksum}} / {{versionId}}
gaps per {{ObjectAttributesHandler}}
# *UploadPartCopy* (part upload with {{x-amz-copy-source}})
# *ListDirectoryBuckets* (S3 Express SigV4 {{s3express}} scope on root GET)
# *GetObject* with {{partNumber}}; *Range* GET (206)
# FSO directory PUT (trailing {{/}}, zero body;
{{ozone.s3g.fso.directory.creation.enabled}})
# Link or subsection for *STS* {{AssumeRole}} / {{GetCallerIdentity}} (separate
endpoint)
# *x-amz-expected-bucket-owner* where enforced
h3. Document explicitly NOT implemented (optional "Unsupported" table)
# {{GetBucketLocation}}, {{GetObjectTorrent}}, {{PutObjectAcl}}
# CORS, bucket policy, website, bucket versioning API, Object Lock, S3 Select,
SSE-S3/SSE-KMS headers (keep TDE/Ranger KMS pointer)
h3. Site vs repo parity
# Published site includes *Supported AWS CLI Versions* (v1 1.37+, v2 2.23+,
CRC32 uploads)—add same subsection to {{S3.md}} if missing in repo.
# Repo {{S3.md}} includes *Health check* ({{/health/live}}, {{/health/ready}}
on admin port)—ensure published docs include it.
h3. Minor polish
# Getting started: mention {{./run.sh -d}} / {{OZONE_DATANODES}} alongside
{{docker-compose --scale datanode=3}}.
h2. Acceptance criteria
* {{S3.md}} endpoint tables and "Advanced features" block reflect current
{{s3gateway}} behavior.
* Stale HDDS-13117 "planned" and lifecycle "roadmap" language removed or
qualified.
* English and Chinese S3 interface pages stay in sync (if project policy
requires).
h2. References
* Page:
https://ozone.apache.org/docs/next/user-guide/client-interfaces/s3/s3-api
* Source: {{hadoop-hdds/docs/content/interface/S3.md}}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
