[
https://issues.apache.org/jira/browse/HDDS-16564?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Krishna Kumar Asawa reassigned HDDS-16564:
------------------------------------------
Assignee: Gargi Jaiswal
> [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
> Assignee: Gargi Jaiswal
> Priority: Major
> Labels: ozoneDoc, s3gateway
>
> 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]
