Customize AWS service client configurations

By default, AWS SDK for Swift uses a basic default configuration for each AWS service. This configuration automatically looks for credentials to use in a predictable, standard way:

1. The environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY_ID, and AWS_SESSION_TOKEN.

2. The default AWS profile, as described in the AWS configuration file (located at ~/.aws/config on Linux and macOS and at C:\Users\USERNAME\.aws\config on Windows), and the credentials found in the file ~/.aws/credentials on Linux and macOS and in C:\Users\USERNAME\.aws\credentials on Windows.

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 a given set of options. All of these classes are based on the generic AWSClientRuntime.AWSClientConfiguration class, which defines the configuration options available across all services. This includes options such as the Region and credentials, which are always needed in order to access an AWS service.

Within the AWS SDK for Swift, each service defines a struct that's used to resolve the AWSClientConfiguration type to include options supported by the service's client. The resolved type is given an alias such as S3Client.S3ClientConfiguration for convenience, which is defined like this:

extension S3Client {
   public typealias S3ClientConfiguration = AWSClientConfiguration<ServiceSpecificConfiguration>

   public struct ServiceSpecificConfiguration: AWSServiceSpecificConfiguration {
      /// Service-specific properties are defined here, including:

      public var serviceName: String { "S3" }
      public var clientName: String { "S3Client" }

      /// ... and so on.
   }
}   

This establishes S3Client.S3ClientConfiguration as an alias for the type AWSClientConfiguration<ServiceSpecificConfiguration>. As a result, S3ClientConfiguration includes its own properties and also everything defined in AWSClientConfiguration and the AWSServiceSpecificConfiguration protocol it's based on.

Every service configuration class includes the serviceName and clientName properties. serviceName specifies the shorthand name of the service, such as S3, IAM, or DynamoDB. clientName gives the name of the actual service client class, such as S3Client, IAMClient, or DynamoDBClient.

By creating a custom configuration object and using it when creating a service client object, you can specify a configuration source from which credentials and other options are taken. Alternatively, 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 a type corresponding 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 (keeping every option other than the Region with its default value) 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.

• 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", the adaptive retry mode, and the maximum
        // number of retries as 5.

        let config: S3Client.S3ClientConfiguration

        do {
            config = try await S3Client.S3ClientConfiguration(
                region: "us-east-1", 
                retryStrategyOptions: RetryStrategyOptions(
                    maxRetriesBase: 5,
                    rateLimitingMode: .adaptive
                )
            )
        } 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.