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, Kubernetes 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.2".freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(env: nil, connection: nil, metadata_cache: 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.

  • metadata_cache (Hash) —

    Mock cache.



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

def initialize env: nil, connection: nil, metadata_cache: nil
  @metadata_cache = 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:



359
360
361
 
# File 'lib/google/cloud/env.rb', line 359

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) 


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

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) 


272
273
274
275
 
# File 'lib/google/cloud/env.rb', line 272

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) 


252
253
254
 
# File 'lib/google/cloud/env.rb', line 252

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) 


262
263
264
 
# File 'lib/google/cloud/env.rb', line 262

def app_engine_service_version
  env["GAE_VERSION"]
end

#cloud_shell? ⇒ Boolean

Determine whether the application is running on Google Cloud Shell.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/google/cloud/env.rb', line 105

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, Kubernetes 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) 


121
122
123
 
# File 'lib/google/cloud/env.rb', line 121

def compute_engine?
  metadata?
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) 


242
243
244
 
# File 'lib/google/cloud/env.rb', line 242

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) 


229
230
231
232
 
# File 'lib/google/cloud/env.rb', line 229

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) 


183
184
185
 
# File 'lib/google/cloud/env.rb', line 183

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) 


205
206
207
208
 
# File 'lib/google/cloud/env.rb', line 205

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) 


172
173
174
 
# File 'lib/google/cloud/env.rb', line 172

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) 


217
218
219
220
 
# File 'lib/google/cloud/env.rb', line 217

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) 


194
195
196
197
 
# File 'lib/google/cloud/env.rb', line 194

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

#kubernetes_engine? ⇒ Boolean Also known as: container_engine?

Determine whether the application is running on Google Kubernetes Engine (GKE).

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/google/cloud/env.rb', line 95

def kubernetes_engine?
  kubernetes_engine_cluster_name ? true : false
end

#kubernetes_engine_cluster_name ⇒ String? Also known as: container_engine_cluster_name

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

Returns:

  • (String, nil) 


284
285
286
 
# File 'lib/google/cloud/env.rb', line 284

def kubernetes_engine_cluster_name
  instance_attribute "cluster-name"
end

#kubernetes_engine_namespace_id ⇒ String? Also known as: container_engine_namespace_id

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

Returns:

  • (String, nil) 


296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/google/cloud/env.rb', line 296

def kubernetes_engine_namespace_id
  # The Kubernetes namespace is difficult to obtain without help from
  # the application using the Downward API. The environment variable
  # below is set in some older versions of GKE, and the file below is
  # present in Kubernetes as of version 1.9, but it is possible that
  # alternatives will need to be found in the future.
  env["GKE_NAMESPACE_ID"] ||
    ::IO.read("/var/run/secrets/kubernetes.io/serviceaccount/namespace")
rescue SystemCallError
  nil
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) 


338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/google/cloud/env.rb', line 338

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,
           Errno::EHOSTDOWN
      metadata_cache[path] = nil
    end
  end
  metadata_cache[path]
end

#metadata? ⇒ Boolean

Determine whether the Google Compute Engine Metadata Service is running.

Returns:

  • (Boolean) 


314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/google/cloud/env.rb', line 314

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,
           Errno::EHOSTDOWN
      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) 


155
156
157
158
159
160
161
162
163
164
 
# File 'lib/google/cloud/env.rb', line 155

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) 


142
143
144
145
 
# File 'lib/google/cloud/env.rb', line 142

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 Kubernetes Engine.

Returns:

  • (Boolean) 


132
133
134
 
# File 'lib/google/cloud/env.rb', line 132

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