Class: Aws::EC2Metadata

Inherits:
Object
  • Object
show all
Defined in:
lib/aws-sdk-core/ec2_metadata.rb

Overview

A client that can query version 2 of the EC2 Instance Metadata

Defined Under Namespace

Classes: MetadataNotFoundError, RequestForbiddenError, Token, TokenExpiredError, TokenRetrievalError

Constant Summary collapse

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

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ EC2Metadata

Note:

Customers using containers may need to increase their hop limit to access IMDSv2.

Creates a client that can query version 2 of the EC2 Instance Metadata

service (IMDS).

Parameters:

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

Options Hash (options):

  • :token_ttl (Integer) — default: 21600 —

    The session token’s TTL, defaulting to 6 hours.

  • :retries (Integer) — default: 3 —

    The number of retries for failed requests.

  • :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]’).

  • :port (Integer) — default: 80 —

    The IMDS endpoint port.

  • :http_open_timeout (Integer) — default: 1 —

    The number of seconds to wait for the connection to open.

  • :http_read_timeout (Integer) — default: 1 —

    The number of seconds for one chunk of data to be read.

  • :http_debug_output (IO) —

    An output stream for debugging. Do not use this in production.

  • :backoff (Integer, Proc) —

    A backoff used for retryable requests. When given an Integer, it sleeps that amount. When given a Proc, it is called with the current number of failed retries.

See Also:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/aws-sdk-core/ec2_metadata.rb', line 57

def initialize(options = {})
  @token_ttl = options[:token_ttl] || 21_600
  @retries = options[:retries] || 3
  @backoff = backoff(options[:backoff])

  endpoint_mode = options[:endpoint_mode] || 'IPv4'
  @endpoint = resolve_endpoint(options[:endpoint], endpoint_mode)
  @port = options[:port] || 80

  @http_open_timeout = options[:http_open_timeout] || 1
  @http_read_timeout = options[:http_read_timeout] || 1
  @http_debug_output = options[:http_debug_output]

  @token = nil
  @mutex = Mutex.new
end

Instance Method Details

#get(path) ⇒ Object

Note:

This implementation always returns a String and will not parse any responses. Parsable responses may include JSON objects or directory listings, which are strings separated by line feeds (ASCII 10).

Note:

Unlike other services, IMDS does not have a service API model. This means that we cannot confidently generate code with methods and response structures. This implementation ensures that new IMDS features are always supported by being deployed to the instance and does not require code changes.

Fetches a given metadata category using a String path, and returns the

result as a String. A path starts with the API version (usually
"/latest/"). See the instance data categories for possible paths.

Examples:

Fetching the instance ID


ec2_metadata = Aws::EC2Metadata.new
ec2_metadata.get('/latest/meta-data/instance-id')
=> "i-023a25f10a73a0f79"

Fetching and parsing JSON meta-data


require 'json'
data = ec2_metadata.get('/latest/dynamic/instance-identity/document')
JSON.parse(data)
=> {"accountId"=>"012345678912", ... }

Fetching and parsing directory listings


listing = ec2_metadata.get('/latest/meta-data')
listing.split(10.chr)
=> ["ami-id", "ami-launch-index", ...]

Parameters:

  • path (String) —

    The full path to the metadata.

See Also:



110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/aws-sdk-core/ec2_metadata.rb', line 110

def get(path)
  retry_errors(max_retries: @retries) do
    @mutex.synchronize do
      fetch_token unless @token && !@token.expired?
    end

    open_connection do |conn|
      http_get(conn, path, @token.value)
    end
  end
end