Smart configuration defaults - Amazon SDKs and Tools
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Smart configuration defaults

With the smart configuration defaults feature, Amazon SDKs can provide predefined, optimized default values for other configuration settings.

Configure this functionality by using the following:

defaults_mode - shared Amazon config file setting
AWS_DEFAULTS_MODE - environment variable
aws.defaultsMode - JVM system property: Java/Kotlin only

With this setting, you can choose a mode that aligns with your application architecture, which then provides optimized default values for your application. If an Amazon SDK setting has a value explicitly set, then that value always takes precedence. If an Amazon SDK setting does not have a value explicitly set, and defaults_mode is not equal to legacy, then this feature can provide different default values for various settings optimized for your application. Settings may include the following: HTTP communication settings, retry behavior, service Regional endpoint settings, and, potentially, any SDK-related configuration. Customers who use this feature can get new configuration defaults tailored to common usage scenarios. If your defaults_mode is not equal to legacy, we recommend performing tests of your application when you upgrade the SDK, because the default values provided might change as best practices evolve.

Default value: legacy

Note: New major versions of SDKs will default to standard.

Valid values:

  • legacy – Provides default settings that vary by SDK and existed before establishment of defaults_mode.

  • standard – Provides the latest recommended default values that should be safe to run in most scenarios.

  • in-region – Builds on the standard mode and includes optimization tailored for applications that call Amazon Web Services from within the same Amazon Web Services Region.

  • cross-region – Builds on the standard mode and includes optimization tailored for applications that call Amazon Web Services in a different Region.

  • mobile – Builds on the standard mode and includes optimization tailored for mobile applications.

  • auto – Builds on the standard mode and includes experimental features. The SDK attempts to discover the runtime environment to determine the appropriate settings automatically. The auto detection is heuristics-based and does not provide 100% accuracy. If the runtime environment can't be determined, standard mode is used. The auto detection might query instance metadata, which might introduce latency. If startup latency is critical to your application, we recommend choosing an explicit defaults_mode instead.

Example of setting this value in the config file:

[default] defaults_mode = standard

The following parameters might be optimized based on the selection of defaults_mode:

  • retryMode – Specifies how the SDK attempts retries. See Retry behavior.

  • stsRegionalEndpoints – Specifies how the SDK determines the Amazon Web Service endpoint that it uses to talk to the Amazon Security Token Service (Amazon STS). See Amazon STS Regionalized endpoints.

  • s3UsEast1RegionalEndpoints – Specifies how the SDK determines the Amazon service endpoint that it uses to talk to the Amazon S3 for the us-east-1 Region.

  • connectTimeoutInMillis – After making an initial connection attempt on a socket, the amount of time before timing out. If the client does not receive a completion of the connect handshake, the client gives up and fails the operation.

  • tlsNegotiationTimeoutInMillis – The maximum amount of time that a TLS handshake can take from the time the CLIENT HELLO message is sent to the time the client and server have fully negotiated ciphers and exchanged keys.

The default value for each setting changes depending on the defaults_mode selected for your application. These values are currently set as follows (subject to change):

Parameter standard mode in-region mode cross-region mode mobile mode
retryMode standard standard standard standard
stsRegionalEndpoints regional regional regional regional
s3UsEast1RegionalEndpoints regional regional regional regional
connectTimeoutInMillis 3100 1100 3100 30000
tlsNegotiationTimeoutInMillis 3100 1100 3100 30000

For example, if the defaults_mode you selected was standard, then the value of standard would be assigned for retry_mode (from the valid retry_mode options) and the value of regional would be assigned for stsRegionalEndpoints (from the valid stsRegionalEndpoints options).

Compatibility with Amazon SDKs

The following SDKs support the features and settings described in this topic. Any partial exceptions are noted. Any JVM system property settings are supported by the Amazon SDK for Java and the Amazon SDK for Kotlin only.

SDK Supported Notes or more information
Amazon CLI v2 No
SDK for C++ Yes Parameters not optimized: stsRegionalEndpoints, s3UsEast1RegionalEndpoints, tlsNegotiationTimeoutInMillis.
SDK for Go V2 (1.x) Yes Parameters not optimized: retryMode, stsRegionalEndpoints, s3UsEast1RegionalEndpoints.
SDK for Go 1.x (V1) No
SDK for Java 2.x Yes Parameters not optimized: stsRegionalEndpoints.
SDK for Java 1.x No
SDK for JavaScript 3.x Yes Parameters not optimized: stsRegionalEndpoints, s3UsEast1RegionalEndpoints, tlsNegotiationTimeoutInMillis. connectTimeoutInMillis is called connectionTimeout.
SDK for JavaScript 2.x No
SDK for Kotlin No
SDK for .NET 3.x Yes Parameters not optimized: connectTimeoutInMillis, tlsNegotiationTimeoutInMillis.
SDK for PHP 3.x Yes Parameters not optimized: tlsNegotiationTimeoutInMillis.
SDK for Python (Boto3) Yes Parameters not optimized: tlsNegotiationTimeoutInMillis.
SDK for Ruby 3.x Yes
SDK for Rust No
Tools for PowerShell Yes Parameters not optimized: connectTimeoutInMillis, tlsNegotiationTimeoutInMillis.