Configuring service clients for the AWS SDK for Kotlin - AWS SDK for Kotlin

This is prerelease documentation for a service in preview release. It is subject to change.

Configuring service clients for the AWS SDK for Kotlin

Creating service clients

To make a request to an AWS service, first instantiate an object to serve as a client for that service.

You must specify a region and a credentials provider as part of the service client instantiation. The SDK uses these values to route requests to the correct region and to sign requests with your credentials. You can specify these values programmatically in code, or have them automatically loaded from the environment.

The simplest way to create a new service client is by loading the region, credentials, and other configuration from the application environment. For example, this code snippet instantiates a DynamoDbClient object as a service client for DynamoDB.

val dynamoDbClient = DynamoDbClient.fromEnvironment()

The fromEnvironment() method creates a service client with the default configuration. It uses the default provider chain to load credentials and the AWS Region. If credentials or the region can’t be determined from the environment that the application is running in, the call fails. Using the fromEnvironment() method can be particularly convenient with AWS Lambda functions or Amazon EC2 instances or in other situations where you want to decouple your code from your configuration.

Altenratively, you can supply configuration values on the service client. The following code snippet shows an example of one way to instantiate an Ec2Client object as a service client for Amazon EC2.

val ec2Client = Ec2Client { region = "us-west-2" credentialsProvider = ProfileCredentialsProvider(profileName = "myprofile") }

When you use the configuration from your environment, you can override specific settings for that service client by providing a new value for each property you need to override. The following code snippet is an example of overriding the region.

val ec2Client = Ec2Client.fromEnvironment() { region = "us-east-1" }

Configuring service clients

You can configure individual settings on the service client to override the defaults, such as the HTTP engine to use, the logging level, the retry configuration, or other settings. Refer to the following code snippet for a few examples.

val s3Client = S3Client.fromEnvironment() { sdkLogMode = SdkLogMode.LogRequest credentialsProvider = ProfileCredentialsProvider(profileName = "alternatecredentials") ... }

To reuse a configuration across service clients, generate an AwsClientConfig object with the desired settings. Refer to the following code snippet for an example.

import aws.sdk.kotlin.runtime.client.AwsClientConfig import aws.sdk.kotlin.runtime.config.fromEnvironment import aws.sdk.kotlin.services.dynamodb.DynamoDbClient import aws.sdk.kotlin.services.s3.S3Client // ... val sharedConfig = AwsClientConfig.fromEnvironment() val dynamoDbClient = DynamoDbClient(sharedConfig) val s3Client = S3Client(sharedConfig)

You can override individual configuration settings on a shared configuration in the same way that you do for a client object-specific configuration. Refer to the following code snippet for an example.

val s3Client = S3Client(sharedConfig) { sdkLogMode = SdkLogMode.LogRequest }