Configuring the SDK

The Configuration Object

Configuration in the SDK can be done in two ways:

1. Global configuration on AWS.config, or,
2. Passing extra configuration to a service object

Setting global configuration with AWS.config is often easier to get up and running with, but service level configuration can provide much more control over your requests. Both of these configuration mechanisms are discussed.

Global Configuration (AWS.config)

By default, you can set global configuration by updating the AWS.config object with new settings. The most common settings are:

1. accessKeyId, secretAccessKey, sessionToken — for credential management
2. region — to set the region for requests
3. sslEnabled — whether SSL is enabled or not
4. maxRetries — to control the number of retries for a request

More configuration settings can be found in the API reference documentation.

The only things you need to set in order to use the SDK are credentials and the region value. Let's discuss how to do that.

Setting AWS Credentials

Remember, if you set your AWS credentials in your environment variables, the AWS SDK for Node.js will automatically detect them, and you will not need to perform any manual credential configuration in your application.

Credentials are the most important thing you need to set when using any AWS SDK. Credentials can be set globally on the AWS.config object or per service by passing the credential information to the service object directly.

There are a few ways to load credentials. Here they are, in order of recommendation:

1. Loaded from environment variables,
2. Loaded from a JSON file on disk,
3. Loaded from EC2 metadata service,
4. Hardcoded in your application

We recommend you not hard-code your AWS credentials in your application; however, it is reasonable to temporarily hard-code credential information in small personal scripts or for testing purposes.

Credentials from Environment Variables

By default, the AWS SDK for Node.js will automatically detect AWS credentials set in your environment and use them for requests. This means that if you properly set your environment variables, you do not need to manage credentials in your application at all.

The keys that the SDK looks for are as follows:

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN (optional)

Alternately, the SDK can accept the AMAZON_ prefix instead:

AMAZON_ACCESS_KEY_ID, AMAZON_SECRET_ACCESS_KEY, AMAZON_SESSION_TOKEN (optional)

Credentials from Disk

You can also load configuration and credentials from disk using AWS.config.loadFromPath by passing a file to a JSON document containing the configuration data. For example, if you had a file named 'config.json' with the contents:

{ "accessKeyId": "akid", "secretAccessKey": "secret", "region": "us-east-1" }

You can load the JSON data using the command:

AWS.config.loadFromPath('./config.json');

Note that the loadFromPath method clobbers all existing configuration on the object. If you are adding extra configuration, make sure you add it after this call.

Hard-Coding Credentials

We recommend you not hard-code credentials inside an application. Use this method only for small personal scripts or for testing purposes.

You can hard-code credentials by passing the credential information to the configuration object using AWS.config.update():

AWS.config.update({accessKeyId: 'akid', secretAccessKey: 'secret'});

Setting the Region

The AWS SDK for Node.js doesn't select the region by default. You can choose a region similarly to setting credentials by either loading from disk or using AWS.config.update():

AWS.config.update({region: 'us-west-1'});

Locking API Versions

For more information on API version locking in the SDK, see the Services section

You can globally configure a set of API versions to use for each service by specifying the apiVersions parameter in AWS.config. For example, you can choose to set specific versions of the DynamoDB and EC2 services, while selecting the "latest" version of Redshift:

AWS.config.apiVersions = {
  dynamodb: '2011-12-05',
  ec2: '2013-02-01',
  redshift: 'latest'
}

Note that by default, the SDK will use the "latest" available API version when constructing a service.

You can also lock all services at a specific point in time by using a "fuzzy version":

// Try to use latest available APIs before this date
AWS.config.apiVersion = '2012-05-04';

Configuring a Proxy

If you cannot connect to the internet directly, the SDK supports the use of HTTP or HTTPS proxies through global or per-service configuration options. To set a proxy, pass the proxy option to the httpOptions setting of your config object. This is how you could set a global proxy:

AWS.config.update({
  httpOptions: {
    proxy: 'http://localhost:8080'
  }
});

var s3 = new AWS.S3();
s3.getObject({Bucket: 'bucket', Key: 'key'}, function (err, data) {
  console.log(err, data);
});

Service-Specific Configuration

Occasionally, you might want to apply configuration only to one service. For instance, you want to use multiple EC2 objects in different regions. You can do this by passing configuration data directly to the service object constructor:

var ec2 = new AWS.EC2({region: 'ap-southeast-2', maxRetries: 15});

Note that the constructor takes all of the same configuration data as the AWS.config object described above, including credential information.

Immutable Configuration Data

Global configuration changes apply to all requests for all newly created services. Any newly created service will merge its local options on top of the global configuration data at the time of creation. This means that any future updates to the global AWS.config object will not apply to existing service objects. These services would have to be manually updated with the new configuration data, or recreated using the following command (assuming an existing s3 service object):

s3 = new AWS.S3(s3.config);