Hadoop-AWS module: Integration with Amazon Web Services

Directory Marker Compatibility

1. This release can safely list/index/read S3 buckets where “empty directory” markers are retained.

2. This release can be configured to retain these directory makers at the expense of being backwards incompatible.

Consult Controlling the S3A Directory Marker Behavior for full details.

Other S3 Connectors

There other Hadoop connectors to S3. Only S3A is actively maintained by the Hadoop project itself.

1. Apache’s Hadoop’s original s3:// client. This is no longer included in Hadoop.
2. Amazon EMR’s s3:// client. This is from the Amazon EMR team, who actively maintain it.
3. Apache’s Hadoop’s s3n: filesystem client. This connector is no longer available: users must migrate to the newer s3a: client.

Warning #1: Directories are mimicked

The S3A clients mimics directories by:

1. Creating a stub entry after a mkdirs call, deleting it when a file is added anywhere underneath
2. When listing a directory, searching for all objects whose path starts with the directory path, and returning them as the listing.
3. When renaming a directory, taking such a listing and asking S3 to copying the individual objects to new objects with the destination filenames.
4. When deleting a directory, taking such a listing and deleting the entries in batches.
5. When renaming or deleting directories, taking such a listing and working on the individual files.

Here are some of the consequences:

• Directories may lack modification times. Parts of Hadoop relying on this can have unexpected behaviour. E.g. the AggregatedLogDeletionService of YARN will not remove the appropriate logfiles.
• Directory listing can be slow. Use listFiles(path, recursive) for high performance recursive listings whenever possible.
• It is possible to create files under files if the caller tries hard.
• The time to rename a directory is proportional to the number of files underneath it (directory or indirectly) and the size of the files. (The copy is executed inside the S3 storage, so the time is independent of the bandwidth from client to S3).
• Directory renames are not atomic: they can fail partway through, and callers cannot safely rely on atomic renames as part of a commit algorithm.
• Directory deletion is not atomic and can fail partway through.

The final three issues surface when using S3 as the immediate destination of work, as opposed to HDFS or other “real” filesystem.

The S3A committers are the sole mechanism available to safely save the output of queries directly into S3 object stores through the S3A filesystem.

Warning #2: Object stores have different authorization models

The object authorization model of S3 is much different from the file authorization model of HDFS and traditional file systems. The S3A client simply reports stub information from APIs that would query this metadata:

• File owner is reported as the current user.
• File group also is reported as the current user. Prior to Apache Hadoop 2.8.0, file group was reported as empty (no group associated), which is a potential incompatibility problem for scripts that perform positional parsing of shell output and other clients that expect to find a well-defined group.
• Directory permissions are reported as 777.
• File permissions are reported as 666.

S3A does not really enforce any authorization checks on these stub permissions. Users authenticate to an S3 bucket using AWS credentials. It’s possible that object ACLs have been defined to enforce authorization at the S3 side, but this happens entirely within the S3 service, not within the S3A implementation.

Warning #4: Your AWS credentials are very, very valuable

Your AWS credentials not only pay for services, they offer read and write access to the data. Anyone with the credentials can not only read your datasets —they can delete them.

Do not inadvertently share these credentials through means such as:

1. Checking in to SCM any configuration files containing the secrets.
2. Logging them to a console, as they invariably end up being seen.
3. Including the secrets in bug reports.
4. Logging the AWS_ environment variables.

If you do any of these: change your credentials immediately!

Authentication properties

<property>
  <name>fs.s3a.access.key</name>
  <description>AWS access key ID.
   Omit for IAM role-based or provider-based authentication.</description>
</property>

<property>
  <name>fs.s3a.secret.key</name>
  <description>AWS secret key.
   Omit for IAM role-based or provider-based authentication.</description>
</property>

<property>
  <name>fs.s3a.aws.credentials.provider</name>
  <description>
    Comma-separated class names of credential provider classes which implement
    com.amazonaws.auth.AWSCredentialsProvider.

    These are loaded and queried in sequence for a valid set of credentials.
    Each listed class must implement one of the following means of
    construction, which are attempted in order:
    1. a public constructor accepting java.net.URI and
        org.apache.hadoop.conf.Configuration,
    2. a public static method named getInstance that accepts no
       arguments and returns an instance of
       com.amazonaws.auth.AWSCredentialsProvider, or
    3. a public default constructor.

    Specifying org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider allows
    anonymous access to a publicly accessible S3 bucket without any credentials.
    Please note that allowing anonymous access to an S3 bucket compromises
    security and therefore is unsuitable for most use cases. It can be useful
    for accessing public data sets without requiring AWS credentials.

    If unspecified, then the default list of credential provider classes,
    queried in sequence, is:
    1. org.apache.hadoop.fs.s3a.SimpleAWSCredentialsProvider:
       Uses the values of fs.s3a.access.key and fs.s3a.secret.key.
    2. com.amazonaws.auth.EnvironmentVariableCredentialsProvider: supports
        configuration of AWS access key ID and secret access key in
        environment variables named AWS_ACCESS_KEY_ID and
        AWS_SECRET_ACCESS_KEY, as documented in the AWS SDK.
    3. com.amazonaws.auth.InstanceProfileCredentialsProvider: supports use
        of instance profile credentials if running in an EC2 VM.
  </description>
</property>

<property>
  <name>fs.s3a.session.token</name>
  <description>
    Session token, when using org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider
    as one of the providers.
  </description>
</property>

Authenticating via the AWS Environment Variables

S3A supports configuration via the standard AWS environment variables.

The core environment variables are for the access key and associated secret:

export AWS_ACCESS_KEY_ID=my.aws.key
export AWS_SECRET_ACCESS_KEY=my.secret.key

If the environment variable AWS_SESSION_TOKEN is set, session authentication using “Temporary Security Credentials” is enabled; the Key ID and secret key must be set to the credentials for that specific session.

export AWS_SESSION_TOKEN=SECRET-SESSION-TOKEN
export AWS_ACCESS_KEY_ID=SESSION-ACCESS-KEY
export AWS_SECRET_ACCESS_KEY=SESSION-SECRET-KEY

These environment variables can be used to set the authentication credentials instead of properties in the Hadoop configuration.

Important: These environment variables are generally not propagated from client to server when YARN applications are launched. That is: having the AWS environment variables set when an application is launched will not permit the launched application to access S3 resources. The environment variables must (somehow) be set on the hosts/processes where the work is executed.

Changing Authentication Providers

The standard way to authenticate is with an access key and secret key set in the Hadoop configuration files.

By default, the S3A client follows the following authentication chain:

1. The options fs.s3a.access.key, fs.s3a.secret.key and fs.s3a.sesson.key are looked for in the Hadoop XML configuration/Hadoop credential providers, returning a set of session credentials if all three are defined.
2. The fs.s3a.access.key and fs.s3a.secret.key are looked for in the Hadoop XML configuration//Hadoop credential providers, returning a set of long-lived credentials if they are defined.
3. The AWS environment variables, are then looked for: these will return session or full credentials depending on which values are set.
4. An attempt is made to query the Amazon EC2 Instance Metadata Service to retrieve credentials published to EC2 VMs.

S3A can be configured to obtain client authentication providers from classes which integrate with the AWS SDK by implementing the com.amazonaws.auth.AWSCredentialsProvider Interface. This is done by listing the implementation classes, in order of preference, in the configuration option fs.s3a.aws.credentials.provider.

Important: AWS Credential Providers are distinct from Hadoop Credential Providers. As will be covered later, Hadoop Credential Providers allow passwords and other secrets to be stored and transferred more securely than in XML configuration files. AWS Credential Providers are classes which can be used by the Amazon AWS SDK to obtain an AWS login from a different source in the system, including environment variables, JVM properties and configuration files.

All Hadoop fs.s3a. options used to store login details can all be secured in Hadoop credential providers; this is advised as a more secure way to store valuable secrets.

There are a number of AWS Credential Providers inside the hadoop-aws JAR:

There are also many in the Amazon SDKs, in particular two which are automatically set up in the authentication chain:

EC2 IAM Metadata Authentication with InstanceProfileCredentialsProvider

Applications running in EC2 may associate an IAM role with the VM and query the EC2 Instance Metadata Service for credentials to access S3. Within the AWS SDK, this functionality is provided by InstanceProfileCredentialsProvider, which internally enforces a singleton instance in order to prevent throttling problem.

Using Named Profile Credentials with ProfileCredentialsProvider

You can configure Hadoop to authenticate to AWS using a named profile.

To authenticate with a named profile:

1. Declare com.amazonaws.auth.profile.ProfileCredentialsProvider as the provider.
2. Set your profile via the AWS_PROFILE environment variable.
3. Due to a bug in version 1 of the AWS Java SDK, you’ll need to remove the profile prefix from the AWS configuration section heading.

   Here’s an example of what your AWS configuration files should look like:

   $ cat ~/.aws/config
   [user1]
   region = us-east-1
   $ cat ~/.aws/credentials
   [user1]
   aws_access_key_id = ...
   aws_secret_access_key = ...
   aws_session_token = ...
   aws_security_token = ...
   

Note:

1. The region setting is only used if fs.s3a.endpoint.region is set to the empty string.
2. For the credentials to be available to applications running in a Hadoop cluster, the configuration files MUST be in the ~/.aws/ directory on the local filesystem in all hosts in the cluster.

Using Session Credentials with TemporaryAWSCredentialsProvider

Temporary Security Credentials can be obtained from the Amazon Security Token Service; these consist of an access key, a secret key, and a session token.

To authenticate with these:

1. Declare org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider as the provider.
2. Set the session key in the property fs.s3a.session.token, and the access and secret key properties to those of this temporary session.

Example:

<property>
  <name>fs.s3a.aws.credentials.provider</name>
  <value>org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider</value>
</property>

<property>
  <name>fs.s3a.access.key</name>
  <value>SESSION-ACCESS-KEY</value>
</property>

<property>
  <name>fs.s3a.secret.key</name>
  <value>SESSION-SECRET-KEY</value>
</property>

<property>
  <name>fs.s3a.session.token</name>
  <value>SECRET-SESSION-TOKEN</value>
</property>

The lifetime of session credentials are fixed when the credentials are issued; once they expire the application will no longer be able to authenticate to AWS.

Anonymous Login with AnonymousAWSCredentialsProvider

Specifying org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider allows anonymous access to a publicly accessible S3 bucket without any credentials. It can be useful for accessing public data sets without requiring AWS credentials.

<property>
  <name>fs.s3a.aws.credentials.provider</name>
  <value>org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider</value>
</property>

Once this is done, there’s no need to supply any credentials in the Hadoop configuration or via environment variables.

This option can be used to verify that an object store does not permit unauthenticated access: that is, if an attempt to list a bucket is made using the anonymous credentials, it should fail —unless explicitly opened up for broader access.

hadoop fs -ls \
 -D fs.s3a.aws.credentials.provider=org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider \
 s3a://landsat-pds/

1. Allowing anonymous access to an S3 bucket compromises security and therefore is unsuitable for most use cases.

2. If a list of credential providers is given in fs.s3a.aws.credentials.provider, then the Anonymous Credential provider must come last. If not, credential providers listed after it will be ignored.

Simple name/secret credentials with SimpleAWSCredentialsProvider*

This is the standard credential provider, which supports the secret key in fs.s3a.access.key and token in fs.s3a.secret.key values.

<property>
  <name>fs.s3a.aws.credentials.provider</name>
  <value>org.apache.hadoop.fs.s3a.SimpleAWSCredentialsProvider</value>
</property>

This is the basic authenticator used in the default authentication chain.

This means that the default S3A authentication chain can be defined as

<property>
  <name>fs.s3a.aws.credentials.provider</name>
  <value>
    org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider,
    org.apache.hadoop.fs.s3a.SimpleAWSCredentialsProvider,
    com.amazonaws.auth.EnvironmentVariableCredentialsProvider,
    org.apache.hadoop.fs.s3a.auth.IAMInstanceCredentialsProvider
  </value>
  <description>
    Comma-separated class names of credential provider classes which implement
    com.amazonaws.auth.AWSCredentialsProvider.

    When S3A delegation tokens are not enabled, this list will be used
    to directly authenticate with S3 and other AWS services.
    When S3A Delegation tokens are enabled, depending upon the delegation
    token binding it may be used
    to communicate with the STS endpoint to request session/role
    credentials.

    These are loaded and queried in sequence for a valid set of credentials.
    Each listed class must implement one of the following means of
    construction, which are attempted in order:
    * a public constructor accepting java.net.URI and
        org.apache.hadoop.conf.Configuration,
    * a public constructor accepting org.apache.hadoop.conf.Configuration,
    * a public static method named getInstance that accepts no
       arguments and returns an instance of
       com.amazonaws.auth.AWSCredentialsProvider, or
    * a public default constructor.

    Specifying org.apache.hadoop.fs.s3a.AnonymousAWSCredentialsProvider allows
    anonymous access to a publicly accessible S3 bucket without any credentials.
    Please note that allowing anonymous access to an S3 bucket compromises
    security and therefore is unsuitable for most use cases. It can be useful
    for accessing public data sets without requiring AWS credentials.

    If unspecified, then the default list of credential provider classes,
    queried in sequence, is:
    * org.apache.hadoop.fs.s3a.TemporaryAWSCredentialsProvider: looks
       for session login secrets in the Hadoop configuration.
    * org.apache.hadoop.fs.s3a.SimpleAWSCredentialsProvider:
       Uses the values of fs.s3a.access.key and fs.s3a.secret.key.
    * com.amazonaws.auth.EnvironmentVariableCredentialsProvider: supports
        configuration of AWS access key ID and secret access key in
        environment variables named AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
        and AWS_SESSION_TOKEN as documented in the AWS SDK.
    * org.apache.hadoop.fs.s3a.auth.IAMInstanceCredentialsProvider: picks up
       IAM credentials of any EC2 VM or AWS container in which the process is running.
  </description>
</property>

Step 1: Create a credential file

A credential file can be created on any Hadoop filesystem; when creating one on HDFS or a Unix filesystem the permissions are automatically set to keep the file private to the reader —though as directory permissions are not touched, users should verify that the directory containing the file is readable only by the current user.

hadoop credential create fs.s3a.access.key -value 123 \
    -provider jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks

hadoop credential create fs.s3a.secret.key -value 456 \
    -provider jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks

A credential file can be listed, to see what entries are kept inside it

hadoop credential list -provider jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks

Listing aliases for CredentialProvider: jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks
fs.s3a.secret.key
fs.s3a.access.key

At this point, the credentials are ready for use.

Step 2: Configure the hadoop.security.credential.provider.path property

The URL to the provider must be set in the configuration property hadoop.security.credential.provider.path, either on the command line or in XML configuration files.

<property>
  <name>hadoop.security.credential.provider.path</name>
  <value>jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks</value>
  <description>Path to interrogate for protected credentials.</description>
</property>

Because this property only supplies the path to the secrets file, the configuration option itself is no longer a sensitive item.

The property hadoop.security.credential.provider.path is global to all filesystems and secrets. There is another property, fs.s3a.security.credential.provider.path which only lists credential providers for S3A filesystems. The two properties are combined into one, with the list of providers in the fs.s3a. property taking precedence over that of the hadoop.security list (i.e. they are prepended to the common list).

<property>
  <name>fs.s3a.security.credential.provider.path</name>
  <value />
  <description>
    Optional comma separated list of credential providers, a list
    which is prepended to that set in hadoop.security.credential.provider.path
  </description>
</property>

This was added to support binding different credential providers on a per bucket basis, without adding alternative secrets in the credential list. However, some applications (e.g Hive) prevent the list of credential providers from being dynamically updated by users. As per-bucket secrets are now supported, it is better to include per-bucket keys in JCEKS files and other sources of credentials.

Using secrets from credential providers

Once the provider is set in the Hadoop configuration, Hadoop commands work exactly as if the secrets were in an XML file.

hadoop distcp \
    hdfs://nn1.example.com:9001/user/backup/007020615 s3a://glacier1/

hadoop fs -ls s3a://glacier1/

The path to the provider can also be set on the command line:

hadoop distcp \
    -D hadoop.security.credential.provider.path=jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks \
    hdfs://nn1.example.com:9001/user/backup/007020615 s3a://glacier1/

hadoop fs \
  -D fs.s3a.security.credential.provider.path=jceks://hdfs@nn1.example.com:9001/user/backup/s3.jceks \
  -ls s3a://glacier1/

Because the provider path is not itself a sensitive secret, there is no risk from placing its declaration on the command line.

Unrecoverable Problems: Fail Fast

• No object/bucket store: FileNotFoundException
• No access permissions: AccessDeniedException
• Network errors considered unrecoverable (UnknownHostException, NoRouteToHostException, AWSRedirectException).
• Interruptions: InterruptedIOException, InterruptedException.
• Rejected HTTP requests: InvalidRequestException

These are all considered unrecoverable: S3A will make no attempt to recover from them.

Possibly Recoverable Problems: Retry

• Connection timeout: ConnectTimeoutException. Timeout before setting up a connection to the S3 endpoint (or proxy).
• HTTP response status code 400, “Bad Request”

The status code 400, Bad Request usually means that the request is unrecoverable; it’s the generic “No” response. Very rarely it does recover, which is why it is in this category, rather than that of unrecoverable failures.

These failures will be retried with an exponential sleep interval set in fs.s3a.retry.interval, up to the limit set in fs.s3a.retry.limit.

Only retriable on idempotent operations

Some network failures are considered to be retriable if they occur on idempotent operations; there’s no way to know if they happened after the request was processed by S3.

• SocketTimeoutException: general network failure.
• EOFException : the connection was broken while reading data
• “No response from Server” (443, 444) HTTP responses.
• Any other AWS client, service or S3 exception.

These failures will be retried with an exponential sleep interval set in fs.s3a.retry.interval, up to the limit set in fs.s3a.retry.limit.

Important: DELETE is considered idempotent, hence: FileSystem.delete() and FileSystem.rename() will retry their delete requests on any of these failures.

The issue of whether delete should be idempotent has been a source of historical controversy in Hadoop.

1. In the absence of any other changes to the object store, a repeated DELETE request will eventually result in the named object being deleted; it’s a no-op if reprocessed. As indeed, is Filesystem.delete().
2. If another client creates a file under the path, it will be deleted.
3. Any filesystem supporting an atomic FileSystem.create(path, overwrite=false) operation to reject file creation if the path exists MUST NOT consider delete to be idempotent, because a create(path, false) operation will only succeed if the first delete() call has already succeeded.
4. And a second, retried delete() call could delete the new data.

Because S3 is eventually consistent and doesn’t support an atomic create-no-overwrite operation, the choice is more ambiguous.

Currently S3A considers delete to be idempotent because it is convenient for many workflows, including the commit protocols. Just be aware that in the presence of transient failures, more things may be deleted than expected. (For anyone who considers this to be the wrong decision: rebuild the hadoop-aws module with the constant S3AFileSystem.DELETE_CONSIDERED_IDEMPOTENT set to false).

Throttled requests from S3

When AWS S3 returns a response indicating that requests from the caller are being throttled, an exponential back-off with an initial interval and a maximum number of requests.

<property>
  <name>fs.s3a.retry.throttle.limit</name>
  <value>${fs.s3a.attempts.maximum}</value>
  <description>
    Number of times to retry any throttled request.
  </description>
</property>

<property>
  <name>fs.s3a.retry.throttle.interval</name>
  <value>1000ms</value>
  <description>
    Interval between retry attempts on throttled requests.
  </description>
</property>

Notes

1. There is also throttling taking place inside the AWS SDK; this is managed by the value fs.s3a.attempts.maximum.
2. Throttling events are tracked in the S3A filesystem metrics and statistics.
3. Amazon KMS may throttle a customer based on the total rate of uses of KMS across all user accounts and applications.

Throttling of S3 requests is all too common; it is caused by too many clients trying to access the same shard of S3 Storage. This generally happen if there are too many reads, those being the most common in Hadoop applications. This problem is exacerbated by Hive’s partitioning strategy used when storing data, such as partitioning by year and then month. This results in paths with little or no variation at their start, which ends up in all the data being stored in the same shard(s).

Here are some expensive operations; the more of these taking place against part of an S3 bucket, the more load it experiences. * Many clients trying to list directories or calling getFileStatus on paths (LIST and HEAD requests respectively) * The GET requests issued when reading data. * Random IO used when reading columnar data (ORC, Parquet) means that many more GET requests than a simple one-per-file read. * The number of active writes to that part of the S3 bucket.

A special case is when enough data has been written into part of an S3 bucket that S3 decides to split the data across more than one shard: this is believed to be one by some copy operation which can take some time. While this is under way, S3 clients access data under these paths will be throttled more than usual.

Mitigation strategies

1. Use separate buckets for intermediate data/different applications/roles.
2. Use significantly different paths for different datasets in the same bucket.
3. Increase the value of fs.s3a.retry.throttle.interval to provide longer delays between attempts.
4. Reduce the parallelism of the queries. The more tasks trying to access data in parallel, the more load.
5. Reduce fs.s3a.threads.max to reduce the amount of parallel operations performed by clients. !. Maybe: increase fs.s3a.readahead.range to increase the minimum amount of data asked for in every GET request, as well as how much data is skipped in the existing stream before aborting it and creating a new stream.
6. KMS: “consult AWS about increasing your capacity”.

Change detection with S3 Versions.

It is possible to switch to using the S3 object version id instead of eTag as the change detection mechanism. Use of this option requires object versioning to be enabled on any S3 buckets used by the filesystem. The benefit of using version id instead of eTag is potentially reduced frequency of RemoteFileChangedException. With object versioning enabled, old versions of objects remain available after they have been overwritten. This means an open input stream will still be able to seek backwards after a concurrent writer has overwritten the file. The reader will retain their consistent view of the version of the file from which they read the first byte. Because the version ID is null for objects written prior to enablement of object versioning, this option should only be used when the S3 buckets have object versioning enabled from the beginning.

Note: when you rename files the copied files may have a different version number.

Change Detection Modes.

Configurable change detection mode is the next option. Different modes are available primarily for compatibility with third-party S3 implementations which may not support all change detection mechanisms.

• server: the version/etag check is performed on the server by adding extra headers to the GET request. This is the default.
• client : check on the client by comparing the eTag/version ID of a reopened file with the previous version. This is useful when the implementation doesn’t support the If-Match header.
• warn: check on the client, but only warn on a mismatch, rather than fail.
• none do not check. Useful if the implementation doesn’t provide eTag or version ID support at all or you would like to retain previous behavior where the reader’s input stream silently switches over to the new object version (not recommended).

The final option (fs.s3a.change.detection.version.required) is present primarily to ensure the filesystem doesn’t silently ignore the condition where it is configured to use version ID on a bucket that doesn’t have object versioning enabled or alternatively it is configured to use eTag on an S3 implementation that doesn’t return eTags.

When true (default) and ‘Get Object’ doesn’t return eTag or version ID (depending on configured ‘source’), a NoVersionAttributeException will be thrown. When false and eTag or version ID is not returned, the stream can be read, but without any version checking.

Using Per-Bucket Configuration to access data round the world

S3 Buckets are hosted in different “regions”, the default being “US-East”. The S3A client talks to this region by default, issuing HTTP requests to the server s3.amazonaws.com.

S3A can work with buckets from any region. Each region has its own S3 endpoint, documented by Amazon.

1. Applications running in EC2 infrastructure do not pay for IO to/from local S3 buckets. They will be billed for access to remote buckets. Always use local buckets and local copies of data, wherever possible.
2. The default S3 endpoint can support data IO with any bucket when the V1 request signing protocol is used.
3. When the V4 signing protocol is used, AWS requires the explicit region endpoint to be used —hence S3A must be configured to use the specific endpoint. This is done in the configuration option fs.s3a.endpoint.
4. All endpoints other than the default endpoint only support interaction with buckets local to that S3 instance.

While it is generally simpler to use the default endpoint, working with V4-signing-only regions (Frankfurt, Seoul) requires the endpoint to be identified. Expect better performance from direct connections —traceroute will give you some insight.

If the wrong endpoint is used, the request may fail. This may be reported as a 301/redirect error, or as a 400 Bad Request: take these as cues to check the endpoint setting of a bucket.

Here is a list of properties defining all AWS S3 regions, current as of June 2017:

<!--
 This is the default endpoint, which can be used to interact
 with any v2 region.
 -->
<property>
  <name>central.endpoint</name>
  <value>s3.amazonaws.com</value>
</property>

<property>
  <name>canada.endpoint</name>
  <value>s3.ca-central-1.amazonaws.com</value>
</property>

<property>
  <name>frankfurt.endpoint</name>
  <value>s3.eu-central-1.amazonaws.com</value>
</property>

<property>
  <name>ireland.endpoint</name>
  <value>s3-eu-west-1.amazonaws.com</value>
</property>

<property>
  <name>london.endpoint</name>
  <value>s3.eu-west-2.amazonaws.com</value>
</property>

<property>
  <name>mumbai.endpoint</name>
  <value>s3.ap-south-1.amazonaws.com</value>
</property>

<property>
  <name>ohio.endpoint</name>
  <value>s3.us-east-2.amazonaws.com</value>
</property>

<property>
  <name>oregon.endpoint</name>
  <value>s3-us-west-2.amazonaws.com</value>
</property>

<property>
  <name>sao-paolo.endpoint</name>
  <value>s3-sa-east-1.amazonaws.com</value>
</property>

<property>
  <name>seoul.endpoint</name>
  <value>s3.ap-northeast-2.amazonaws.com</value>
</property>

<property>
  <name>singapore.endpoint</name>
  <value>s3-ap-southeast-1.amazonaws.com</value>
</property>

<property>
  <name>sydney.endpoint</name>
  <value>s3-ap-southeast-2.amazonaws.com</value>
</property>

<property>
  <name>tokyo.endpoint</name>
  <value>s3-ap-northeast-1.amazonaws.com</value>
</property>

<property>
  <name>virginia.endpoint</name>
  <value>${central.endpoint}</value>
</property>

This list can be used to specify the endpoint of individual buckets, for example for buckets in the central and EU/Ireland endpoints.

<property>
  <name>fs.s3a.bucket.landsat-pds.endpoint</name>
  <value>${central.endpoint}</value>
  <description>The endpoint for s3a://landsat-pds URLs</description>
</property>

<property>
  <name>fs.s3a.bucket.eu-dataset.endpoint</name>
  <value>${ireland.endpoint}</value>
  <description>The endpoint for s3a://eu-dataset URLs</description>
</property>

Why explicitly declare a bucket bound to the central endpoint? It ensures that if the default endpoint is changed to a new region, data store in US-east is still reachable.

Buffering upload data on disk fs.s3a.fast.upload.buffer=disk

When fs.s3a.fast.upload.buffer is set to disk, all data is buffered to local hard disks prior to upload. This minimizes the amount of memory consumed, and so eliminates heap size as the limiting factor in queued uploads —exactly as the original “direct to disk” buffering.

<property>
  <name>fs.s3a.fast.upload.buffer</name>
  <value>disk</value>
</property>

<property>
  <name>fs.s3a.buffer.dir</name>
  <value>${env.LOCAL_DIRS:-${hadoop.tmp.dir}}/s3a</value>
  <description>Comma separated list of directories that will be used to buffer file
    uploads to.
    Yarn container path will be used as default value on yarn applications,
    otherwise fall back to hadoop.tmp.dir
  </description>
</property>

This is the default buffer mechanism. The amount of data which can be buffered is limited by the amount of available disk space.

Buffering upload data in ByteBuffers: fs.s3a.fast.upload.buffer=bytebuffer

When fs.s3a.fast.upload.buffer is set to bytebuffer, all data is buffered in “Direct” ByteBuffers prior to upload. This may be faster than buffering to disk, and, if disk space is small (for example, tiny EC2 VMs), there may not be much disk space to buffer with.

The ByteBuffers are created in the memory of the JVM, but not in the Java Heap itself. The amount of data which can be buffered is limited by the Java runtime, the operating system, and, for YARN applications, the amount of memory requested for each container.

The slower the upload bandwidth to S3, the greater the risk of running out of memory —and so the more care is needed in tuning the upload settings.

<property>
  <name>fs.s3a.fast.upload.buffer</name>
  <value>bytebuffer</value>
</property>

Buffering upload data in byte arrays: fs.s3a.fast.upload.buffer=array

When fs.s3a.fast.upload.buffer is set to array, all data is buffered in byte arrays in the JVM’s heap prior to upload. This may be faster than buffering to disk.

The amount of data which can be buffered is limited by the available size of the JVM heap. The slower the write bandwidth to S3, the greater the risk of heap overflows. This risk can be mitigated by tuning the upload settings.

<property>
  <name>fs.s3a.fast.upload.buffer</name>
  <value>array</value>
</property>

Upload Thread Tuning

Both the Array and Byte buffer buffer mechanisms can consume very large amounts of memory, on-heap or off-heap respectively. The disk buffer mechanism does not use much memory up, but will consume hard disk capacity.

If there are many output streams being written to in a single process, the amount of memory or disk used is the multiple of all stream’s active memory/disk use.

Careful tuning may be needed to reduce the risk of running out memory, especially if the data is buffered in memory.

There are a number parameters which can be tuned:

1. The total number of threads available in the filesystem for data uploads or any other queued filesystem operation. This is set in fs.s3a.threads.max

2. The number of operations which can be queued for execution:, awaiting a thread: fs.s3a.max.total.tasks

3. The number of blocks which a single output stream can have active, that is: being uploaded by a thread, or queued in the filesystem thread queue: fs.s3a.fast.upload.active.blocks

4. How long an idle thread can stay in the thread pool before it is retired: fs.s3a.threads.keepalivetime

When the maximum allowed number of active blocks of a single stream is reached, no more blocks can be uploaded from that stream until one or more of those active blocks’ uploads completes. That is: a write() call which would trigger an upload of a now full datablock, will instead block until there is capacity in the queue.

How does that come together?

• As the pool of threads set in fs.s3a.threads.max is shared (and intended to be used across all threads), a larger number here can allow for more parallel operations. However, as uploads require network bandwidth, adding more threads does not guarantee speedup.

• The extra queue of tasks for the thread pool (fs.s3a.max.total.tasks) covers all ongoing background S3A operations (future plans include: parallelized rename operations, asynchronous directory operations).

• When using memory buffering, a small value of fs.s3a.fast.upload.active.blocks limits the amount of memory which can be consumed per stream.

• When using disk buffering a larger value of fs.s3a.fast.upload.active.blocks does not consume much memory. But it may result in a large number of blocks to compete with other filesystem operations.

We recommend a low value of fs.s3a.fast.upload.active.blocks; enough to start background upload without overloading other parts of the system, then experiment to see if higher values deliver more throughput —especially from VMs running on EC2.

<property>
  <name>fs.s3a.fast.upload.active.blocks</name>
  <value>4</value>
  <description>
    Maximum Number of blocks a single output stream can have
    active (uploading, or queued to the central FileSystem
    instance's pool of queued operations.

    This stops a single stream overloading the shared thread pool.
  </description>
</property>

<property>
  <name>fs.s3a.threads.max</name>
  <value>10</value>
  <description>The total number of threads available in the filesystem for data
    uploads *or any other queued filesystem operation*.</description>
</property>

<property>
  <name>fs.s3a.max.total.tasks</name>
  <value>5</value>
  <description>The number of operations which can be queued for execution</description>
</property>

<property>
  <name>fs.s3a.threads.keepalivetime</name>
  <value>60</value>
  <description>Number of seconds a thread can be idle before being
    terminated.</description>
</property>

Cleaning up after partial Upload Failures

There are two mechanisms for cleaning up after leftover multipart uploads: - Hadoop s3guard CLI commands for listing and deleting uploads by their age. Documented in the S3Guard section. - The configuration parameter fs.s3a.multipart.purge, covered below.

If a large stream write operation is interrupted, there may be intermediate partitions uploaded to S3 —data which will be billed for.

These charges can be reduced by enabling fs.s3a.multipart.purge, and setting a purge time in seconds, such as 86400 seconds —24 hours. When an S3A FileSystem instance is instantiated with the purge time greater than zero, it will, on startup, delete all outstanding partition requests older than this time.

<property>
  <name>fs.s3a.multipart.purge</name>
  <value>true</value>
  <description>True if you want to purge existing multipart uploads that may not have been
     completed/aborted correctly</description>
</property>

<property>
  <name>fs.s3a.multipart.purge.age</name>
  <value>86400</value>
  <description>Minimum age in seconds of multipart uploads to purge</description>
</property>

If an S3A client is instantiated with fs.s3a.multipart.purge=true, it will delete all out of date uploads in the entire bucket. That is: it will affect all multipart uploads to that bucket, from all applications.

Leaving fs.s3a.multipart.purge to its default, false, means that the client will not make any attempt to reset or change the partition rate.

The best practise for using this option is to disable multipart purges in normal use of S3A, enabling only in manual/scheduled housekeeping operations.

S3A “fadvise” input policy support

The S3A Filesystem client supports the notion of input policies, similar to that of the Posix fadvise() API call. This tunes the behavior of the S3A client to optimise HTTP GET requests for the different use cases.

See Improving data input performance through fadvise for the details.

Copying Data with distcp

Hadoop’s distcp tool is often used to copy data between a Hadoop cluster and Amazon S3. See Copying Data Between a Cluster and Amazon S3 for details on S3 copying specifically.

The distcp update command tries to do incremental updates of data. It is straightforward to verify when files do not match when they are of different length, but not when they are the same size.

Distcp addresses this by comparing file checksums on the source and destination filesystems, which it tries to do even if the filesystems have incompatible checksum algorithms.

The S3A connector can provide the HTTP etag header to the caller as the checksum of the uploaded file. Doing so will break distcp operations between hdfs and s3a.

For this reason, the etag-as-checksum feature is disabled by default.

<property>
  <name>fs.s3a.etag.checksum.enabled</name>
  <value>false</value>
  <description>
    Should calls to getFileChecksum() return the etag value of the remote
    object.
    WARNING: if enabled, distcp operations between HDFS and S3 will fail unless
    -skipcrccheck is set.
  </description>
</property>

If enabled, distcp between two S3 buckets can use the checksum to compare objects. Their checksums should be identical if they were either each uploaded as a single file PUT, or, if in a multipart PUT, in blocks of the same size, as configured by the value fs.s3a.multipart.size.

To disable checksum verification in distcp, use the -skipcrccheck option:

hadoop distcp -update -skipcrccheck -numListstatusThreads 40 /user/alice/datasets s3a://alice-backup/datasets

Advanced - Custom Signers

AWS uees request signing to authenticate requests. In general, there should be no need to override the signers, and the defaults work out of the box. If, however, this is required - this section talks about how to configure custom signers. There’s 2 broad config categories to be set - one for registering a custom signer and another to specify usage.

<property>
  <name>fs.s3a.custom.signers</name>
  <value>comma separated list of signers</value>
  <!-- Example
  <value>AWS4SignerType,CS1:CS1ClassName,CS2:CS2ClassName:CS2InitClass</value>
  -->
</property>

<property>
  <name>fs.s3a.s3.signing-algorithm</name>
  <value>${S3SignerName}</value>
  <description>Specify the signer for S3</description>
</property>

<property>
  <name>fs.s3a.signing-algorithm</name>
  <value>${SignerName}</value>
</property>