Better document support for IAM Roles #153

Closed
willwhite opened this Issue Aug 27, 2013 · 6 comments

Projects

None yet

3 participants

@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
Contributor
lsegal commented Aug 27, 2013

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
Contributor
lsegal commented Aug 27, 2013

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
onetom commented Dec 27, 2013

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
Contributor
lsegal commented Dec 27, 2013

@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.

@lsegal lsegal pushed a commit that closed this issue Aug 19, 2014
Loren Segal Update guide to explain IAM role cred config
Close #153
a8dad90
@lsegal lsegal closed this in a8dad90 Aug 19, 2014
@lsegal lsegal pushed a commit that referenced this issue Aug 21, 2014
Loren Segal Update guide to explain IAM role cred config
Re-applying this commit, since it got lost.

Closes #153
45f693e
@AdityaManohar AdityaManohar added a commit that referenced this issue Sep 11, 2014
@AdityaManohar AdityaManohar Tag release v2.0.16
References:
  #153, #342, #343, #345, #349, #352, #353
57cee39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment