Configuring the AWS SDK at global and service levels

When we access AWS services from the SDK, we need to set the configuration options. These can be defined at two different levels: global and service levels.

1. Global level

The first option is to set the configuration options globally. This means that each service initiated after the global settings are defined will inherit these settings.

1.1. Set the region

Let’s see an example for setting the configuration parameters globally:

const AWS = require('aws-sdk')

AWS.config.update({
  region: 'us-west-2',
})

const kms = new AWS.KMS()
// work with KMS...

Here we define us-west-2 as the region globally by using the update method of the config object. This method accepts an object, and one of the properties is region.

This is a good option if we know that the services our application uses are located within the same region. In this case, the KMS service will inherit the global settings.

1.2. Credentials

It’s not only the region that can be set at the global object level.

Although it’s not the best way to do it in production, it’s possible to have all credentials in a shared file. This works well when you have more than one set of credentials (access key and secret access key) in the .aws/credentials file, and you will need a profile different from default.

For local development, the following code works well:

const credentials = new AWS.SharedIniFileCredentials({
  profile: 'name-of-the-profile-I-need-to-work-with',
})

AWS.config.credentials = credentials

Here we save the credentials that need to be used to the variable called credentials, and assign them to the credentials property of the config object.

1.3. Lock the API version

We can also lock the API versions for the services used in module.

AWS recommends that the API version get locked to ensure that newer versions of the SDK don’t break the application. The API version is given in YYYY-mm-dd format, or, we can use the latest version by setting latest as the value (but this won’t protect from breaking changes). By default, if the API version is not defined, the latest version of the SDK will be used.

An example for locking the API version is the following:

AWS.config.apiVersions({
  s3: '2006-03-01',
  dynamodb: 'latest',
})

The config object has an apiVersions method, which accepts an object. The keys of this object are the services we want to work with, and the values are the API versions for the corresponding service.

2. Service level

A more granular control can be achieved if the configuration is defined at the service level.

For example, when the KMS module is used, the service level configuration looks like this:

const AWS = require('aws-sdk')

const kms = new AWS.KMS({
  region: 'us-west-2',
  apiVersion: '2014-11-01',
})

A use case of the service level configuration for KMS can be found in this post.

As it can be seen from the example, region and apiVersion can be defined in the object when KMS service is initialized.

It’s also possible to override the global configuration at the service level:

AWS.config.update({
  region: 'us-east-1',
})

const kms = new AWS.KMS({
  region: 'us-west-2',
})

In this case, the code related to the KMS service will use us-west-2, but other services will connect to us-east-1.

3. Summary

AWS credentials can be set at two different levels: global and service level.

Global level settings are inherited by all services, but changes in the global configuration won’t affect the already initiated services.

The service level configuration allows a more granular control, and it can override the global configurations if needed.

Thanks for reading, and see you next time.