Class: Gcloud::ResourceManager::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/resource_manager/project.rb,
lib/gcloud/resource_manager/project/list.rb,
lib/gcloud/resource_manager/project/updater.rb

Overview

# Project

Project is a high-level Google Cloud Platform entity. It is a container for ACLs, APIs, AppEngine Apps, VMs, and other Google Cloud Platform resources.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.update do |p|
  p.name = "My Project"
  p.labels["env"] = "production"
end

Direct Known Subclasses

Updater

Defined Under Namespace

Classes: List, Updater

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Project

Returns a new instance of Project.



52
53
54
55
 
# File 'lib/gcloud/resource_manager/project.rb', line 52

def initialize
  @service = nil
  @gapi = Gcloud::ResourceManager::Service::API::Project.new
end

Instance Attribute Details

#gapi ⇒ Object 



48
49
50
 
# File 'lib/gcloud/resource_manager/project.rb', line 48

def gapi
  @gapi
end

#service ⇒ Object 



44
45
46
 
# File 'lib/gcloud/resource_manager/project.rb', line 44

def service
  @service
end

Class Method Details

.from_gapi(gapi, service) ⇒ Object 



468
469
470
471
472
473
 
# File 'lib/gcloud/resource_manager/project.rb', line 468

def self.from_gapi gapi, service
  new.tap do |p|
    p.gapi = gapi
    p.service = service
  end
end

Instance Method Details

#active? ⇒ Boolean

Checks if the state is ‘ACTIVE`.

Returns:

  • (Boolean) 


200
201
202
203
 
# File 'lib/gcloud/resource_manager/project.rb', line 200

def active?
  return false if state.nil?
  "ACTIVE".casecmp(state).zero?
end

#created_at ⇒ Object

The time that this project was created.



175
176
177
178
179
 
# File 'lib/gcloud/resource_manager/project.rb', line 175

def created_at
  Time.parse @gapi.create_time
rescue
  nil
end

#delete ⇒ Object

Marks the project for deletion. This method will only affect the project if the following criteria are met:

  • The project does not have a billing account associated with it.

  • The project has a lifecycle state of ‘ACTIVE`.

  • This method changes the project’s lifecycle state from ‘ACTIVE` to `DELETE_REQUESTED`. The deletion starts at an unspecified time, at which point the lifecycle state changes to `DELETE_IN_PROGRESS`.

Until the deletion completes, you can check the lifecycle state by calling #reload!, or by retrieving the project with Manager#project. The project remains visible to Manager#project and Manager#projects, but cannot be updated.

After the deletion completes, the project is not retrievable by the Manager#project and Manager#projects methods.

The caller must have modify permissions for this project.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.active? #=> true
project.delete
project.active? #=> false
project.delete_requested? #=> true



301
302
303
304
305
 
# File 'lib/gcloud/resource_manager/project.rb', line 301

def delete
  service.delete_project project_id
  reload!
  true
end

#delete_in_progress? ⇒ Boolean

Checks if the state is ‘DELETE_IN_PROGRESS`.

Returns:

  • (Boolean) 


221
222
223
224
 
# File 'lib/gcloud/resource_manager/project.rb', line 221

def delete_in_progress?
  return false if state.nil?
  "DELETE_IN_PROGRESS".casecmp(state).zero?
end

#delete_requested? ⇒ Boolean

Checks if the state is ‘DELETE_REQUESTED`.

Returns:

  • (Boolean) 


214
215
216
217
 
# File 'lib/gcloud/resource_manager/project.rb', line 214

def delete_requested?
  return false if state.nil?
  "DELETE_REQUESTED".casecmp(state).zero?
end

#labels {|labels| ... } ⇒ Object

The labels associated with this project.

Label keys must be between 1 and 63 characters long and must conform to the regular expression [a-z]([-a-z0-9]*[a-z0-9])?.

Label values must be between 0 and 63 characters long and must conform to the regular expression ([a-z]([-a-z0-9]*[a-z0-9])?)?.

No more than 256 labels can be associated with a given resource. (‘Hash`)

Examples:

Labels are read-only and cannot be changed:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.labels["env"] #=> "dev" # read only
project.labels["env"] = "production" # raises error

Labels can be updated by passing a block, or with #labels=:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.labels do |labels|
  labels["env"] = "production"
end

Yields:

  • (labels) —

    a block for setting labels

Yield Parameters:

  • labels (Hash) —

    the hash accepting labels



135
136
137
138
139
140
141
142
143
144
 
# File 'lib/gcloud/resource_manager/project.rb', line 135

def labels
  labels = @gapi.labels.to_h
  if block_given?
    yielded_labels = labels.dup
    yield yielded_labels
    self.labels = yielded_labels if yielded_labels != labels # changed
  else
    labels.freeze
  end
end

#labels=(new_labels) ⇒ Object

Updates the labels associated with this project.

Label keys must be between 1 and 63 characters long and must conform to the regular expression [a-z]([-a-z0-9]*[a-z0-9])?.

Label values must be between 0 and 63 characters long and must conform to the regular expression ([a-z]([-a-z0-9]*[a-z0-9])?)?.

No more than 256 labels can be associated with a given resource. (‘Hash`)

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.labels = { "env" => "production" }



166
167
168
169
170
 
# File 'lib/gcloud/resource_manager/project.rb', line 166

def labels= new_labels
  ensure_service!
  @gapi.labels = new_labels
  @gapi = service.update_project @gapi
end

#name ⇒ Object

The user-assigned name of the project.



76
77
78
 
# File 'lib/gcloud/resource_manager/project.rb', line 76

def name
  @gapi.name
end

#name=(new_name) ⇒ Object

Updates the user-assigned name of the project. This field is optional and can remain unset.

Allowed characters are: lowercase and uppercase letters, numbers, hyphen, single-quote, double-quote, space, and exclamation point.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.name = "My Project"



95
96
97
98
99
 
# File 'lib/gcloud/resource_manager/project.rb', line 95

def name= new_name
  ensure_service!
  @gapi.name = new_name
  @gapi = service.update_project @gapi
end

#policy(force: false) {|policy| ... } ⇒ Policy

Gets and updates the [Cloud IAM](cloud.google.com/iam/) access control policy for this project.

Examples:

Policy values are memoized to reduce the number of API calls:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"

policy = project.policy # API call
policy_2 = project.policy # No API call

Use ‘force` to retrieve the latest policy from the service:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"

policy = project.policy force: true # API call
policy_2 = project.policy force: true # API call

Update the policy by passing a block:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"

policy = project.policy do |p|
  p.add "roles/owner", "user:[email protected]"
end # 2 API calls

Parameters:

  • force (Boolean) (defaults to: false) —

    Force load the latest policy when ‘true`. Otherwise the policy will be memoized to reduce the number of API calls made. The default is `false`.

Yields:

  • (policy) —

    A block for updating the policy. The latest policy will be read from the service and passed to the block. After the block completes, the modified policy will be written to the service.

Yield Parameters:

  • policy (Policy) —

    the current Cloud IAM Policy for this project

Returns:

  • (Policy) —

    the current Cloud IAM Policy for this project

See Also:



384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/gcloud/resource_manager/project.rb', line 384

def policy force: false
  @policy = nil if force || block_given?
  @policy ||= begin
    ensure_service!
    gapi = service.get_policy project_id
    Policy.from_gapi gapi
  end
  return @policy unless block_given?
  p = @policy.deep_dup
  yield p
  self.policy = p
end

#policy=(new_policy) ⇒ Object

Updates the [Cloud IAM](cloud.google.com/iam/) access control policy for this project. The policy should be read from #policy. See Gcloud::ResourceManager::Policy for an explanation of the policy ‘etag` property and how to modify policies.

You can also update the policy by passing a block to #policy, which will call this method internally after the block completes.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"

policy = project.policy # API call

policy.add "roles/owner", "user:[email protected]"

project.policy = policy # API call

Parameters:

  • new_policy (Policy) —

    a new or modified Cloud IAM Policy for this project

See Also:



427
428
429
430
431
432
433
 
# File 'lib/gcloud/resource_manager/project.rb', line 427

def policy= new_policy
  ensure_service!
  gapi = service.set_policy project_id, new_policy.to_gapi
  # Convert symbols to strings for backwards compatibility.
  # This will go away when we add a ResourceManager::Policy class.
  @policy = Policy.from_gapi gapi
end

#project_id ⇒ Object

The unique, user-assigned ID of the project. It must be 6 to 30 lowercase letters, digits, or hyphens. It must start with a letter. Trailing hyphens are prohibited. e.g. tokyo-rain-123



62
63
64
 
# File 'lib/gcloud/resource_manager/project.rb', line 62

def project_id
  @gapi.project_id
end

#project_number ⇒ Object

The number uniquely identifying the project. e.g. 415104041262



69
70
71
 
# File 'lib/gcloud/resource_manager/project.rb', line 69

def project_number
  @gapi.project_number
end

#reload! ⇒ Object Also known as: refresh!

Reloads the project (with updated state) from the Google Cloud Resource Manager service.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.reload!



265
266
267
 
# File 'lib/gcloud/resource_manager/project.rb', line 265

def reload!
  @gapi = service.get_project project_id
end

#state ⇒ Object

The project lifecycle state.

Possible values are:

  • ‘ACTIVE` - The normal and active state.

  • ‘DELETE_REQUESTED` - The project has been marked for deletion by the user (by invoking ##delete) or by the system (Google Cloud Platform). This can generally be reversed by invoking #undelete.

  • ‘DELETE_IN_PROGRESS` - The process of deleting the project has begun. Reversing the deletion is no longer possible.

  • ‘LIFECYCLE_STATE_UNSPECIFIED` - Unspecified state. This is only used/useful for distinguishing unset values.



194
195
196
 
# File 'lib/gcloud/resource_manager/project.rb', line 194

def state
  @gapi.lifecycle_state
end

#test_permissions(*permissions) ⇒ Array<String>

Tests the specified permissions against the [Cloud IAM](cloud.google.com/iam/) access control policy.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
perms = project.test_permissions "resourcemanager.projects.get",
                                 "resourcemanager.projects.delete"
perms.include? "resourcemanager.projects.get"    #=> true
perms.include? "resourcemanager.projects.delete" #=> false

Parameters:

  • permissions (String, Array<String>) —

    The set of permissions to check access for. Permissions with wildcards (such as ‘*` or `storage.*`) are not allowed.

Returns:

  • (Array<String>) —

    The permissions that have access

See Also:



459
460
461
462
463
464
 
# File 'lib/gcloud/resource_manager/project.rb', line 459

def test_permissions *permissions
  permissions = Array(permissions).flatten
  ensure_service!
  gapi = service.test_permissions project_id, permissions
  gapi.permissions
end

#undelete ⇒ Object

Restores the project. You can only use this method for a project that has a lifecycle state of ‘DELETE_REQUESTED`. After deletion starts, as indicated by a lifecycle state of `DELETE_IN_PROGRESS`, the project cannot be restored.

The caller must have modify permissions for this project.

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.delete_requested? #=> true
project.undelete
project.delete_requested? #=> false
project.active? #=> true



326
327
328
329
330
 
# File 'lib/gcloud/resource_manager/project.rb', line 326

def undelete
  service.undelete_project project_id
  reload!
  true
end

#unspecified? ⇒ Boolean

Checks if the state is ‘LIFECYCLE_STATE_UNSPECIFIED`.

Returns:

  • (Boolean) 


207
208
209
210
 
# File 'lib/gcloud/resource_manager/project.rb', line 207

def unspecified?
  return false if state.nil?
  "LIFECYCLE_STATE_UNSPECIFIED".casecmp(state).zero?
end

#update {|project| ... } ⇒ Object

Updates the project in a single API call. See Updater

Examples:

require "gcloud"

gcloud = Gcloud.new
resource_manager = gcloud.resource_manager
project = resource_manager.project "tokyo-rain-123"
project.update do |p|
  p.name = "My Project"
  p.labels["env"] = "production"
end

Yields:

  • (project) —

    a block yielding a project delegate

Yield Parameters:



244
245
246
247
248
249
250
251
 
# File 'lib/gcloud/resource_manager/project.rb', line 244

def update
  updater = Updater.from_project self
  yield updater
  if updater.gapi.to_h != @gapi.to_h # changed
    @gapi = service.update_project updater.gapi
  end
  self
end