Better document support for IAM Roles

[willwhite]

According to Configuring the SDK support exists of loading AWS credentials "from EC2 metadata service". I'm familiar with IAM roles and STS, but I'd love understand the correct way to use those tools with this SDK.

I'm also curious why "in order of recommendation" it's listed number three. Given the option it seems reasonable to recommend IAM roles and STS in most cases.

[lsegal]

I'd love understand the correct way to use those tools with this SDK.

You are correct in associating the EC2 metadata service with IAM roles. The correct terminology should in fact be "IAM roles for EC2 instances"-- we should update the guide to reflect this.

You're also right that IAM roles should definitely be preferred over env vars or configuration files on disk. The verbage is a little inaccurate in the guide; the rationale for that order is that the SDK always looks for credentials from the EC2 instance metadata last, because this is a slow operation on non-EC2 instances, since it is making an HTTP request to a local IP that might not be present. We would also only be recommending that be used if the SDK is used on an EC2 instance, of course, which we should update the guide to reflect.

[willwhite]

Great, thanks for the fast reply. Does the SDK behave like the Ruby SDK where the metadata API is checked automatically if credentials aren't provide directly or do I have to turn this feature on explicitly?

[lsegal]

The feature is enabled by default. Sorry I forgot to mention this. The SDK works with "zero configuration" if you have IAM roles enabled on an instance.

[willwhite]

Great thanks. I'll poke around and see about a pull request for the docs.

[onetom]

It would be great to show an example in the documentation what does "zero configuration" mean.
Something like this:

$ cat aws-credentials.js
    AWS=require('aws-sdk');
    ... ??? ...
    console.log(AWS.config.credentials);
$ ROLE=$( curl http://169.254.169.254/latest/meta-data/iam/security-credentials/ )
$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE
$ node aws-credentials.js
$ AWS_ACCESS_KEY_ID='xxxx' AWS_SECRET_ACCESS_KEY='xxxx' node aws-credentials.js

Q1: When using the EC2MetadataCredentials will it refresh the credentials when they expire?

Q2: Why is it necessary to specify the region? Shouldn't it be specified automatically using the metadata too?
for example curl http://169.254.169.254/latest/dynamic/instance-identity/document/ | grep region

[lsegal]

@onetom "zero configuration" literally means that there is zero configuration for your application to use credentials from the instance metadata service. I'm not sure what your example shows?

As for questions:

Q1: When using the EC2MetadataCredentials will it refresh the credentials when they expire?

Yes.

Q2: Why is it necessary to specify the region? Shouldn't it be specified automatically using the metadata too?

The region that the EC2 instance is located is not necessarily the region in which your other resources live. It may be the case that this is true, but defaulting this value can lead to confusing behavior if a user forgets to configure their region. You can certainly setup your machine to export AWS_REGION from the instance metadata, but it should be something users explicitly choose to avoid confusion about what region the SDK is operating in.

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.