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.

[
  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

'/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

'/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:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :retries (Integer) — default: 1 —

    Number of times to retry when retrieving credentials.

  • :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
  • :delay (Numeric, Proc) —

    By default, failures are retried with exponential back-off, i.e. ‘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.

  • :http_debug_output (IO) — default: nil —

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

  • :token_ttl (Integer) —

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

  • :before_refresh (Callable) —

    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.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 79

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:

  • (Proc) 


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

def backoff
  @backoff
end

#disable_imds_v1 ⇒ Boolean0 (readonly)

Returns Boolean0.

Returns:

  • (Boolean0) —

    Boolean0



99
100
101
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 99

def disable_imds_v1
  @disable_imds_v1
end

#endpoint ⇒ String (readonly)

Returns:

  • (String) 


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

def endpoint
  @endpoint
end

#http_debug_output ⇒ IO? (readonly)

Returns:

  • (IO, nil) 


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

def http_debug_output
  @http_debug_output
end

#http_open_timeout ⇒ Integer (readonly)

Returns:

  • (Integer) 


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

def http_open_timeout
  @http_open_timeout
end

#http_read_timeout ⇒ Integer (readonly)

Returns:

  • (Integer) 


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

def http_read_timeout
  @http_read_timeout
end

#port ⇒ Integer (readonly)

Returns:

  • (Integer) 


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

def port
  @port
end

#retries ⇒ Integer (readonly)

Returns:

  • (Integer) 


105
106
107
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 105

def retries
  @retries
end

#token_ttl ⇒ Integer (readonly)

Returns:

  • (Integer) 


102
103
104
 
# File 'lib/aws-sdk-core/instance_profile_credentials.rb', line 102

def token_ttl
  @token_ttl
end