Class: Google::Cloud::Env

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/env.rb,
lib/google/cloud/env/version.rb,
lib/google/cloud/env/variables.rb,
lib/google/cloud/env/lazy_value.rb,
lib/google/cloud/env/file_system.rb,
lib/google/cloud/env/compute_smbios.rb,
lib/google/cloud/env/compute_metadata.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 can 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

Defined Under Namespace

Classes: ComputeMetadata, ComputeSMBIOS, FileSystem, MetadataServerNotResponding, Variables

Constant Summary collapse

VERSION =

Library version

Returns:

  • (String) 
"2.2.1".freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Env

Create a new instance of the environment information. Most clients should not need to call this directly. Obtain a singleton instance of the information from Google::Cloud.env.



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

def initialize
  @variables = Variables.new
  @file_system = FileSystem.new
  @compute_smbios = ComputeSMBIOS.new
  @compute_metadata = ComputeMetadata.new variables: @variables,
                                          compute_smbios: @compute_smbios
end

Instance Attribute Details

#compute_metadata ⇒ Google::Cloud::Env::ComputeMetadata (readonly)

The compute metadata access object. Use this to make direct calls to compute metadata or configure how metadata server queries are done, or to mock out the metadata server for testing.

Returns:



113
114
115
 
# File 'lib/google/cloud/env.rb', line 113

def compute_metadata
  @compute_metadata
end

#compute_smbios ⇒ Google::Cloud::Env::ComputeSMBIOS (readonly)

The compute SMBIOS access object. Use this to make direct queries for compute SMBIOS information, or to mock out the SMBIOS for testing.

Returns:



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

def compute_smbios
  @compute_smbios
end

#file_system ⇒ Google::Cloud::Env::FileSystem (readonly)

The variables access object. Use this to make direct queries for information from the file system, or to mock out the file system for testing.

Returns:



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

def file_system
  @file_system
end

#variables ⇒ Google::Cloud::Env::Variables (readonly)

The variables access object. Use this to make direct queries for environment variable information, or to mock out environment variables for testing.

Returns:



87
88
89
 
# File 'lib/google/cloud/env.rb', line 87

def variables
  @variables
end

Class Method Details

.get ⇒ Google::Cloud::Env

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

Returns:



518
519
520
 
# File 'lib/google/cloud/env.rb', line 518

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) 


212
213
214
 
# File 'lib/google/cloud/env.rb', line 212

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

#app_engine_flexible? ⇒ boolean

Determine whether the application is running on Google App Engine Flexible Environment.

Returns:

  • (boolean) 


222
223
224
 
# File 'lib/google/cloud/env.rb', line 222

def app_engine_flexible?
  app_engine? && variables["GAE_ENV"] != "standard"
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) 


463
464
465
466
 
# File 'lib/google/cloud/env.rb', line 463

def app_engine_memory_mb
  result = variables["GAE_MEMORY_MB"]
  result&.to_i
end

#app_engine_service_id ⇒ String? Also known as: app_engine_service_name

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

Returns:

  • (String, nil) 


442
443
444
 
# File 'lib/google/cloud/env.rb', line 442

def app_engine_service_id
  variables["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) 


453
454
455
 
# File 'lib/google/cloud/env.rb', line 453

def app_engine_service_version
  variables["GAE_VERSION"]
end

#app_engine_standard? ⇒ boolean

Determine whether the application is running on Google App Engine Standard Environment.

Returns:

  • (boolean) 


232
233
234
 
# File 'lib/google/cloud/env.rb', line 232

def app_engine_standard?
  app_engine? && variables["GAE_ENV"] == "standard"
end

#cloud_shell? ⇒ boolean

Determine whether the application is running on Google Cloud Shell.

Returns:

  • (boolean) 


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

def cloud_shell?
  variables["GOOGLE_CLOUD_SHELL"] ? 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) 


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

def compute_engine?
  compute_smbios.google_compute?
end

#ensure_metadata(timeout: nil) ⇒ :confirmed

Assert that the Metadata Server should be present, and wait for a confirmed connection to ensure it is up. In general, this will run at most Google::Cloud::Env::ComputeMetadata::DEFAULT_WARMUP_TIME seconds to wait out the expected maximum warmup time, but a shorter timeout can be provided.

This method is useful call during application initialization to wait for the Metadata Server to warm up and ensure that subsequent lookups should succeed.

Parameters:

  • 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



149
150
151
 
# File 'lib/google/cloud/env.rb', line 149

def ensure_metadata timeout: nil
  compute_metadata.ensure_existence timeout: timeout
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) 


409
410
411
412
413
 
# File 'lib/google/cloud/env.rb', line 409

def instance_attribute key
  compute_metadata.lookup "instance/attributes/#{key}"
rescue MetadataServerNotResponding
  nil
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) 


394
395
396
397
398
399
 
# File 'lib/google/cloud/env.rb', line 394

def instance_attribute_keys
  result = compute_metadata.lookup "instance/attributes/"
  result&.split
rescue MetadataServerNotResponding
  nil
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) 


340
341
342
343
344
 
# File 'lib/google/cloud/env.rb', line 340

def instance_description
  compute_metadata.lookup "instance/description"
rescue MetadataServerNotResponding
  nil
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) 


366
367
368
369
370
371
 
# File 'lib/google/cloud/env.rb', line 366

def instance_machine_type
  result = compute_metadata.lookup "instance/machine-type"
  result&.split("/")&.last
rescue MetadataServerNotResponding
  nil
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) 


327
328
329
330
331
 
# File 'lib/google/cloud/env.rb', line 327

def instance_name
  variables["GAE_INSTANCE"] || compute_metadata.lookup("instance/name")
rescue MetadataServerNotResponding
  nil
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) 


380
381
382
383
384
385
 
# File 'lib/google/cloud/env.rb', line 380

def instance_tags
  result = compute_metadata.lookup "instance/tags"
  result.nil? ? nil : JSON.parse(result)
rescue MetadataServerNotResponding
  nil
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) 


353
354
355
356
357
358
 
# File 'lib/google/cloud/env.rb', line 353

def instance_zone
  result = compute_metadata.lookup "instance/zone"
  result&.split("/")&.last
rescue MetadataServerNotResponding
  nil
end

#knative? ⇒ boolean

Determine whether the application is running on a Knative-based hosting platform, such as Cloud Run or Cloud Functions.

Returns:

  • (boolean) 


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

def knative?
  variables["K_SERVICE"] ? true : false
end

#knative_service_id ⇒ String? Also known as: knative_service_name

Returns the name of the running Knative service, or nil if the current code is not running on Knative.

Returns:

  • (String, nil) 


421
422
423
 
# File 'lib/google/cloud/env.rb', line 421

def knative_service_id
  variables["K_SERVICE"]
end

#knative_service_revision ⇒ String?

Returns the revision of the running Knative service, or nil if the current code is not running on Knative.

Returns:

  • (String, nil) 


432
433
434
 
# File 'lib/google/cloud/env.rb', line 432

def knative_service_revision
  variables["K_REVISION"]
end

#kubernetes_engine? ⇒ boolean Also known as: container_engine?

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

Returns:

  • (boolean) 


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

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) 


475
476
477
478
479
 
# File 'lib/google/cloud/env.rb', line 475

def kubernetes_engine_cluster_name
  instance_attribute "cluster-name"
rescue MetadataServerNotResponding
  nil
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) 


489
490
491
492
493
494
495
496
497
 
# File 'lib/google/cloud/env.rb', line 489

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.
  variables["GKE_NAMESPACE_ID"] ||
    file_system.read("/var/run/secrets/kubernetes.io/serviceaccount/namespace")
end

#logging_agent_expected? ⇒ boolean

Determine whether the application is running in an environment where a Google Cloud logging agent is expected to be running. In such an environment, we expect that the standard output and error streams are likely to be parsed by the logging agent and log entries are written to the Google Cloud Logging service.

Returns:

  • (boolean) 


509
510
511
 
# File 'lib/google/cloud/env.rb', line 509

def logging_agent_expected?
  compute_engine? && !cloud_shell? && (app_engine? || knative? || kubernetes_engine?)
end

#lookup_metadata(type, entry, query: nil) ⇒ String?

Retrieve info from the Google Compute Engine Metadata Service. Returns nil if 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.

  • query (Hash{String => String}) (defaults to: nil) —

    Any additional query parameters to send with the request.

Returns:

  • (String) —

    the data

  • (nil) —

    if there is no data for the specified type and entry

Raises:

  • (MetadataServerNotResponding) —

    if the Metadata Server is not responding. This could either be because the metadata service is not present in the current environment, or if it is expected to be present but is overloaded or has not finished initializing.



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

def lookup_metadata type, entry, query: nil
  compute_metadata.lookup "#{type}/#{entry}", query: query
end

#lookup_metadata_response(type, entry, query: nil) ⇒ Google::Cloud::Env::ComputeMetadata::Response

Retrieve an HTTP response from the Google Compute Engine Metadata Service. Returns a Google::Cloud::Env::ComputeMetadata::Response with a status code, data, and headers. The response could be 200 for success, 404 if the given entry is not present, or other HTTP result code for authorization or other errors.

Parameters:

  • type (String) —

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

  • entry (String) —

    Metadata entry path to look up.

  • query (Hash{String => String}) (defaults to: nil) —

    Any additional query parameters to send with the request.

Returns:

Raises:

  • (MetadataServerNotResponding) —

    if the Metadata Server is not responding. This could either be because the metadata service is not present in the current environment, or if it is expected to be present but is overloaded or has not finished initializing.



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

def lookup_metadata_response type, entry, query: nil
  compute_metadata.lookup_response "#{type}/#{entry}", query: query
end

#metadata? ⇒ boolean

Determine whether the Google Compute Engine Metadata Service is running.

This method is conservative. It may block for a short period (up to about 1.5 seconds) while attempting to contact the server, but if this fails, this method will return false, even though it is possible that a future call could succeed. In particular, this might happen in environments where there is a warmup time for the Metadata Server. Early calls before the Server has warmed up may return false, while later calls return true.

Returns:

  • (boolean) 


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

def metadata?
  compute_metadata.check_existence == :confirmed
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) 


306
307
308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/google/cloud/env.rb', line 306

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 = begin
    compute_metadata.lookup "project/numeric-project-id"
  rescue MetadataServerNotResponding
    nil
  end
  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) 


289
290
291
292
293
294
295
296
 
# File 'lib/google/cloud/env.rb', line 289

def project_id
  variables["GOOGLE_CLOUD_PROJECT"] ||
    variables["GCLOUD_PROJECT"] ||
    variables["DEVSHELL_PROJECT_ID"] ||
    compute_metadata.lookup("project/project-id")
rescue MetadataServerNotResponding
  nil
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) 


279
280
281
 
# File 'lib/google/cloud/env.rb', line 279

def raw_compute_engine?
  compute_engine? && !knative? && !app_engine? && !cloud_shell? && !kubernetes_engine?
end