Google Cloud Platform environment queries - Class Google::Cloud::Env::ComputeMetadata (v2.2.2)

Reference documentation and code samples for the Google Cloud Platform environment queries class Google::Cloud::Env::ComputeMetadata.

A client for the Google metadata service.

Inherits

  • Object

Methods

#check_existence

def check_existence(open_timeout: nil, request_timeout: nil, retry_count: :default, retry_timeout: :default) -> :no, :unconfirmed, :confirmed

Return detailed information about whether we think Metadata is available. If we have not previously confirmed existence one way or another, this could block while trying to contact the server through the given timeouts and retries.

Parameters
  • open_timeout (Numeric) (defaults to: nil) — Timeout for opening http connections. Defaults to #open_timeout.
  • request_timeout (Numeric) (defaults to: nil) — Timeout for entire http requests. Defaults to #request_timeout.
  • retry_count (Integer, nil) (defaults to: :default) — Number of times to retry. A value of 1 means 2 attempts (i.e. 1 retry). A value of nil indicates retries are limited only by the timeout. Defaults to #retry_count.
  • retry_timeout (Numeric, nil) (defaults to: :default) — Total timeout for retries. A value of nil indicates no time limit, and retries are limited only by count. Defaults to #retry_timeout.
Returns
  • (:no) — if we know the metadata server is not present
  • (:unconfirmed) — if we believe metadata should be present but we haven't gotten a confirmed response from it. This can happen if SMBIOS says we're on GCE but we can't contact the Metadata Server even through retries.
  • (:confirmed) — if we have a confirmed response from metadata.

#ensure_existence

def ensure_existence(timeout: nil) -> :confirmed

Assert that the Metadata Server should be present, and wait for a confirmed connection to ensure it is up. This will generally run at most #warmup_time seconds to wait out the expected maximum warmup time, but a shorter timeout can be provided.

Parameter
  • timeout (Numeric, nil) (defaults to: nil) — a timeout in seconds, or nil to wait until we have conclusively decided one way or the other.
Returns
  • (:confirmed) — if we were able to confirm connection.
Raises
  • (MetadataServerNotResponding) — if we were unable to confirm connection with the Metadata Server, either because the timeout expired or because the server seems to be down

#existence_immediate

def existence_immediate() -> nil, :no, :unconfirmed, :confirmed

The current detailed existence status, without blocking on any attempt to contact the metadata server.

Returns
  • (nil) — if we have no information at all yet
  • (:no) — if we know the metadata server is not present
  • (:unconfirmed) — if we believe metadata should be present but we haven't gotten a confirmed response from it.
  • (:confirmed) — if we have a confirmed response from metadata.

#expiration_time_of

def expiration_time_of(path, query: nil) -> Numeric, nil, false

Get the expiration time for the given path. Returns the monotonic time if the data has been retrieved and has an expiration, nil if the data has been retrieved but has no expiration, or false if the data has not yet been retrieved.

Returns
  • (Numeric, nil, false)

#host

def host() -> String

The host URL for the metadata server, including http://.

Returns
  • (String)

#host=

def host=(new_host)

The host URL for the metadata server, including http://.

#initialize

def initialize(variables: nil, compute_smbios: nil) -> ComputeMetadata

Create a compute metadata access object.

Parameters
Returns

#lookup

def lookup(path, query: nil, open_timeout: nil, request_timeout: nil, retry_count: :default, retry_timeout: :default) -> String, nil

Look up a particular key from the metadata server and return the data as a string. Could return a cached value if the key has been queried before, otherwise this could block while trying to contact the server through the given timeouts and retries.

This returns the HTTP body as a string, only if the call succeeds. If the key is inaccessible or missing (i.e. the HTTP status was not 200) or does not have the correct Metadata-Flavor header, then nil is returned. If you need more detailed information, use #lookup_response.

Parameters
  • path (String) — The key path (e.g. project/project-id)
  • query (Hash{String => String}) (defaults to: nil) — Any additional query parameters to send with the request.
  • open_timeout (Numeric) (defaults to: nil) — Timeout for opening http connections. Defaults to #open_timeout.
  • request_timeout (Numeric) (defaults to: nil) — Timeout for entire http requests. Defaults to #request_timeout.
  • retry_count (Integer, nil) (defaults to: :default) — Number of times to retry. A value of 1 means 2 attempts (i.e. 1 retry). A value of nil indicates retries are limited only by the timeout. Defaults to #retry_count.
  • retry_timeout (Numeric, nil) (defaults to: :default) — Total timeout for retries. A value of nil indicates no time limit, and retries are limited only by count. Defaults to #retry_timeout.
Returns
  • (String) — the data from the metadata server
  • (nil) — if the key is not present
Raises

#lookup_response

def lookup_response(path, query: nil, open_timeout: nil, request_timeout: nil, retry_count: :default, retry_timeout: :default) -> Response

Look up a particular key from the metadata server, and return a full Response object. Could return a cached value if the key has been queried before, otherwise this could block while trying to contact the server through the given timeouts and retries.

This returns a Response object even if the HTTP status is 404, so be sure to check the status code to determine whether the key actually exists. Unlike #lookup, this method does not return nil.

Parameters
  • path (String) — The key path (e.g. project/project-id)
  • query (Hash{String => String}) (defaults to: nil) — Any additional query parameters to send with the request.
  • open_timeout (Numeric) (defaults to: nil) — Timeout for opening http connections. Defaults to #open_timeout.
  • request_timeout (Numeric) (defaults to: nil) — Timeout for entire http requests. Defaults to #request_timeout.
  • retry_count (Integer, nil) (defaults to: :default) — Number of times to retry. A value of 1 means 2 attempts (i.e. 1 retry). A value of nil indicates retries are limited only by the timeout. Defaults to #retry_count.
  • retry_timeout (Numeric, nil) (defaults to: :default) — Total timeout for retries. A value of nil indicates no time limit, and retries are limited only by count. Defaults to #retry_timeout.
Returns
  • (Response) — the data from the metadata server
Raises

#open_timeout

def open_timeout() -> Numeric

The timeout for opening http connections in seconds.

Returns
  • (Numeric)

#open_timeout=

def open_timeout=(timeout)

The timeout for opening http connections in seconds.

Parameter
  • timeout (Numeric)

#overrides

def overrides() -> Overrides, nil

The overrides, or nil if overrides are not present. If present, overrides will answer all metadata queries, and actual calls to the metadata server will be blocked.

Returns

#overrides=

def overrides=(new_overrides)

Set the overrides. You can also set nil to disable overrides. If present, overrides will answer all metadata queries, and actual calls to the metadata server will be blocked.

#request_timeout

def request_timeout() -> Numeric

The total timeout for an HTTP request in seconds.

Returns
  • (Numeric)

#request_timeout=

def request_timeout=(timeout)

The total timeout for an HTTP request in seconds.

Parameter
  • timeout (Numeric)

#retry_count

def retry_count() -> Integer, nil

The default maximum number of times to retry a query for a key. A value of 1 means 2 attempts (i.e. 1 retry). A value of nil means there is no limit to the number of retries, although there could be an overall timeout.

Defaults to DEFAULT_RETRY_COUNT.

Returns
  • (Integer, nil)

#retry_count=

def retry_count=(value) -> Integer, nil

The default maximum number of times to retry a query for a key. A value of 1 means 2 attempts (i.e. 1 retry). A value of nil means there is no limit to the number of retries, although there could be an overall timeout.

Defaults to DEFAULT_RETRY_COUNT.

Parameter
  • value (Integer, nil)
Returns
  • (Integer, nil)

#retry_interval

def retry_interval() -> Numeric

The time in seconds between retries. This time includes the time spent by the previous attempt.

Defaults to DEFAULT_RETRY_INTERVAL.

Returns
  • (Numeric)

#retry_interval=

def retry_interval=(value) -> Numeric

The time in seconds between retries. This time includes the time spent by the previous attempt.

Defaults to DEFAULT_RETRY_INTERVAL.

Parameter
  • value (Numeric)
Returns
  • (Numeric)

#retry_timeout

def retry_timeout() -> Numeric, nil

The default overall timeout across all retries of a lookup, in seconds. A value of nil means there is no timeout, although there could be a limit to the number of retries.

Defaults to DEFAULT_RETRY_TIMEOUT.

Returns
  • (Numeric, nil)

#retry_timeout=

def retry_timeout=(value) -> Numeric, nil

The default overall timeout across all retries of a lookup, in seconds. A value of nil means there is no timeout, although there could be a limit to the number of retries.

Defaults to DEFAULT_RETRY_TIMEOUT.

Parameter
  • value (Numeric, nil)
Returns
  • (Numeric, nil)

#warmup_time

def warmup_time() -> Numeric, nil

A time in seconds allotted to environment warmup, during which retries will not be ended. This handles certain environments in which the Metadata Server might not be fully awake until some time after application startup. A value of nil disables this warmup period.

Defaults to DEFAULT_WARMUP_TIME.

Returns
  • (Numeric, nil)

#warmup_time=

def warmup_time=(value) -> Numeric, nil

A time in seconds allotted to environment warmup, during which retries will not be ended. This handles certain environments in which the Metadata Server might not be fully awake until some time after application startup. A value of nil disables this warmup period.

Defaults to DEFAULT_WARMUP_TIME.

Parameter
  • value (Numeric, nil)
Returns
  • (Numeric, nil)

#with_overrides

def with_overrides(temp_overrides)

Run the given block with the overrides replaced with the given set (or nil to disable overrides in the block). The original overrides setting is restored at the end of the block. This is used for debugging/testing/mocking.

Parameter

Constants

DEFAULT_HOST

value: "http://169.254.169.254"
The default host for the metadata server

DEFAULT_OPEN_TIMEOUT

value: 0.1
The default timeout in seconds for opening http connections

DEFAULT_REQUEST_TIMEOUT

value: 0.5
The default timeout in seconds for request responses

DEFAULT_RETRY_COUNT

value: 2
The default number of retries

DEFAULT_RETRY_TIMEOUT

value: nil
The default timeout across retries

DEFAULT_RETRY_INTERVAL

value: 0.5
The default interval between retries, in seconds

DEFAULT_WARMUP_TIME

value: 60
The default time in seconds to wait for environment warmup.