| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| | Generated by Apache Maven Doxia at 2021-06-15 |
| | Rendered using Apache Maven Stylus Skin 1.5 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <title>Apache Hadoop Amazon Web Services support – Experimental: Controlling the S3A Directory Marker Behavior</title> |
| <style type="text/css" media="all"> |
| @import url("../../css/maven-base.css"); |
| @import url("../../css/maven-theme.css"); |
| @import url("../../css/site.css"); |
| </style> |
| <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" /> |
| <meta name="Date-Revision-yyyymmdd" content="20210615" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="http://hadoop.apache.org/" id="bannerLeft"> |
| <img src="http://hadoop.apache.org/images/hadoop-logo.jpg" alt="" /> |
| </a> |
| <a href="http://www.apache.org/" id="bannerRight"> |
| <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| <div class="xleft"> |
| <a href="http://www.apache.org/" class="externalLink">Apache</a> |
| > |
| <a href="http://hadoop.apache.org/" class="externalLink">Hadoop</a> |
| > |
| <a href="../../index.html">Apache Hadoop Amazon Web Services support</a> |
| > |
| Experimental: Controlling the S3A Directory Marker Behavior |
| </div> |
| <div class="xright"> <a href="http://wiki.apache.org/hadoop" class="externalLink">Wiki</a> |
| | |
| <a href="https://gitbox.apache.org/repos/asf/hadoop.git" class="externalLink">git</a> |
| |
| | Last Published: 2021-06-15 |
| | Version: 3.3.1 |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| <h5>General</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../index.html">Overview</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/SingleCluster.html">Single Node Setup</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/ClusterSetup.html">Cluster Setup</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/CommandsManual.html">Commands Reference</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/FileSystemShell.html">FileSystem Shell</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/Compatibility.html">Compatibility Specification</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/DownstreamDev.html">Downstream Developer's Guide</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/AdminCompatibilityGuide.html">Admin Compatibility Guide</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/InterfaceClassification.html">Interface Classification</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/filesystem/index.html">FileSystem Specification</a> |
| </li> |
| </ul> |
| <h5>Common</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/CLIMiniCluster.html">CLI Mini Cluster</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/FairCallQueue.html">Fair Call Queue</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/NativeLibraries.html">Native Libraries</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/Superusers.html">Proxy User</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/RackAwareness.html">Rack Awareness</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/SecureMode.html">Secure Mode</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/ServiceLevelAuth.html">Service Level Authorization</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/HttpAuthentication.html">HTTP Authentication</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/CredentialProviderAPI.html">Credential Provider API</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-kms/index.html">Hadoop KMS</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/Tracing.html">Tracing</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/UnixShellGuide.html">Unix Shell Guide</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/registry/index.html">Registry</a> |
| </li> |
| </ul> |
| <h5>HDFS</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsDesign.html">Architecture</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsUserGuide.html">User Guide</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSCommands.html">Commands Reference</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html">NameNode HA With QJM</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithNFS.html">NameNode HA With NFS</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/ObserverNameNode.html">Observer NameNode</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/Federation.html">Federation</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/ViewFs.html">ViewFs</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/ViewFsOverloadScheme.html">ViewFsOverloadScheme</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsSnapshots.html">Snapshots</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsEditsViewer.html">Edits Viewer</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsImageViewer.html">Image Viewer</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsPermissionsGuide.html">Permissions and HDFS</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsQuotaAdminGuide.html">Quotas and HDFS</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/LibHdfs.html">libhdfs (C API)</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/WebHDFS.html">WebHDFS (REST API)</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-hdfs-httpfs/index.html">HttpFS</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/ShortCircuitLocalReads.html">Short Circuit Local Reads</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/CentralizedCacheManagement.html">Centralized Cache Management</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsNfsGateway.html">NFS Gateway</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsRollingUpgrade.html">Rolling Upgrade</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/ExtendedAttributes.html">Extended Attributes</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/TransparentEncryption.html">Transparent Encryption</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsMultihoming.html">Multihoming</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/ArchivalStorage.html">Storage Policies</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/MemoryStorage.html">Memory Storage Support</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/SLGUserGuide.html">Synthetic Load Generator</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSErasureCoding.html">Erasure Coding</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HDFSDiskbalancer.html">Disk Balancer</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsUpgradeDomain.html">Upgrade Domain</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsDataNodeAdminGuide.html">DataNode Admin</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs-rbf/HDFSRouterFederation.html">Router Federation</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/HdfsProvidedStorage.html">Provided Storage</a> |
| </li> |
| </ul> |
| <h5>MapReduce</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapReduceTutorial.html">Tutorial</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapredCommands.html">Commands Reference</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapReduce_Compatibility_Hadoop1_Hadoop2.html">Compatibility with 1.x</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/EncryptedShuffle.html">Encrypted Shuffle</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/PluggableShuffleAndPluggableSort.html">Pluggable Shuffle/Sort</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/DistributedCacheDeploy.html">Distributed Cache Deploy</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/SharedCacheSupport.html">Support for YARN Shared Cache</a> |
| </li> |
| </ul> |
| <h5>MapReduce REST APIs</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/MapredAppMasterRest.html">MR Application Master</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-hs/HistoryServerRest.html">MR History Server</a> |
| </li> |
| </ul> |
| <h5>YARN</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/YARN.html">Architecture</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/YarnCommands.html">Commands Reference</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/CapacityScheduler.html">Capacity Scheduler</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/FairScheduler.html">Fair Scheduler</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceManagerRestart.html">ResourceManager Restart</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceManagerHA.html">ResourceManager HA</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceModel.html">Resource Model</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/NodeLabel.html">Node Labels</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/NodeAttributes.html">Node Attributes</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/WebApplicationProxy.html">Web Application Proxy</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServer.html">Timeline Server</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServiceV2.html">Timeline Service V.2</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/WritingYarnApplications.html">Writing YARN Applications</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/YarnApplicationSecurity.html">YARN Application Security</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/NodeManager.html">NodeManager</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/DockerContainers.html">Running Applications in Docker Containers</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/RuncContainers.html">Running Applications in runC Containers</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/NodeManagerCgroups.html">Using CGroups</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/SecureContainer.html">Secure Containers</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/ReservationSystem.html">Reservation System</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/GracefulDecommission.html">Graceful Decommission</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/OpportunisticContainers.html">Opportunistic Containers</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/Federation.html">YARN Federation</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/SharedCache.html">Shared Cache</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/UsingGpus.html">Using GPU</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/UsingFPGA.html">Using FPGA</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/PlacementConstraints.html">Placement Constraints</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/YarnUI2.html">YARN UI2</a> |
| </li> |
| </ul> |
| <h5>YARN REST APIs</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/WebServicesIntro.html">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/ResourceManagerRest.html">Resource Manager</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/NodeManagerRest.html">Node Manager</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServer.html#Timeline_Server_REST_API_v1">Timeline Server</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/TimelineServiceV2.html#Timeline_Service_v.2_REST_API">Timeline Service V.2</a> |
| </li> |
| </ul> |
| <h5>YARN Service</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/Overview.html">Overview</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/QuickStart.html">QuickStart</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/Concepts.html">Concepts</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/YarnServiceAPI.html">Yarn Service API</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/ServiceDiscovery.html">Service Discovery</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-site/yarn-service/SystemServices.html">System Services</a> |
| </li> |
| </ul> |
| <h5>Hadoop Compatible File Systems</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-aliyun/tools/hadoop-aliyun/index.html">Aliyun OSS</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-aws/tools/hadoop-aws/index.html">Amazon S3</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-azure/index.html">Azure Blob Storage</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-azure-datalake/index.html">Azure Data Lake Storage</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-openstack/index.html">OpenStack Swift</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-cos/cloud-storage/index.html">Tencent COS</a> |
| </li> |
| </ul> |
| <h5>Auth</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-auth/index.html">Overview</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-auth/Examples.html">Examples</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-auth/Configuration.html">Configuration</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-auth/BuildingIt.html">Building</a> |
| </li> |
| </ul> |
| <h5>Tools</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-streaming/HadoopStreaming.html">Hadoop Streaming</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-archives/HadoopArchives.html">Hadoop Archives</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-archive-logs/HadoopArchiveLogs.html">Hadoop Archive Logs</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-distcp/DistCp.html">DistCp</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-gridmix/GridMix.html">GridMix</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-rumen/Rumen.html">Rumen</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-resourceestimator/ResourceEstimator.html">Resource Estimator Service</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-sls/SchedulerLoadSimulator.html">Scheduler Load Simulator</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/Benchmarking.html">Hadoop Benchmarking</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-dynamometer/Dynamometer.html">Dynamometer</a> |
| </li> |
| </ul> |
| <h5>Reference</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/release/">Changelog and Release Notes</a> |
| </li> |
| <li class="none"> |
| <a href="../../../api/index.html">Java API docs</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/UnixShellAPI.html">Unix Shell API</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/Metrics.html">Metrics</a> |
| </li> |
| </ul> |
| <h5>Configuration</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/core-default.xml">core-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs/hdfs-default.xml">hdfs-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-hdfs-rbf/hdfs-rbf-default.xml">hdfs-rbf-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-mapreduce-client/hadoop-mapreduce-client-core/mapred-default.xml">mapred-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-yarn/hadoop-yarn-common/yarn-default.xml">yarn-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-kms/kms-default.html">kms-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-hdfs-httpfs/httpfs-default.html">httpfs-default.xml</a> |
| </li> |
| <li class="none"> |
| <a href="../../../hadoop-project-dist/hadoop-common/DeprecatedProperties.html">Deprecated Properties</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/> |
| </a> |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| <!--- |
| 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. |
| --> |
| <h1>Experimental: Controlling the S3A Directory Marker Behavior</h1> |
| <p>This document discusses an experimental feature of the S3A connector since Hadoop 3.3.1: the ability to retain directory marker objects above paths containing files or subdirectories.</p> |
| <div class="section"> |
| <h2><a name="Critical:_this_is_not_backwards_compatible.21"></a><a name="compatibility"></a> Critical: this is not backwards compatible!</h2> |
| <p>This document shows how the performance of S3 I/O, especially applications creating many files (for example Apache Hive) or working with versioned S3 buckets can increase performance by changing the S3A directory marker retention policy.</p> |
| <p>Changing the policy from the default value, <tt>"delete"</tt> <i>is not backwards compatible</i>.</p> |
| <p>Versions of Hadoop which are incompatible with other marker retention policies, as of August 2020.</p><hr /></div> |
| <div class="section"> |
| <h2><a name="a.7C__Branch____.7C_Compatible_Since_.7C_Supported___________.7C_.7C.E2.80.94.E2.80.94.E2.80.94.E2.80.94.7C.E2.80.94.E2.80.94.E2.80.94.E2.80.94.E2.80.94.E2.80.94.7C.E2.80.94.E2.80.94.E2.80.94.E2.80.94.E2.80.94.E2.80.94.E2.80.94.7C_.7C_Hadoop_2.x_.7C_______n.2Fa________.7C_WONTFIX_____________.7C_.7C_Hadoop_3.0_.7C______check_______.7C_Read-only___________.7C_.7C_Hadoop_3.1_.7C______check_______.7C_Read-only___________.7C_.7C_Hadoop_3.2_.7C______check_______.7C_Read-only___________.7C_.7C_Hadoop_3.3_.7C______3.3.1_______.7C_Done________________.7C"></a>| Branch | Compatible Since | Supported | |————|——————|———————| | Hadoop 2.x | n/a | WONTFIX | | Hadoop 3.0 | check | Read-only | | Hadoop 3.1 | check | Read-only | | Hadoop 3.2 | check | Read-only | | Hadoop 3.3 | 3.3.1 | Done |</h2> |
| <p><i>WONTFIX</i></p> |
| <p>The Hadoop branch-2 line will <i>not</i> be patched.</p> |
| <p><i>Read-only</i></p> |
| <p>These branches have read-only compatibility.</p> |
| <ul> |
| |
| <li>They may list directories with directory markers, and correctly identify when such directories have child entries.</li> |
| <li>They will open files under directories with such markers.</li> |
| </ul> |
| <p>However, they have limitations when writing/deleting directories.</p> |
| <p>Specifically: S3Guard tables may not be correctly updated in all conditions, especially on the partial failure of delete operations. Specifically: they may mistakenly add a tombstone in the dynamoDB table and so future directory/directory tree listings will consider the directory to be nonexistent.</p> |
| <p><i>It is not safe for Hadoop releases before Hadoop 3.3.1 to write to S3 buckets which have directory markers when S3Guard is enabled</i></p></div> |
| <div class="section"> |
| <h2><a name="Verifying_read_compatibility."></a>Verifying read compatibility.</h2> |
| <p>The <tt>s3guard bucket-info</tt> tool <a href="#bucket-info">can be used to verify support</a>. This allows for a command line check of compatibility, including in scripts.</p> |
| <p>External Hadoop-based applications should also be assumed to be incompatible unless otherwise stated/known.</p> |
| <p>It is only safe change the directory marker policy if the following conditions are met:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>You know exactly which applications are writing to and reading from (including backing up) an S3 bucket.</li> |
| <li>You know all applications which read data from the bucket are compatible.</li> |
| </ol> |
| <div class="section"> |
| <h3><a name="Applications_backing_up_data."></a><a name="backups"></a> Applications backing up data.</h3> |
| <p>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 <i>must</i> be from a compatible hadoop version.</p></div> |
| <div class="section"> |
| <h3><a name="How_will_incompatible_applications.2Fversions_fail.3F"></a><a name="fallure-mode"></a> How will incompatible applications/versions fail?</h3> |
| <p>Applications using an incompatible version of the S3A connector will mistake directories containing data for empty directories. This means that:</p> |
| <ul> |
| |
| <li>Listing directories/directory trees may exclude files which exist.</li> |
| <li>Queries across the data will miss data files.</li> |
| <li>Renaming a directory to a new location may exclude files underneath.</li> |
| </ul> |
| <p>The failures are silent: there is no error message, stack trace or other warning that files may have been missed. They simply aren’t found.</p></div> |
| <div class="section"> |
| <h3><a name="If_an_application_has_updated_a_directory_tree_incompatibly.E2.80.93_what_can_be_done.3F"></a><a name="recovery"></a> If an application has updated a directory tree incompatibly– what can be done?</h3> |
| <p>There’s a tool on the hadoop command line, <a href="#marker-tool">marker tool</a> which can audit a bucket/path for markers, and clean up any markers which were found. It can be used to make a bucket compatible with older applications.</p> |
| <p>Now that this is all clear, let’s explain the problem.</p></div></div> |
| <div class="section"> |
| <h2><a name="Background:_Directory_Markers:_what_and_why.3F"></a><a name="background"></a> Background: Directory Markers: what and why?</h2> |
| <p>Amazon S3 is not a filesystem, it is an object store.</p> |
| <p>The S3A connector not only provides a hadoop-compatible API to interact with data in S3, it tries to maintain the filesystem metaphor.</p> |
| <p>One key aspect of the metaphor of a file system is “directories”</p> |
| <div class="section"> |
| <div class="section"> |
| <h4><a name="The_directory_concept"></a>The directory concept</h4> |
| <p>In normal Unix-style filesystems, the “filesystem” is really a “directory and file tree” in which files are always stored in “directories”</p> |
| <ul> |
| |
| <li>A directory may contain zero or more files.</li> |
| <li>A directory may contain zero or more directories “subdirectories”</li> |
| <li>At the base of a filesystem is the “root directory”</li> |
| <li>All files MUST be in a directory “the parent directory”</li> |
| <li>All directories other than the root directory must be in another directory.</li> |
| <li>If a directory contains no files or directories, it is “empty”</li> |
| <li>When a directory is <i>listed</i>, all files and directories in it are enumerated and returned to the caller</li> |
| </ul> |
| <p>The S3A connector emulates this metaphor by grouping all objects which have the same prefix as if they are in the same directory tree.</p> |
| <p>If there are two objects <tt>a/b/file1</tt> and <tt>a/b/file2</tt> then S3A pretends that there is a directory <tt>/a/b</tt> containing two files <tt>file1</tt> and <tt>file2</tt>.</p> |
| <p>The directory itself does not exist.</p> |
| <p>There’s a bit of a complication here.</p></div> |
| <div class="section"> |
| <h4><a name="What_does_mkdirs.28.29_do.3F"></a>What does <tt>mkdirs()</tt> do?</h4> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>In HDFS and other “real” filesystems, when <tt>mkdirs()</tt> is invoked on a path whose parents are all directories, then an <i>empty directory</i> is created.</p> |
| </li> |
| <li> |
| |
| <p>This directory can be probed for “it exists” and listed (an empty list is returned)</p> |
| </li> |
| <li> |
| |
| <p>Files and other directories can be created in it.</p> |
| </li> |
| </ol> |
| <p>Lots of code contains a big assumption here: after you create a directory it exists. They also assume that after files in a directory are deleted, the directory still exists.</p> |
| <p>Given the S3A connector mimics directories just by aggregating objects which share a prefix, how can you have empty directories?</p> |
| <p>The original Hadoop <tt>s3n://</tt> connector created a Directory Marker -any path ending in <tt>_$folder$</tt> was considered to be a sign that a directory existed. A call to <tt>mkdir(s3n://bucket/a/b)</tt> would create a new marker object <tt>a/b_$folder$</tt> .</p> |
| <p>The S3A also has directory markers, but it just appends a “/” to the directory name, so <tt>mkdir(s3a://bucket/a/b)</tt> will create a new marker object <tt>a/b/</tt> .</p> |
| <p>When a file is created under a path, the directory marker is deleted. And when a file is deleted, if it was the last file in the directory, the marker is recreated.</p> |
| <p>And, historically, When a path is listed, if a marker to that path is found, <i>it has been interpreted as an empty directory.</i></p> |
| <p>It is that little detail which is the cause of the incompatibility issues.</p></div></div></div> |
| <div class="section"> |
| <h2><a name="The_Problem_with_Directory_Markers"></a><a name="problem"></a> The Problem with Directory Markers</h2> |
| <p>Creating, deleting and the listing directory markers adds overhead and can slow down applications.</p> |
| <p>Whenever a file is created we have to delete any marker which could exist in parent directory <i>or any parent paths</i>. Rather than do a sequence of probes for parent markers existing, the connector issues a single request to S3 to delete all parents. For example, if a file <tt>/a/b/file1</tt> is created, a multi-object <tt>DELETE</tt> request containing the keys <tt>/a/</tt> and <tt>/a/b/</tt> is issued. If no markers exists, this is harmless.</p> |
| <p>When a file is deleted, a check for the parent directory continuing to exist (i.e. are there sibling files/directories?), and if not a marker is created.</p> |
| <p>This all works well and has worked well for many years.</p> |
| <p>However, it turns out to have some scale problems, especially from the delete call made whenever a file is created.</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>The number of the objects listed in each request is that of the number of parent directories: deeper trees create longer requests.</p> |
| </li> |
| <li> |
| |
| <p>Every single object listed in the delete request is considered to be a write operation.</p> |
| </li> |
| <li> |
| |
| <p>In versioned S3 buckets, tombstone markers are added to the S3 indices even if no object was deleted.</p> |
| </li> |
| <li> |
| |
| <p>There’s also the overhead of actually issuing the request and awaiting the response.</p> |
| </li> |
| </ol> |
| <p>Issue #2 has turned out to cause significant problems on some interactions with large hive tables:</p> |
| <p>Because each object listed in a DELETE call is treated as one operation, and there is (as of summer 2020) a limit of 3500 write requests/second in a directory tree. When writing many files to a deep directory tree, it is the delete calls which create throttling problems.</p> |
| <p>The tombstone markers have follow-on consequences -it makes listings against S3 versioned buckets slower. This can have adverse effects on those large directories, again.</p></div> |
| <div class="section"> |
| <h2><a name="Strategies_to_avoid_marker-related_problems."></a><a name="solutions"></a> Strategies to avoid marker-related problems.</h2> |
| <div class="section"> |
| <h3><a name="Presto:_every_path_is_a_directory"></a>Presto: every path is a directory</h3> |
| <p>In the Presto <a class="externalLink" href="https://prestodb.io/docs/current/connector/hive.html#amazon-s3-configuration">S3 connector</a>, <tt>mkdirs()</tt> is a no-op. Whenever it lists any path which isn’t an object or a prefix of one more more objects, it returns an empty listing. That is:; by default, every path is an empty directory.</p> |
| <p>Provided no code probes for a directory existing and fails if it is there, this is very efficient. That’s a big requirement however, -one Presto can pull off because they know how their file uses data in S3.</p></div> |
| <div class="section"> |
| <h3><a name="Hadoop_3.3.1.2B:_marker_deletion_is_now_optional"></a>Hadoop 3.3.1+: marker deletion is now optional</h3> |
| <p>From Hadoop 3.3.1 onwards, the S3A client can be configured to skip deleting directory markers when creating files under paths. This removes all scalability problems caused by deleting these markers -however, it is achieved at the expense of backwards compatibility.</p></div></div> |
| <div class="section"> |
| <h2><a name="Controlling_marker_retention_with_fs.s3a.directory.marker.retention"></a><a name="marker-retention"></a> Controlling marker retention with <tt>fs.s3a.directory.marker.retention</tt></h2> |
| <p>There is now an option <tt>fs.s3a.directory.marker.retention</tt> which controls how markers are managed when new files are created</p> |
| <p><i>Default</i> <tt>delete</tt>: a request is issued to delete any parental directory markers whenever a file or directory is created.</p> |
| <p><i>New</i> <tt>keep</tt>: No delete request is issued. Any directory markers which exist are not deleted. This is <i>not</i> backwards compatible</p> |
| <p><i>New</i> <tt>authoritative</tt>: directory markers are deleted <i>except for files created in “authoritative” directories</i>. This is backwards compatible <i>outside authoritative directories</i>.</p> |
| <p>Until now, the notion of an “authoritative” directory has only been used as a performance optimization for deployments where it is known that all Applications are using the same S3Guard metastore when writing and reading data. In such a deployment, if it is also known that all applications are using a compatible version of the s3a connector, then they can switch to the higher-performance mode for those specific directories.</p> |
| <p>Only the default setting, <tt>fs.s3a.directory.marker.retention = delete</tt> is compatible with every shipping Hadoop releases.</p></div> |
| <div class="section"> |
| <h2><a name="Directory_Markers_and_S3Guard"></a><a name="s3guard"></a> Directory Markers and S3Guard</h2> |
| <p>Applications which interact with S3A in S3A clients with S3Guard enabled still create and delete markers. There’s no attempt to skip operations, such as by having <tt>mkdirs()</tt>create entries in the DynamoDB table but not the store. Having the client always update S3 ensures that other applications and clients do (eventually) see the changes made by the “guarded” application.</p> |
| <p>When S3Guard is configured to treat some directories as <a href="s3guard.html#authoritative">Authoritative</a> then an S3A connector with a retention policy of <tt>fs.s3a.directory.marker.retention</tt> of <tt>authoritative</tt> will omit deleting markers in authoritative directories.</p> |
| <p><i>Note</i> there may be further changes in directory semantics in “authoritative mode”; only use in managed applications where all clients are using the same version of hadoop, and configured consistently.</p> |
| <p>After the directory marker feature <a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-13230">HADOOP-13230</a> was added, issues related to S3Guard integration surfaced:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>The incremental update of the S3Guard table was inserting tombstones over directories as the markers were deleted, hiding files underneath. This happened during directory <tt>rename()</tt> and <tt>delete()</tt>.</li> |
| <li>The update of the S3Guard table after a partial failure of a bulk delete operation would insert tombstones in S3Guard records of successfully deleted markers, irrespective of the directory status.</li> |
| </ol> |
| <p>Issue #1 is unique to Hadoop branch 3.3; however issue #2 is s critical part of the S3Guard consistency handling.</p> |
| <p>Both issues have been fixed in Hadoop 3.3.x, in <a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-17244">HADOOP-17244</a></p> |
| <p>Issue #2, delete failure handling, is not easily backported and is not likely to be backported.</p> |
| <p>Accordingly: Hadoop releases with read-only compatibility must not be used to rename or delete directories where markers are retained <i>when S3Guard is enabled.</i></p></div> |
| <div class="section"> |
| <h2><a name="Verifying_marker_policy_with_s3guard_bucket-info"></a><a name="bucket-info"></a> Verifying marker policy with <tt>s3guard bucket-info</tt></h2> |
| <p>The <tt>bucket-info</tt> command has been enhanced to support verification from the command line of bucket policies via the <tt>-marker</tt> option</p> |
| <table border="0" class="bodyTable"> |
| <thead> |
| |
| <tr class="a"> |
| <th> option </th> |
| <th> verifies </th></tr> |
| </thead><tbody> |
| |
| <tr class="b"> |
| <td> <tt>-markers aware</tt> </td> |
| <td> the hadoop release is “aware” of directory markers </td></tr> |
| <tr class="a"> |
| <td> <tt>-markers delete</tt> </td> |
| <td> directory markers are deleted </td></tr> |
| <tr class="b"> |
| <td> <tt>-markers keep</tt> </td> |
| <td> directory markers are kept (not backwards compatible) </td></tr> |
| <tr class="a"> |
| <td> <tt>-markers authoritative</tt> </td> |
| <td> directory markers are kept in authoritative paths </td></tr> |
| </tbody> |
| </table> |
| <p>All releases of Hadoop which have been updated to be marker aware will support the <tt>-markers aware</tt> option.</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>Updated releases which do not support switching marker retention policy will also support the <tt>-markers delete</tt> option.</li> |
| </ol> |
| <p>Example: <tt>s3guard bucket-info -markers aware</tt> on a compatible release.</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard bucket-info -markers aware s3a://landsat-pds/ |
| Filesystem s3a://landsat-pds |
| Location: us-west-2 |
| Filesystem s3a://landsat-pds is not using S3Guard |
| |
| ... |
| |
| Security |
| Delegation token support is disabled |
| |
| The directory marker policy is "delete" |
| |
| The S3A connector is compatible with buckets where directory markers are not deleted |
| Available Policies: delete, keep, authoritative |
| </pre></div></div> |
| |
| <p>The same command will fail on older releases, because the <tt>-markers</tt> option is unknown</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard bucket-info -markers aware s3a://landsat-pds/ |
| Illegal option -markers |
| Usage: hadoop bucket-info [OPTIONS] s3a://BUCKET |
| provide/check S3Guard information about a specific bucket |
| |
| Common options: |
| -guarded - Require S3Guard |
| -unguarded - Force S3Guard to be disabled |
| -auth - Require the S3Guard mode to be "authoritative" |
| -nonauth - Require the S3Guard mode to be "non-authoritative" |
| -magic - Require the S3 filesystem to be support the "magic" committer |
| -encryption -require {none, sse-s3, sse-kms} - Require encryption policy |
| |
| When possible and not overridden by more specific options, metadata |
| repository information will be inferred from the S3A URL (if provided) |
| |
| Generic options supported are: |
| -conf <config file> - specify an application configuration file |
| -D <property=value> - define a value for a given property |
| |
| 2020-08-12 16:47:16,579 [main] INFO util.ExitUtil (ExitUtil.java:terminate(210)) - Exiting with status 42: Illegal option -markers |
| </pre></div></div> |
| |
| <p>A specific policy check verifies that the connector is configured as desired</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard bucket-info -markers delete s3a://landsat-pds/ |
| Filesystem s3a://landsat-pds |
| Location: us-west-2 |
| Filesystem s3a://landsat-pds is not using S3Guard |
| |
| ... |
| |
| The directory marker policy is "delete" |
| </pre></div></div> |
| |
| <p>When probing for a specific policy, the error code “46” is returned if the active policy does not match that requested:</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard bucket-info -markers keep s3a://landsat-pds/ |
| Filesystem s3a://landsat-pds |
| Location: us-west-2 |
| Filesystem s3a://landsat-pds is not using S3Guard |
| |
| ... |
| |
| Security |
| Delegation token support is disabled |
| |
| The directory marker policy is "delete" |
| |
| 2020-08-12 17:14:30,563 [main] INFO util.ExitUtil (ExitUtil.java:terminate(210)) - Exiting with status 46: 46: Bucket s3a://landsat-pds: required marker policy is "keep" but actual policy is "delete" |
| </pre></div></div> |
| </div> |
| <div class="section"> |
| <h2><a name="The_marker_tool:hadoop_s3guard_markers"></a><a name="marker-tool"></a> The marker tool:<tt>hadoop s3guard markers</tt></h2> |
| <p>The marker tool aims to help migration by scanning/auditing directory trees for surplus markers, and for optionally deleting them. Leaf-node markers for empty directories are not considered surplus and will be retained.</p> |
| <p>Syntax</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard markers -verbose -nonauth |
| markers (-audit | -clean) [-min <count>] [-max <count>] [-out <filename>] [-limit <limit>] [-nonauth] [-verbose] <PATH> |
| View and manipulate S3 directory markers |
| |
| </pre></div></div> |
| |
| <p><i>Options</i></p> |
| <table border="0" class="bodyTable"> |
| <thead> |
| |
| <tr class="a"> |
| <th> Option </th> |
| <th> Meaning </th></tr> |
| </thead><tbody> |
| |
| <tr class="b"> |
| <td> <tt>-audit</tt> </td> |
| <td> Audit the path for surplus markers </td></tr> |
| <tr class="a"> |
| <td> <tt>-clean</tt> </td> |
| <td> Clean all surplus markers under a path </td></tr> |
| <tr class="b"> |
| <td> <tt>-min <count></tt> </td> |
| <td> Minimum number of markers an audit must find (default: 0) </td></tr> |
| <tr class="a"> |
| <td> <tt>-max <count>]</tt> </td> |
| <td> Minimum number of markers an audit must find (default: 0) </td></tr> |
| <tr class="b"> |
| <td> <tt>-limit <count>]</tt> </td> |
| <td> Limit the number of objects to scan </td></tr> |
| <tr class="a"> |
| <td> <tt>-nonauth</tt> </td> |
| <td> Only consider markers in non-authoritative paths as errors </td></tr> |
| <tr class="b"> |
| <td> <tt>-out <filename></tt> </td> |
| <td> Save a list of all markers found to the nominated file </td></tr> |
| <tr class="a"> |
| <td> <tt>-verbose</tt> </td> |
| <td> Verbose output </td></tr> |
| </tbody> |
| </table> |
| <p><i>Exit Codes</i></p> |
| <table border="0" class="bodyTable"> |
| <thead> |
| |
| <tr class="a"> |
| <th> Code </th> |
| <th> Meaning </th></tr> |
| </thead><tbody> |
| |
| <tr class="b"> |
| <td> 0 </td> |
| <td> Success </td></tr> |
| <tr class="a"> |
| <td> 3 </td> |
| <td> interrupted -the value of <tt>-limit</tt> was reached </td></tr> |
| <tr class="b"> |
| <td> 42 </td> |
| <td> Usage </td></tr> |
| <tr class="a"> |
| <td> 46 </td> |
| <td> Markers were found (see HTTP “406”, “unacceptable”) </td></tr> |
| </tbody> |
| </table> |
| <p>All other non-zero status code also indicate errors of some form or other.</p> |
| <div class="section"> |
| <h3><a name="markers_-audit"></a><a name="marker-tool-report"></a><tt>markers -audit</tt></h3> |
| <p>Audit the path and fail if any markers were found.</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard markers -limit 8000 -audit s3a://landsat-pds/ |
| |
| The directory marker policy of s3a://landsat-pds is "Delete" |
| 2020-08-05 13:42:56,079 [main] INFO tools.MarkerTool (DurationInfo.java:<init>(77)) - Starting: marker scan s3a://landsat-pds/ |
| Scanned 1,000 objects |
| Scanned 2,000 objects |
| Scanned 3,000 objects |
| Scanned 4,000 objects |
| Scanned 5,000 objects |
| Scanned 6,000 objects |
| Scanned 7,000 objects |
| Scanned 8,000 objects |
| Limit of scan reached - 8,000 objects |
| 2020-08-05 13:43:01,184 [main] INFO tools.MarkerTool (DurationInfo.java:close(98)) - marker scan s3a://landsat-pds/: duration 0:05.107s |
| No surplus directory markers were found under s3a://landsat-pds/ |
| Listing limit reached before completing the scan |
| 2020-08-05 13:43:01,187 [main] INFO util.ExitUtil (ExitUtil.java:terminate(210)) - Exiting with status 3: |
| </pre></div></div> |
| |
| <p>Here the scan reached its object limit before completing the audit; the exit code of 3, “interrupted” indicates this.</p> |
| <p>Example: a verbose audit of a bucket whose policy if authoritative -it is not an error if markers are found under the path <tt>/tables</tt>.</p> |
| |
| <div> |
| <div> |
| <pre class="source">> bin/hadoop s3guard markers -audit s3a://london/ |
| |
| 2020-08-05 18:29:16,473 [main] INFO impl.DirectoryPolicyImpl (DirectoryPolicyImpl.java:getDirectoryPolicy(143)) - Directory markers will be kept on authoritative paths |
| The directory marker policy of s3a://london is "Authoritative" |
| Authoritative path list is "/tables" |
| 2020-08-05 18:29:19,186 [main] INFO tools.MarkerTool (DurationInfo.java:<init>(77)) - Starting: marker scan s3a://london/ |
| 2020-08-05 18:29:21,610 [main] INFO tools.MarkerTool (DurationInfo.java:close(98)) - marker scan s3a://london/: duration 0:02.425s |
| Listed 8 objects under s3a://london/ |
| |
| Found 3 surplus directory markers under s3a://london/ |
| s3a://london/tables |
| s3a://london/tables/tables-4 |
| s3a://london/tables/tables-4/tables-5 |
| Found 5 empty directory 'leaf' markers under s3a://london/ |
| s3a://london/tables/tables-2 |
| s3a://london/tables/tables-3 |
| s3a://london/tables/tables-4/tables-5/06 |
| s3a://london/tables2 |
| s3a://london/tables3 |
| These are required to indicate empty directories |
| Surplus markers were found -failing audit |
| 2020-08-05 18:29:21,614 [main] INFO util.ExitUtil (ExitUtil.java:terminate(210)) - Exiting with status 46: |
| </pre></div></div> |
| |
| <p>This fails because surplus markers were found. This S3A bucket would <i>NOT</i> be safe for older Hadoop versions to use.</p> |
| <p>The <tt>-nonauth</tt> option does not treat markers under authoritative paths as errors:</p> |
| |
| <div> |
| <div> |
| <pre class="source">bin/hadoop s3guard markers -nonauth -audit s3a://london/ |
| |
| 2020-08-05 18:31:16,255 [main] INFO impl.DirectoryPolicyImpl (DirectoryPolicyImpl.java:getDirectoryPolicy(143)) - Directory markers will be kept on authoritative paths |
| The directory marker policy of s3a://london is "Authoritative" |
| Authoritative path list is "/tables" |
| 2020-08-05 18:31:19,210 [main] INFO tools.MarkerTool (DurationInfo.java:<init>(77)) - Starting: marker scan s3a://london/ |
| 2020-08-05 18:31:22,240 [main] INFO tools.MarkerTool (DurationInfo.java:close(98)) - marker scan s3a://london/: duration 0:03.031s |
| Listed 8 objects under s3a://london/ |
| |
| Found 3 surplus directory markers under s3a://london/ |
| s3a://london/tables/ |
| s3a://london/tables/tables-4/ |
| s3a://london/tables/tables-4/tables-5/ |
| Found 5 empty directory 'leaf' markers under s3a://london/ |
| s3a://london/tables/tables-2/ |
| s3a://london/tables/tables-3/ |
| s3a://london/tables/tables-4/tables-5/06/ |
| s3a://london/tables2/ |
| s3a://london/tables3/ |
| These are required to indicate empty directories |
| |
| Ignoring 3 markers in authoritative paths |
| </pre></div></div> |
| |
| <p>All of this S3A bucket <i>other</i> than the authoritative path <tt>/tables</tt> will be safe for incompatible Hadoop releases to to use.</p></div> |
| <div class="section"> |
| <h3><a name="markers_clean"></a><a name="marker-tool-clean"></a><tt>markers clean</tt></h3> |
| <p>The <tt>markers clean</tt> command will clean the directory tree of all surplus markers. The <tt>-verbose</tt> option prints more detail on the operation as well as some IO statistics</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop s3guard markers -clean -verbose s3a://london/ |
| |
| 2020-08-05 18:33:25,303 [main] INFO impl.DirectoryPolicyImpl (DirectoryPolicyImpl.java:getDirectoryPolicy(143)) - Directory markers will be kept on authoritative paths |
| The directory marker policy of s3a://london is "Authoritative" |
| Authoritative path list is "/tables" |
| 2020-08-05 18:33:28,511 [main] INFO tools.MarkerTool (DurationInfo.java:<init>(77)) - Starting: marker scan s3a://london/ |
| Directory Marker tables |
| Directory Marker tables/tables-2/ |
| Directory Marker tables/tables-3/ |
| Directory Marker tables/tables-4/ |
| Directory Marker tables/tables-4/tables-5/ |
| Directory Marker tables/tables-4/tables-5/06/ |
| Directory Marker tables2/ |
| Directory Marker tables3/ |
| 2020-08-05 18:33:31,685 [main] INFO tools.MarkerTool (DurationInfo.java:close(98)) - marker scan s3a://london/: duration 0:03.175s |
| Listed 8 objects under s3a://london/ |
| |
| Found 3 surplus directory markers under s3a://london/ |
| s3a://london/tables/ |
| s3a://london/tables/tables-4/ |
| s3a://london/tables/tables-4/tables-5/ |
| Found 5 empty directory 'leaf' markers under s3a://london/ |
| s3a://london/tables/tables-2/ |
| s3a://london/tables/tables-3/ |
| s3a://london/tables/tables-4/tables-5/06/ |
| s3a://london/tables2/ |
| s3a://london/tables3/ |
| These are required to indicate empty directories |
| |
| 3 markers to delete in 1 page of 250 keys/page |
| 2020-08-05 18:33:31,688 [main] INFO tools.MarkerTool (DurationInfo.java:<init>(77)) - Starting: Deleting markers |
| 2020-08-05 18:33:31,812 [main] INFO tools.MarkerTool (DurationInfo.java:close(98)) - Deleting markers: duration 0:00.124s |
| |
| Storage Statistics for s3a://london |
| |
| op_get_file_status 1 |
| object_delete_requests 1 |
| object_list_requests 2 |
| </pre></div></div> |
| |
| <p>The <tt>markers -clean</tt> command <i>does not</i> delete markers above empty directories -only those which have files underneath. If invoked on a path, it will clean up the directory tree into a state where it is safe for older versions of Hadoop to interact with.</p> |
| <p>Note that if invoked with a <tt>-limit</tt> value, surplus markers found during the scan will be removed, even though the scan will be considered a failure due to the limit being reached.</p></div></div> |
| <div class="section"> |
| <h2><a name="Advanced_Topics"></a><a name="advanced-topics"></a> Advanced Topics</h2> |
| <div class="section"> |
| <h3><a name="Probing_for_retention_via_PathCapabilities_and_StreamCapabilities"></a><a name="pathcapabilities"></a> Probing for retention via <tt>PathCapabilities</tt> and <tt>StreamCapabilities</tt></h3> |
| <p>An instance of the filesystem can be probed for its directory marker retention ability/ policy can be probed for through the <tt>org.apache.hadoop.fs.PathCapabilities</tt> interface, which all FileSystem classes have supported since Hadoop 3.3.</p> |
| <table border="0" class="bodyTable"> |
| <thead> |
| |
| <tr class="a"> |
| <th> Probe </th> |
| <th> Meaning </th></tr> |
| </thead><tbody> |
| |
| <tr class="b"> |
| <td> <tt>fs.s3a.capability.directory.marker.aware</tt> </td> |
| <td> Does the filesystem support surplus directory markers? </td></tr> |
| <tr class="a"> |
| <td> <tt>fs.s3a.capability.directory.marker.policy.delete</tt> </td> |
| <td> Is the bucket policy “delete”? </td></tr> |
| <tr class="b"> |
| <td> <tt>fs.s3a.capability.directory.marker.policy.keep</tt> </td> |
| <td> Is the bucket policy “keep”? </td></tr> |
| <tr class="a"> |
| <td> <tt>fs.s3a.capability.directory.marker.policy.authoritative</tt> </td> |
| <td> Is the bucket policy “authoritative”? </td></tr> |
| <tr class="b"> |
| <td> <tt>fs.s3a.capability.directory.marker.action.delete</tt> </td> |
| <td> If a file was created at this path, would directory markers be deleted? </td></tr> |
| <tr class="a"> |
| <td> <tt>fs.s3a.capability.directory.marker.action.keep</tt> </td> |
| <td> If a file was created at this path, would directory markers be retained? </td></tr> |
| </tbody> |
| </table> |
| <p>The probe <tt>fs.s3a.capability.directory.marker.aware</tt> allows for a filesystem to be probed to determine if its file listing policy is “aware” of directory marker retention -that is: can this s3a client safely work with S3 buckets where markers have not been deleted.</p> |
| <p>The <tt>fs.s3a.capability.directory.marker.policy.</tt> probes return the active policy for the bucket.</p> |
| <p>The two <tt>fs.s3a.capability.directory.marker.action.</tt> probes dynamically query the marker retention behavior of a specific path. That is: if a file was created at that location, would ancestor directory markers be kept or deleted?</p> |
| <p>The <tt>S3AFileSystem</tt> class also implements the <tt>org.apache.hadoop.fs.StreamCapabilities</tt> interface, which can be used to probe for marker awareness via the <tt>fs.s3a.capability.directory.marker.aware</tt> capability.</p> |
| <p>Again, this will be true if-and-only-if the S3A connector is safe to work with S3A buckets/paths where directories are retained.</p> |
| <p>*If an S3A instance, probed by <tt>PathCapabilities</tt> or <tt>StreamCapabilities</tt> for the capability <tt>fs.s3a.capability.directory.marker.aware</tt> and it returns false, <i>it is not safe to be used with S3A paths where markers have been retained</i>.</p> |
| <p>This is programmatic probe -however it can be accessed on the command line via the external <a class="externalLink" href="https://github.com/steveloughran/cloudstore"><tt>cloudstore</tt></a> tool:</p> |
| |
| <div> |
| <div> |
| <pre class="source">> hadoop jar cloudstore-1.0.jar pathcapability fs.s3a.capability.directory.marker.aware s3a://london/ |
| |
| Probing s3a://london/ for capability fs.s3a.capability.directory.marker.aware |
| |
| Using filesystem s3a://london |
| Path s3a://london/ has capability fs.s3a.capability.directory.marker.aware |
| </pre></div></div> |
| |
| <p>If the exit code of the command is <tt>0</tt>, then the S3A is safe to work with buckets where markers have not been deleted.</p> |
| <p>The same tool can be used to dynamically probe for the policy.</p> |
| <p>Take a bucket with a retention policy of “authoritative” -only paths under <tt>/tables</tt> will have markers retained.</p> |
| |
| <div> |
| <div> |
| <pre class="source"> <property> |
| <name>fs.s3a.bucket.london.directory.marker.retention</name> |
| <value>authoritative</value> |
| </property> |
| <property> |
| <name>fs.s3a.bucket.london.authoritative.path</name> |
| <value>/tables</value> |
| </property>``` |
| </pre></div></div> |
| |
| <p>With this policy the path capability <tt>fs.s3a.capability.directory.marker.action.keep</tt> will hold under the path <tt>s3a://london/tables</tt></p> |
| |
| <div> |
| <div> |
| <pre class="source">bin/hadoop jar cloudstore-1.0.jar pathcapability fs.s3a.capability.directory.marker.action.keep s3a://london/tables |
| Probing s3a://london/tables for capability fs.s3a.capability.directory.marker.action.keep |
| 2020-08-11 22:03:31,658 [main] INFO impl.DirectoryPolicyImpl (DirectoryPolicyImpl.java:getDirectoryPolicy(143)) |
| - Directory markers will be kept on authoritative paths |
| Using filesystem s3a://london |
| Path s3a://london/tables has capability fs.s3a.capability.directory.marker.action.keep |
| </pre></div></div> |
| |
| <p>However it will not hold for other paths, so indicating that older Hadoop versions will be safe to work with data written there by this S3A client.</p> |
| |
| <div> |
| <div> |
| <pre class="source">bin/hadoop jar cloudstore-1.0.jar pathcapability fs.s3a.capability.directory.marker.action.keep s3a://london/tempdir |
| Probing s3a://london/tempdir for capability fs.s3a.capability.directory.marker.action.keep |
| 2020-08-11 22:06:56,300 [main] INFO impl.DirectoryPolicyImpl (DirectoryPolicyImpl.java:getDirectoryPolicy(143)) |
| - Directory markers will be kept on authoritative paths |
| Using filesystem s3a://london |
| Path s3a://london/tempdir lacks capability fs.s3a.capability.directory.marker.action.keep |
| 2020-08-11 22:06:56,308 [main] INFO util.ExitUtil (ExitUtil.java:terminate(210)) - Exiting with status -1: |
| </pre></div></div> |
| </div></div> |
| <div class="section"> |
| <h2><a name="Glossary"></a><a name="glossary"></a> Glossary</h2> |
| <div class="section"> |
| <div class="section"> |
| <h4><a name="Directory_Marker"></a>Directory Marker</h4> |
| <p>An object in an S3 bucket with a trailing “/”, used to indicate that there is a directory at that location. These are necessary to maintain expectations about directories in an object store:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>After <tt>mkdirs(path)</tt>, <tt>exists(path)</tt> holds.</li> |
| <li>After <tt>rm(path/*)</tt>, <tt>exists(path)</tt> holds.</li> |
| </ol> |
| <p>In previous releases of Hadoop, the marker created by a <tt>mkdirs()</tt> operation was deleted after a file was created. Rather than make a slow HEAD probe + optional marker DELETE of every parent path element, HADOOP-13164 switched to enumerating all parent paths and issuing a single bulk DELETE request. This is faster under light load, but as each row in the delete consumes one write operation on the allocated IOPs of that bucket partition, creates load issues when many worker threads/processes are writing to files. This problem is bad on Apache Hive as: * The hive partition structure places all files within the same S3 partition. * As they are deep structures, there are many parent entries to include in the bulk delete calls. * It’s creating a lot temporary files, and still uses rename to commit output.</p> |
| <p>Apache Spark has less of an issue when an S3A committer is used -although the partition structure is the same, the delayed manifestation of output files reduces load.</p></div> |
| <div class="section"> |
| <h4><a name="Leaf_Marker"></a>Leaf Marker</h4> |
| <p>A directory marker which has not files or directory marker objects underneath. It genuinely represents an empty directory.</p></div> |
| <div class="section"> |
| <h4><a name="Surplus_Marker"></a>Surplus Marker</h4> |
| <p>A directory marker which is above one or more files, and so is superfluous. These are the markers which were traditionally deleted; now it is optional.</p> |
| <p>Older versions of Hadoop mistake such surplus markers as Leaf Markers.</p></div> |
| <div class="section"> |
| <h4><a name="Versioned_Bucket"></a>Versioned Bucket</h4> |
| <p>An S3 Bucket which has Object Versioning enabled.</p> |
| <p>This provides a backup and recovery mechanism for data within the same bucket: older objects can be listed and restored through the AWS S3 console and some applications.</p></div></div></div> |
| <div class="section"> |
| <h2><a name="References"></a>References</h2><!-- if extending, keep JIRAs separate, have them in numerical order; the rest in lexical.` --> |
| |
| <ul> |
| |
| <li> |
| |
| <p><a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-13164">HADOOP-13164</a>. <i>Optimize S3AFileSystem::deleteUnnecessaryFakeDirectories.</i></p> |
| </li> |
| <li> |
| |
| <p><a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-13230">HADOOP-13230</a>. <i>S3A to optionally retain directory markers</i></p> |
| </li> |
| <li> |
| |
| <p><a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-16090">HADOOP-16090</a>. <i>S3A Client to add explicit support for versioned stores.</i></p> |
| </li> |
| <li> |
| |
| <p><a class="externalLink" href="https://issues.apache.org/jira/browse/HADOOP-16823">HADOOP-16823</a>. <i>Large DeleteObject requests are their own Thundering Herd</i></p> |
| </li> |
| <li> |
| |
| <p><a class="externalLink" href="https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html">Object Versioning</a>. <i>Using versioning</i></p> |
| </li> |
| <li> |
| |
| <p><a class="externalLink" href="https://docs.aws.amazon.com/AmazonS3/latest/dev/optimizing-performance.html">Optimizing Performance</a>. <i>Best Practices Design Patterns: Optimizing Amazon S3 Performance</i></p> |
| </li> |
| </ul></div> |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright"> |
| © 2008-2021 |
| Apache Software Foundation |
| |
| - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>. |
| Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation. |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |
