Customize AWS service client configurations

By default, AWS SDK for Swift uses a basic default configuration for each AWS service. If the user doesn't configure a credential resolver, the default one gets used. The default credential resolver is a chain of resolvers that looks for credentials in the following order:

1. The environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY_ID, and AWS_SESSION_TOKEN. While these are suitable for development and testing, they shouldn't be relied on for shipped applications.

2. The default AWS profile, as described in the AWS configuration file (located at ~/.aws/config on Linux and macOS, and the credentials found in the file ~/.aws/credentials on Linux and macOS.

3. Optionally, the configuration is looked for on Amazon Elastic Container Service.

4. Optionally, the configuration can be taken from Amazon EC2 instance metadata.

Each service might have other options available through its configuration class, depending on that service's needs.

Configuration data types

Each AWS service has its own configuration class that you use to specify adjust options for that client type. All of these classes are based on a number of protocols that together describe all the configuration options available for that client. This includes options such as the Region and credentials, which are always needed in order to access an AWS service.

For Amazon S3, the configuration class is called S3Client.S3ClientConfiguration which is defined like this:

extension S3Client {
    public class S3ClientConfiguration: AWSClientRuntime.AWSDefaultClientConfiguration &
            AWSClientRuntime.AWSRegionClientConfiguration &
            ClientRuntime.DefaultClientConfiguration &
            ClientRuntime.DefaultHttpClientConfiguration {
        
        // Service-specific properties are defined here, including:

        public var region: Swift.String?

        // ... and so on.
   }
}   

As a result, S3ClientConfiguration includes its own properties and also all the properties defined in those protocols, making it a complete description of an Amazon S3 client's configuration. Corresponding configuration classes are defined by every AWS service.

By creating a custom configuration object and using it when creating a service client object, you can customize the client by specifying a configuration source from which credentials and other options are taken. Otherwise, you can directly specify the credentials instead of letting the SDK obtain them automatically.

Configure a client

When only changing common options, you can often specify the custom values for your configuration when instantiating the service’s client object. If the client class constructor doesn't support the option you need to change, then create and specify a configuration object with the type that corresponds to the client class.

Create a client with only a custom Region

Most services let you directly specify the Region when you call their constructors. For example, to create an Amazon S3 client configured for the Region af-south-1, specify the region parameter when creating the client, as shown.

do {
    let s3 = try S3Client(region: "af-south-1")

    // Use the client.
} catch {
    // Handle the error.
    dump(error, name: "Error accessing S3 service")
}

This lets you handle a common client configuration scenario (specifying a Region while using the default values for all other options) without going through the full configuration process. That process is covered in the next topic.

Create and use a custom configuration

To customize the configuration of an AWS service, create a configuration object of the appropriate type for the service. Then pass that configuration object into the service client's constructor as the value of its config parameter.

For example, to configure an Amazon S3 client, create an object of type S3Client.S3ClientConfiguration. Set the properties that you want to change, then pass the configuration object into S3Client(config:).

The following example creates a new Amazon S3 client configured with the following options:

• The AWS Region is set to us-east-1.

• An exponential backoff strategy with default options is selected instead of the default backoff strategy.

• The retry mode is set to RetryStrategyOptions.RateLimitingMode.adaptive. See Retry behavior in the AWS SDKs and Tools Reference Guide for details.

• The maximum number of retries is set to 5.

        // Create an Amazon S3 client configuration object that specifies the
        // region as "us-east-1", an exponential backoff strategy, the
        // adaptive retry mode, and the maximum number of retries as 5.

        await SDKLoggingSystem().initialize(logLevel: .debug)

        let config: S3Client.S3ClientConfiguration

        do {
            config = try await S3Client.S3ClientConfiguration(
                awsRetryMode: .standard,
                maxAttempts: 3,
                region: "us-east-1"
            )
        } catch {
            print("Error: Unable to create configuration")
            dump(error)
            exit(1)
        }

        // Create an Amazon S3 client using the configuration created above.

        let client = S3Client(config: config)

If an error occurs creating the configuration, an error message is displayed and the details are dumped to the console. The program then exits. In a real world application, a more constructive approach should be taken when handling this error, such as falling back to a different configuration or using the default configuration, if doing so is appropriate for your application.