Client configuration

By default, the AWS SDK for Swift uses a basic configuration that, among other things, 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

Configurations vary by service

Each AWS service has its own configuration class that you use to specify a given set of options. All of these classes implement the AWSClientRuntime.AWSClientConfiguration protocol, so the options defined in that are available for all services. These shared options include things like the Region and credentials, which are always needed in order to access an AWS service.

With a custom configuration object, you can either specify a specific configuration source for your operations (or even directly specify the credentials) rather than let the SDK determine the credentials automatically. This guide covers both of these cases.

Using custom configurations

When only changing common options, you can often simply specify the custom values for your configuration when instantiating the service’s client object. In other cases, you may need to actually directly instantiate a configuration object for the client you’re using.

Instantiating a client with only a custom Region

Most services let you 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 below.

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

    // .....
} catch {
    dump(error, name: "Error accessing S3 service")
    exit(1)
}

This lets you handle a common client configuration scenario (all default settings other than a specific Region) without going through the full configuration process. That process is our next topic.

Creating and using a custom configuration

To customize the configuration of an AWS service, pass a configuration object into the client’s constructor as the value of its config parameter.

Every configurable service provides a configuration class that implements the AWSClientRuntime.AWSClientConfiguration protocol. For example, to configure Amazon S3, create an object of type S3Client.S3ClientConfiguration, with the values set as desired to customize the S3Client that you wish to create.

Do this by using the DefaultSDKRuntimeConfiguration() constructor to obtain the defaults for Amazon S3 clients and to set any custom values, then pass the resulting object as the value of the runtimeConfig property when instantiating the S3Client.S3ClientConfiguration object.

The example below creates a new Amazon S3 client configured to log both requests and responses to the console.

do {
    let defaultConfig = try DefaultSDKRuntimeConfiguration("S3Client",
                                                           clientLogMode: .requestAndResponse)
    let s3Config = try S3Client.S3ClientConfiguration(runtimeConfig: defaultConfig)
    let s3 = S3Client(config: s3Config)

    // ....
} catch {
    dump(error, "Creating configuration object")
    exit(1)
}

The example instantiates both the client’s configuration and the client itself within a Swift do block. This way, any errors that may occur are handled by the corresponding catch block. In addition, both the configuration and the client are automatically discarded when the do block ends. When the S3Client is deallocated at that time, any active connection is automatically closed by the SDK.