Class: Aws::InstanceProfileCredentials

Inherits:
Object
  • Object
show all
Includes:
CredentialProvider, RefreshingCredentials
Defined in:
lib/aws-sdk-core/instance_profile_credentials.rb

Overview

An auto-refreshing credential provider that loads credentials from EC2 instances.

instance_credentials = Aws::InstanceProfileCredentials.new
ec2 = Aws::EC2::Client.new(credentials: instance_credentials)

## Retries When initialized from the default credential chain, this provider defaults to 0 retries. Breakdown of retries is as follows:

* **Configurable retries** (defaults to `1`): these retries handle errors when communicating
   with the IMDS endpoint. There are two separate retry mechanisms within the provider:
     * Entire token fetch and credential retrieval process
     * Token fetching
* **JSON parsing retries**: Fixed at 3 attempts to handle cases when IMDS returns malformed JSON
   responses. These retries are separate from configurable retries.

See Also:

Defined Under Namespace

Classes: Non200Response, Token, TokenExpiredError, TokenRetrivalError

Constant Summary collapse

NETWORK_ERRORS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

These are the errors we trap when attempting to talk to the instance metadata service. Any of these imply the service is not present, no responding or some other non-recoverable error.

API:

  • private

[
  Errno::EHOSTUNREACH,
  Errno::ECONNREFUSED,
  Errno::EHOSTDOWN,
  Errno::ENETUNREACH,
  SocketError,
  Timeout::Error,
  Non200Response
].freeze
METADATA_PATH_BASE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Path base for GET request for profile and credentials

API:

  • private

'/latest/meta-data/iam/security-credentials/'.freeze
METADATA_TOKEN_PATH =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Path for PUT request for token

API:

  • private

'/latest/api/token'.freeze

Constants included from RefreshingCredentials

RefreshingCredentials::ASYNC_EXPIRATION_LENGTH, RefreshingCredentials::CLIENT_EXCLUDE_OPTIONS, RefreshingCredentials::SYNC_EXPIRATION_LENGTH

Instance Attribute Summary collapse

Attributes included from CredentialProvider

#credentials, #expiration, #metrics

Instance Method Summary collapse

Methods included from RefreshingCredentials

#credentials, #refresh!

Methods included from CredentialProvider

#set?

Constructor Details

#initialize(options = {}) ⇒ InstanceProfileCredentials

Returns a new instance of InstanceProfileCredentials.

Parameters:

  • (defaults to: {})

Options Hash (options):

  • :retries (Integer) — default: 1 —

    Number of times to retry when retrieving credentials.

  • :backoff (Numeric, Proc) —

    By default, failures are retried with exponential back-off, i.e. ‘lambda { |num_failures| sleep(1.2 ** num_failures) }`. You can pass a number of seconds to sleep between failed attempts, or a Proc that accepts the number of failures.

  • :endpoint (String) — default: 'http://169.254.169.254' —

    The IMDS endpoint. This option has precedence over the :endpoint_mode.

  • :endpoint_mode (String) — default: 'IPv4' —

    The endpoint mode for the instance metadata service. This is either ‘IPv4’ (169.254.169.254) or IPv6’ ([fd00:ec2::254]).

  • :disable_imds_v1 (Boolean) — default: false —

    Disable the use of the legacy EC2 Metadata Service v1.

  • :ip_address (String) — default: '169.254.169.254' —

    Deprecated. Use :endpoint instead. The IP address for the endpoint.

  • :port (Integer) — default: 80
  • :http_open_timeout (Float) — default: 1
  • :http_read_timeout (Float) — default: 1
  • :http_debug_output (IO) — default: nil —

    HTTP wire traces are sent to this object. You can specify something like ‘$stdout`.

  • :token_ttl (Integer) — default: 21600 —

    Time-to-Live in seconds for EC2 Metadata Token used for fetching Metadata Profile Credentials.

  • :before_refresh (Proc) —

    A Proc called before credentials are refreshed. :before_refresh is called with an instance of this object when AWS credentials are required and need to be refreshed.



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 89

def initialize(options = {})
  @backoff = resolve_backoff(options[:backoff])
  @disable_imds_v1 = resolve_disable_v1(options)
  @endpoint = resolve_endpoint(options)
  @http_open_timeout = options[:http_open_timeout] || 1
  @http_read_timeout = options[:http_read_timeout] || 1
  @http_debug_output = options[:http_debug_output]
  @port = options[:port] || 80
  @retries = options[:retries] || 1
  @token_ttl = options[:token_ttl] || 21_600

  @async_refresh = false
  @imds_v1_fallback = false
  @no_refresh_until = nil
  @token = nil
  @metrics = ['CREDENTIALS_IMDS']
  super
end

Instance Attribute Details

#backoff ⇒ Proc (readonly)

Returns:



118
119
120
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 118

def backoff
  @backoff
end

#disable_imds_v1 ⇒ Boolean (readonly)

Returns:



109
110
111
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 109

def disable_imds_v1
  @disable_imds_v1
end

#endpoint ⇒ String (readonly)

Returns:



121
122
123
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 121

def endpoint
  @endpoint
end

#http_debug_output ⇒ IO? (readonly)

Returns:



133
134
135
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 133

def http_debug_output
  @http_debug_output
end

#http_open_timeout ⇒ Integer (readonly)

Returns:



127
128
129
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 127

def http_open_timeout
  @http_open_timeout
end

#http_read_timeout ⇒ Integer (readonly)

Returns:



130
131
132
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 130

def http_read_timeout
  @http_read_timeout
end

#port ⇒ Integer (readonly)

Returns:



124
125
126
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 124

def port
  @port
end

#retries ⇒ Integer (readonly)

Returns:



115
116
117
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 115

def retries
  @retries
end

#token_ttl ⇒ Integer (readonly)

Returns:



112
113
114
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 112

def token_ttl
  @token_ttl
end