Class: Aws::InstanceProfileCredentials

Inherits:
Object
  • Object
show all
Includes:
CredentialProvider
Defined in:
gems/aws-sdk-core/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:

Instance Attribute Summary collapse

Attributes included from CredentialProvider

#credentials, #expiration

Instance Method Summary collapse

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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/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 'gems/aws-sdk-core/lib/aws-sdk-core/instance_profile_credentials.rb', line 114

def port
  @port
end

#retries ⇒ Integer (readonly)

Returns:

  • (Integer) 


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

def retries
  @retries
end

#token_ttl ⇒ Integer (readonly)

Returns:

  • (Integer) 


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

def token_ttl
  @token_ttl
end