Class: Google::Cloud::Env

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/env.rb,
lib/google/cloud/env/version.rb

Overview

Google Cloud hosting environment

This library provides access to information about the application's hosting environment if it is running on Google Cloud Platform. You may use this library to determine which Google Cloud product is hosting your application (e.g. app engine, container engine), information about the Google Cloud project hosting the application, information about the virtual machine instance, authentication information, and so forth.

Usage

Obtain an instance of the environment info with:

require "google/cloud/env"
env = Google::Cloud.env

Then you can interrogate any fields using methods on the object.

if env.app_engine?
  # App engine specific logic
end

Any item that does not apply to the current environment will return nil. For example:

unless env.app_engine?
  service = env.app_engine_service_id  # => nil
end

Constant Summary collapse

VERSION = 
"1.0.0".freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(env: nil, connection: nil) ⇒ Env

Create a new instance of the environment information. Most client should not need to call this directly. Obtain a singleton instance of the information from Google::Cloud.env. This constructor is provided for internal testing and allows mocking of the data.

Parameters:

  • env (Hash) —

    Mock environment variables.

  • connection (Faraday::Connection) —

    Faraday connection to use.



71
72
73
74
75
76
77
 
# File 'lib/google/cloud/env.rb', line 71

def initialize env: nil, connection: nil
  @metadata_cache = {}
  @env = env || ::ENV
  @connection = connection ||
                ::Faraday.new(url: METADATA_HOST,
                              request: { timeout: 0.1 })
end

Class Method Details

.get ⇒ Google::Cloud::Env

Returns the global instance of Google::Cloud::Env.

Returns:



344
345
346
 
# File 'lib/google/cloud/env.rb', line 344

def self.get
  ::Google::Cloud.env
end

Instance Method Details

#app_engine? ⇒ Boolean

Determine whether the application is running on Google App Engine.

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/google/cloud/env.rb', line 84

def app_engine?
  env["GAE_INSTANCE"] ? true : false
end

#app_engine_memory_mb ⇒ Integer?

Returns the amount of memory reserved for the current App Engine instance, or nil if the current code is not running in App Engine.

Returns:

  • (Integer, nil) 


269
270
271
272
 
# File 'lib/google/cloud/env.rb', line 269

def app_engine_memory_mb
  result = env["GAE_MEMORY_MB"]
  result.nil? ? nil : result.to_i
end

#app_engine_service_id ⇒ String?

Returns the name of the running App Engine service, or nil if the current code is not running in App Engine.

Returns:

  • (String, nil) 


249
250
251
 
# File 'lib/google/cloud/env.rb', line 249

def app_engine_service_id
  env["GAE_SERVICE"]
end

#app_engine_service_version ⇒ String?

Returns the version of the running App Engine service, or nil if the current code is not running in App Engine.

Returns:

  • (String, nil) 


259
260
261
 
# File 'lib/google/cloud/env.rb', line 259

def app_engine_service_version
  env["GAE_VERSION"]
end

#cloud_shell? ⇒ Boolean

Determine whether the application is running on Google Cloud Shell.

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/google/cloud/env.rb', line 102

def cloud_shell?
  env["DEVSHELL_GCLOUD_CONFIG"] ? true : false
end

#compute_engine? ⇒ Boolean

Determine whether the application is running on Google Compute Engine.

Note that most other products (e.g. App Engine, Container Engine, Cloud Shell) themselves use Compute Engine under the hood, so this method will return true for all the above products. If you want to determine whether the application is running on a "raw" Compute Engine VM without using a higher level hosting product, use #raw_compute_engine?.

Returns:

  • (Boolean) 


118
119
120
 
# File 'lib/google/cloud/env.rb', line 118

def compute_engine?
  metadata?
end

#container_engine? ⇒ Boolean

Determine whether the application is running on Google Container Engine.

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/google/cloud/env.rb', line 93

def container_engine?
  container_engine_cluster_name ? true : false
end

#container_engine_cluster_name ⇒ String?

Returns the name of the Container Engine cluster hosting the application, or nil if the current code is not running in Container Engine.

Returns:

  • (String, nil) 


281
282
283
 
# File 'lib/google/cloud/env.rb', line 281

def container_engine_cluster_name
  instance_attribute "cluster-name"
end

#container_engine_namespace_id ⇒ String?

Returns the name of the Container Engine namespace hosting the application, or nil if the current code is not running in Container Engine.

Returns:

  • (String, nil) 


292
293
294
 
# File 'lib/google/cloud/env.rb', line 292

def container_engine_namespace_id
  env["GKE_NAMESPACE_ID"]
end

#instance_attribute(key) ⇒ String?

Returns the value of the given instance attribute for the VM instance hosting the application, or nil if the given key does not exist or application is not running on Google Cloud.

Parameters:

  • key (String) —

    Attribute key to look up.

Returns:

  • (String, nil) 


239
240
241
 
# File 'lib/google/cloud/env.rb', line 239

def instance_attribute key
  lookup_metadata "instance", "attributes/#{key}"
end

#instance_attribute_keys ⇒ Array<String>?

Returns an array (which may be empty) of all attribute keys present for the VM instance hosting the application, or nil if the application is not running on Google Cloud.

Returns:

  • (Array<String>, nil) 


226
227
228
229
 
# File 'lib/google/cloud/env.rb', line 226

def instance_attribute_keys
  result = lookup_metadata "instance", "attributes/"
  result.nil? ? nil : result.split
end

#instance_description ⇒ String?

Returns the description field (which may be the empty string) of the VM instance hosting the application, or nil if the application is not running on Google Cloud.

Returns:

  • (String, nil) 


180
181
182
 
# File 'lib/google/cloud/env.rb', line 180

def instance_description
  lookup_metadata "instance", "description"
end

#instance_machine_type ⇒ String?

Returns the machine type of the VM instance hosting the application, or nil if the application is not running on Google Cloud.

Returns:

  • (String, nil) 


202
203
204
205
 
# File 'lib/google/cloud/env.rb', line 202

def instance_machine_type
  result = lookup_metadata "instance", "machine-type"
  result.nil? ? nil : result.split("/").last
end

#instance_name ⇒ String?

Returns the name of the VM instance hosting the application, or nil if the application is not running on Google Cloud.

Returns:

  • (String, nil) 


169
170
171
 
# File 'lib/google/cloud/env.rb', line 169

def instance_name
  env["GAE_INSTANCE"] || lookup_metadata("instance", "name")
end

#instance_tags ⇒ Array<String>?

Returns an array (which may be empty) of all tags set on the VM instance hosting the application, or nil if the application is not running on Google Cloud.

Returns:

  • (Array<String>, nil) 


214
215
216
217
 
# File 'lib/google/cloud/env.rb', line 214

def instance_tags
  result = lookup_metadata "instance", "tags"
  result.nil? ? nil : JSON.parse(result)
end

#instance_zone ⇒ String?

Returns the zone (for example "us-central1-c") in which the instance hosting the application lives. Returns nil if the application is not running on Google Cloud.

Returns:

  • (String, nil) 


191
192
193
194
 
# File 'lib/google/cloud/env.rb', line 191

def instance_zone
  result = lookup_metadata "instance", "zone"
  result.nil? ? nil : result.split("/").last
end

#lookup_metadata(type, entry) ⇒ String?

Retrieve info from the Google Compute Engine Metadata Service. Returns nil if the Metadata Service is not running or the given data is not present.

Parameters:

  • type (String) —

    Type of metadata to look up. Currently supported values are "project" and "instance".

  • entry (String) —

    Metadata entry path to look up.

Returns:

  • (String, nil) 


324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/google/cloud/env.rb', line 324

def lookup_metadata type, entry
  path = "#{METADATA_PATH_BASE}/#{type}/#{entry}"
  if !metadata_cache.include?(path) && metadata?
    begin
      resp = connection.get path do |req|
        req.headers = { "Metadata-Flavor" => "Google" }
      end
      metadata_cache[path] = resp.status == 200 ? resp.body.strip : nil
    rescue ::Faraday::TimeoutError, ::Faraday::ConnectionFailed
      metadata_cache[path] = nil
    end
  end
  metadata_cache[path]
end

#metadata? ⇒ Boolean

Determine whether the Google Compute Engine Metadata Service is running.

Returns:

  • (Boolean) 


301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/google/cloud/env.rb', line 301

def metadata?
  unless metadata_cache.include?(METADATA_ROOT_PATH)
    begin
      resp = connection.get METADATA_ROOT_PATH
      metadata_cache[METADATA_ROOT_PATH] = \
        resp.status == 200 && resp.headers["Metadata-Flavor"] == "Google"
    rescue ::Faraday::TimeoutError, ::Faraday::ConnectionFailed
      metadata_cache[METADATA_ROOT_PATH] = false
    end
  end
  metadata_cache[METADATA_ROOT_PATH]
end

#numeric_project_id ⇒ Integer?

Returns the unique numeric ID of the project hosting the application, or nil if the application is not running on Google Cloud.

Caveat: this method does not work and returns nil on CloudShell.

Returns:

  • (Integer, nil) 


152
153
154
155
156
157
158
159
160
161
 
# File 'lib/google/cloud/env.rb', line 152

def numeric_project_id
  # CloudShell's metadata server seems to run in a dummy project.
  # We can get the user's normal project ID via environment variables,
  # but the numeric ID from the metadata service is not correct. So
  # disable this for CloudShell to avoid confusion.
  return nil if cloud_shell?

  result = lookup_metadata "project", "numeric-project-id"
  result.nil? ? nil : result.to_i
end

#project_id ⇒ String?

Returns the unique string ID of the project hosting the application, or nil if the application is not running on Google Cloud.

Returns:

  • (String, nil) 


139
140
141
142
 
# File 'lib/google/cloud/env.rb', line 139

def project_id
  env["GCLOUD_PROJECT"] || env["DEVSHELL_PROJECT_ID"] ||
    lookup_metadata("project", "project-id")
end

#raw_compute_engine? ⇒ Boolean

Determine whether the application is running on "raw" Google Compute Engine without using a higher level hosting product such as App Engine or Container Engine.

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/google/cloud/env.rb', line 129

def raw_compute_engine?
  !app_engine? && !cloud_shell? && metadata? && !container_engine?
end