class Google::Cloud::Env

## 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:

“‘ruby require “google/cloud/env” env = Google::Cloud.env “`

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

“‘ruby if env.app_engine?

# App engine specific logic

end “‘

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

“‘ruby unless env.app_engine?

service = env.app_engine_service_id  # => nil

end “‘

Constants

VERSION

Library version @return [String]

Attributes

compute_metadata[R]

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.

@return [Google::Cloud::Env::ComputeMetadata]

compute_smbios[R]

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

@return [Google::Cloud::Env::ComputeSMBIOS]

file_system[R]

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.

@return [Google::Cloud::Env::FileSystem]

variables[R]

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

@return [Google::Cloud::Env::Variables]

Public Class Methods

get() click to toggle source

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

@return [Google::Cloud::Env]

# File lib/google/cloud/env.rb, line 518
def self.get
  ::Google::Cloud.env
end
new() click to toggle source

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`.

# 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

Public Instance Methods

app_engine?() click to toggle source

Determine whether the application is running on Google App Engine.

@return [boolean]

# File lib/google/cloud/env.rb, line 212
def app_engine?
  variables["GAE_INSTANCE"] ? true : false
end
app_engine_flexible?() click to toggle source

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

@return [boolean]

# File lib/google/cloud/env.rb, line 222
def app_engine_flexible?
  app_engine? && variables["GAE_ENV"] != "standard"
end
app_engine_memory_mb() click to toggle source

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

@return [Integer,nil]

# 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() click to toggle source

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

@return [String,nil]

# File lib/google/cloud/env.rb, line 442
def app_engine_service_id
  variables["GAE_SERVICE"]
end
Also aliased as: app_engine_service_name
app_engine_service_name()
app_engine_service_version() click to toggle source

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

@return [String,nil]

# File lib/google/cloud/env.rb, line 453
def app_engine_service_version
  variables["GAE_VERSION"]
end
app_engine_standard?() click to toggle source

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

@return [boolean]

# File lib/google/cloud/env.rb, line 232
def app_engine_standard?
  app_engine? && variables["GAE_ENV"] == "standard"
end
cloud_shell?() click to toggle source

Determine whether the application is running on Google Cloud Shell.

@return [boolean]

# File lib/google/cloud/env.rb, line 252
def cloud_shell?
  variables["GOOGLE_CLOUD_SHELL"] ? true : false
end
compute_engine?() click to toggle source

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 {Env#raw_compute_engine?}.

@return [boolean]

# File lib/google/cloud/env.rb, line 268
def compute_engine?
  compute_smbios.google_compute?
end
container_engine?()
Alias for: kubernetes_engine?
container_engine_cluster_name()
container_engine_namespace_id()
ensure_metadata(timeout: nil) click to toggle source

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 {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.

@param timeout [Numeric,nil] a timeout in seconds, or nil to wait

until we have conclusively decided one way or the other.

@return [:confirmed] if we were able to confirm connection. @raise [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
# File lib/google/cloud/env.rb, line 149
def ensure_metadata timeout: nil
  compute_metadata.ensure_existence timeout: timeout
end
instance_attribute(key) click to toggle source

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.

@param [String] key Attribute key to look up. @return [String,nil]

# 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() click to toggle source

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.

@return [Array<String>,nil]

# 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() click to toggle source

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.

@return [String,nil]

# File lib/google/cloud/env.rb, line 340
def instance_description
  compute_metadata.lookup "instance/description"
rescue MetadataServerNotResponding
  nil
end
instance_machine_type() click to toggle source

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

@return [String,nil]

# 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() click to toggle source

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

@return [String,nil]

# 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() click to toggle source

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.

@return [Array<String>,nil]

# 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() click to toggle source

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.

@return [String,nil]

# 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?() click to toggle source

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

@return [boolean]

# File lib/google/cloud/env.rb, line 203
def knative?
  variables["K_SERVICE"] ? true : false
end
knative_service_id() click to toggle source

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

@return [String,nil]

# File lib/google/cloud/env.rb, line 421
def knative_service_id
  variables["K_SERVICE"]
end
Also aliased as: knative_service_name
knative_service_name()
Alias for: knative_service_id
knative_service_revision() click to toggle source

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

@return [String,nil]

# File lib/google/cloud/env.rb, line 432
def knative_service_revision
  variables["K_REVISION"]
end
kubernetes_engine?() click to toggle source

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

@return [boolean]

# File lib/google/cloud/env.rb, line 242
def kubernetes_engine?
  kubernetes_engine_cluster_name ? true : false
end
Also aliased as: container_engine?
kubernetes_engine_cluster_name() click to toggle source

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

@return [String,nil]

# 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() click to toggle source

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

@return [String,nil]

# 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?() click to toggle source

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.

@return [boolean]

# 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) click to toggle source

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

@param [String] type Type of metadata to look up. Currently supported

values are "project" and "instance".

@param [String] entry Metadata entry path to look up. @param query [Hash{String => String}] Any additional query parameters

to send with the request.

@return [String] the data @return [nil] if there is no data for the specified type and entry @raise [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.
# 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) click to toggle source

Retrieve an HTTP response from the Google Compute Engine Metadata Service. Returns a {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.

@param [String] type Type of metadata to look up. Currently supported

values are "project" and "instance".

@param [String] entry Metadata entry path to look up. @param query [Hash{String => String}] Any additional query parameters

to send with the request.

@return [Google::Cloud::Env::ComputeMetadata::Response] the response @raise [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.
# 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?() click to toggle source

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.

@return [boolean]

# File lib/google/cloud/env.rb, line 128
def metadata?
  compute_metadata.check_existence == :confirmed
end
numeric_project_id() click to toggle source

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.

@return [Integer,nil]

# 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() click to toggle source

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

@return [String,nil]

# 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?() click to toggle source

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.

@return [boolean]

# File lib/google/cloud/env.rb, line 279
def raw_compute_engine?
  compute_engine? && !knative? && !app_engine? && !cloud_shell? && !kubernetes_engine?
end