NAME

AWS::Credentials

SYNOPSIS

 my $aws_creds = new Amazon::Credentials({order => [qw/env file container role/]});

DESCRIPTION

Class to find AWS credentials from either the environment, configuration files, instance meta-data or container role.

You can specify the order using the order option in the constructor to determine the order in which the class will look for credentials. The default order is environent, file, container, instance meta-data. See "new".

METHODS

new

 new( options );

 my $aws_creds = new Amazon::Credential( { profile => 'sandbox', debug => 1 });

options is a hash of keys that represent options. Any of the options can also be retrieved using their corresponding 'get_{option} method.

Options are listed below.

aws_access_key_id

AWS access key.

aws_secret_access_key

AWS secret access key.

Note: If you pass the access keys in the constructor then the constructor will not look in other places for credentials.

debug

Set to true for verbose troubleshooting information.

logger

Pass in your own logger that has a debug() method. Otherwise the default logger will output debug messages to STDERR.

user_agent

Pass in your own user agent, otherwise LWP will be used. Probably only useful to override this for testing purposes.

profile

The profile name in the configuration file (~/.aws/config or ~/.aws/credentials).

 my $aws_creds = new Amazon::Credentials({ profile => 'sandbox' });

The class will also look for the environment variable AWS_PROFILE, so you can invoke your script like this:

 $ AWS_PROFILE=sandbox my-script.pl
order

An array reference containing tokens that specifies the order in which the class will search for credentials.

default: role, env, file

Example:

  my $creds = new Amazon::Credentials( { order => [ qw/file env role/] });
env - Environment

If there exists an environment variable $AWS_PROFILE, then an attempt will be made to retrieve credentials from the credentials file using that profile, otherwise we'll look for these environment variables to provide credentials.

AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Note that when you set the environment variable AWS_PROFILE, the order essentially is overridden and we'll look in your credential files (~/.aws/config, ~/.aws/credentials) for your credentials.

file - Configuration Files
~/.aws/config
~/.aws/credentials

The class will attempt to find the credentials in either of these two files. You can also specify a profile to use for looking up the credentials by passing it into the constructor or setting in an the environment variable AWS_PROFILE. If no profile is provided, the default credentials or the first profile found is used.

 my $aws_creds = new Amazon::Credentials({ order => [qw/environment role file/] });
container - Task Role

If the process is running in a container, the container may have a task role. We'll look credentials using the container metadata service.

 http://169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
role - Instance Role

The class will use the http://169.254.169.254/latest/meta-data/iam/security-credential URL to look for an instance role and credentials.

Keep in mind that these credentials include a token that needs to be passed to Amazon APIs when using the credentials returned when using instance meta-data. That token has an expiration and should be refreshed as required.

 if ( $aws_creds->is_token_expired() ) {
   $aws_creds->refresh_token()
 }
region

Default region. The class will attempt to find the region in either the configuration files or the instance unless you specify the region in the constructor.

get_default_region

Returns the region of the currently running instance. The constructor will set the region to this value unless you set your own region value. Use get_region to retrieve the value after instantiation or you can call this method again and it will make a second call to retrieve the instance metadata.

You can also invoke this as a class method:

 $ AWS_REGION=$(perl -MAmazon::Credentials -e 'print Amazon::Credentials::get_default_region;')

get_ec2_credentials (deprecated)

find_credentidals

 find_credentials( option => value, ...);

You normally don't want to use this method. It's automatically invoked by the constructor if you don't pass in any credentials. Accepts a hash or hash reference consisting of keys (order or profile) in the same manner as the constructor.

is_token_expired

 is_token_expired( window-interval )

Returns true if the token is about to expire (or is expired). window-interval is the time in minutes before the actual expiration time that the method should consider the token expired. The default is 5 minutes. Amazon states that new credentials will be available at least 5 minutes before a token expires.

get_creds_from_role

 get_creds_from_role()

Returns a hash, possibly containing access keys and a token.

aws_access_key_id

The AWS access key.

aws_secret_access_key

The AWS secret key.

token

Security token used with access keys.

expiration

Token expiration date.

role

IAM role if available.

source

Will be 'IAM' if role and credentials found.

refresh_token

 refresh_token() (deprecated)
 refresh_credentials()

Retrieves a fresh set of IAM credentials.

 if ( $creds->is_token_expired ) {
   $creds->refresh_token()
 }

AUTHOR

Rob Lauer - <rlauer6@comcast.net>

1 POD Error

The following errors were encountered while parsing the POD:

Around line 142:

Unterminated I<...> sequence