[GitHub] [hadoop] mukund-thakur commented on a change in pull request #2149: HADOOP-13230. S3A to optionally retain directory markers

[GitBox <gi...@apache.org>]

mukund-thakur commented on a change in pull request #2149:
URL: https://github.com/apache/hadoop/pull/2149#discussion_r468427878



##########
File path: hadoop-tools/hadoop-aws/src/site/markdown/tools/hadoop-aws/directory_markers.md
##########
@@ -0,0 +1,416 @@
+<!---
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+  
+   http://www.apache.org/licenses/LICENSE-2.0
+  
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License. See accompanying LICENSE file.
+-->
+
+# Controlling the S3A Directory Marker Behavior
+
+## <a name="compatibility"></a> Critical: this is not backwards compatible!
+
+This document shows how the performance of S3 IO, especially applications
+writing many files (hive) or working with versioned S3 buckets can
+increase performance by changing the S3A directory marker retention policy.
+
+Changing the policy from the default value, `"delete"` _is not backwards compatible_.
+
+Versions of Hadoop which are incompatible with other marker retention policies
+
+-------------------------------------------------------
+|  Branch    | Compatible Since | Future Fix Planned? |
+|------------|------------------|---------------------|
+| Hadoop 2.x |                  | NO                  |
+| Hadoop 3.0 |                  | NO                  |
+| Hadoop 3.1 |                  | Yes                 |
+| Hadoop 3.2 |                  | Yes                 |
+| Hadoop 3.3 |      3.3.1       | Done                |
+-------------------------------------------------------
+
+External Hadoop-based applications should also be assumed to be incompatible
+unless otherwise stated/known.
+
+It is only safe change the directory marker policy if the following
+ conditions are met:
+
+1. You know exactly which applications are writing to and reading from
+   (including backing up) an S3 bucket.
+2. You know all applications which read data from the bucket are as compatible.
+
+### <a name="backups"></a> Applications backing up data.
+
+It is not enough to have a version of Apache Hadoop which is compatible, any
+application which backs up an S3 bucket or copies elsewhere must have an S3
+connector which is compatible. For the Hadoop codebase, that means that if
+distcp is used, it _must_ be from a compatible hadoop version.
+
+### <a name="fallure-mode"></a> How will incompatible applications/versions fail? 
+
+Applications using an incompatible version of the S3A connector will mistake
+directories containing data for empty directories. This means that
+
+* Listing directories/directory trees may exclude files which exist.
+* Queries across the data will miss data files.
+* Renaming a directory to a new location may exclude files underneath.
+
+### <a name="recovery"></a> If an application has updated a directory tree incompatibly-- what can be done?
+
+There's a tool on the hadoop command line, [marker tool](#marker-tool) which can audit
+a bucket/path for markers, and clean up any which were found.

Review comment:
       nit : cleanup any files??




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: common-issues-unsubscribe@hadoop.apache.org
For additional commands, e-mail: common-issues-help@hadoop.apache.org