Class: Google::Cloud::Bigtable::Instance

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/bigtable/instance.rb,
lib/google/cloud/bigtable/instance/job.rb,
lib/google/cloud/bigtable/instance/list.rb,
lib/google/cloud/bigtable/instance/cluster_map.rb

Overview

Instance

Represents a Bigtable instance. Instances are dedicated Bigtable serving and storage resources to be used by Bigtable tables.

See Project#instances, Project#instance, and Project#create_instance.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

job = bigtable.create_instance(
  "my-instance",
  "Instance for user data",
  type: :DEVELOPMENT,
  labels: { "env" => "dev"}
) do |clusters|
  clusters.add("test-cluster", "us-east1-b", nodes: 1)
end

job.done? #=> false

# To block until the operation completes.
job.wait_until_done!
job.done? #=> true

if job.error?
  status = job.error
else
  instance = job.instance
end

Defined Under Namespace

Classes: ClusterMap, Job, List

Instance Method Summary collapse

Instance Method Details

#app_profile(app_profile_id) ⇒ Google::Cloud::Bigtable::AppProfile?

Get app profile.

See to delete app_profile AppProfile#delete and update app_profile AppProfile#save.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

app_profile = instance.app_profile("my-app-profile")

if app_profile
  puts app_profile.name
end

Parameters:

  • app_profile_id (String) —

    The unique name of the requested app profile.

Returns:



743
744
745
746
747
748
749
 
# File 'lib/google/cloud/bigtable/instance.rb', line 743

def app_profile app_profile_id
  ensure_service!
  grpc = service.get_app_profile(instance_id, app_profile_id)
  AppProfile.from_grpc(grpc, service)
rescue Google::Cloud::NotFoundError
  nil
end

#app_profiles ⇒ Array<Google::Cloud::Bigtable::AppProfile>

List all app profiles

See to delete app_profile AppProfile#delete and update app_profile AppProfile#save.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

instance.app_profiles.all do |app_profile|
  puts app_profile.name
end

Returns:



770
771
772
773
774
 
# File 'lib/google/cloud/bigtable/instance.rb', line 770

def app_profiles
  ensure_service!
  grpc = service.list_app_profiles(instance_id)
  AppProfile::List.from_grpc(grpc, service)
end

#cluster(cluster_id) ⇒ Google::Cloud::Bigtable::Cluster?

Gets cluster information.

See to delete Cluster#delete and update cluster Cluster#save.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

cluster = instance.cluster("my-instance-cluster")
puts cluster.cluster_id

Parameters:

  • cluster_id (String) —

    The unique ID of the requested cluster.

Returns:



343
344
345
346
347
348
349
 
# File 'lib/google/cloud/bigtable/instance.rb', line 343

def cluster cluster_id
  ensure_service!
  grpc = service.get_cluster(instance_id, cluster_id)
  Cluster.from_grpc(grpc, service)
rescue Google::Cloud::NotFoundError
  nil
end

#clusters(token: nil) ⇒ Array<Google::Cloud::Bigtable::Cluster>

Lists information about clusters in an instance.

See to delete Cluster#delete and update cluster Cluster#save.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

instance.clusters.all do |cluster|
  puts cluster.cluster_id
end

Parameters:

  • token (String) —

    The token value returned by the last call to clusters; indicates that this is a continuation of a call, and that the system should return the next page of data.

Returns:



319
320
321
322
323
 
# File 'lib/google/cloud/bigtable/instance.rb', line 319

def clusters token: nil
  ensure_service!
  grpc = service.list_clusters(instance_id, token: token)
  Cluster::List.from_grpc(grpc, service, instance_id: instance_id)
end

#create_app_profile(name, routing_policy, description: nil, etag: nil, ignore_warnings: false) ⇒ Google::Cloud::Bigtable::AppProfile

Create app profile of instance with routing policy. Only one routing policy can applied to app profile. It can be multi cluster routing or single cluster routing

Examples:

Create app profile with single cluster routing policy

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
  "my-instance-cluster-1"
  allow_transactional_writes: true
)

app_profile = instance.create_app_profile(
  "my-app-profile",
  routing_policy: routing_policy,
  description: "App profile for user data instance"
)
puts app_profile.name

Create app profile with multi cluster routing policy

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing

app_profile = instance.create_app_profile(
  "my-app-profile",
  routing_policy,
  description: "App profile for user data instance"
)
puts app_profile.name

Create app profile and ignore warnings.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing

app_profile = instance.create_app_profile(
  "my-app-profile",
  routing_policy,
  description: "App profile for user data instance",
  ignore_warnings: true
)
puts app_profile.name

Parameters:

  • name (String) —

    Unique Id of the app profile

  • routing_policy (Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting | Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny) —

    The routing policy for all read/write requests which use this app profile. A value must be explicitly set.

    Routing Policies:

    • multi_cluster_routing - Read/write requests may be routed to any cluster in the instance, and will fail over to another cluster in the event of transient errors or delays. Choosing this option sacrifices read-your-writes consistency to improve availability.
    • single_cluster_routing - Unconditionally routes all read/write requests to a specific cluster. This option preserves read-your-writes consistency, but does not improve availability. Value contain cluster_id and optional field allow_transactional_writes.
  • description (String) —

    Description of the use case for this AppProfile

  • etag (String) —

    Strongly validated etag for optimistic concurrency control. Preserve the value returned from GetAppProfile when calling UpdateAppProfile to fail the request if there has been a modification in the mean time. The update_mask of the request need not include etag for this protection to apply. See Wikipedia and RFC 7232 for more details.

  • ignore_warnings (Boolean) —

    If true, ignore safety checks when creating the app profile. Default value is false

Returns:



691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
 
# File 'lib/google/cloud/bigtable/instance.rb', line 691

def create_app_profile \
    name,
    routing_policy,
    description: nil,
    etag: nil,
    ignore_warnings: false
  ensure_service!

  if routing_policy.is_a?(Google::Bigtable::Admin::V2::AppProfile:: \
      MultiClusterRoutingUseAny)
    multi_cluster_routing = routing_policy
  else
    single_cluster_routing = routing_policy
  end

  app_profile_attrs = {
    multi_cluster_routing_use_any: multi_cluster_routing,
    single_cluster_routing: single_cluster_routing,
    description: description,
    etag: etag
  }.delete_if { |_, v| v.nil? }

  grpc = service.create_app_profile(
    instance_id,
    name,
    Google::Bigtable::Admin::V2::AppProfile.new(app_profile_attrs),
    ignore_warnings: ignore_warnings
  )
  AppProfile.from_grpc(grpc, service)
end

#create_cluster(cluster_id, location, nodes: nil, storage_type: nil) ⇒ Google::Cloud::Bigtable::Cluster::Job

Creates a cluster within an instance.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")
job = instance.create_cluster(
  "my-new-cluster",
  "us-east-1b",
  nodes: 3,
  storage_type: :SSD
)

job.done? #=> false

# To block until the operation completes.
job.wait_until_done!
job.done? #=> true

if job.error?
  status = job.error
else
  cluster = job.cluster
end

Parameters:

  • cluster_id (String) —

    The ID to be used when referring to the new cluster within its instance, e.g., just +mycluster+

  • location (String) —

    The location where this cluster's nodes and storage reside. For best performance, clients should be located as close as possible to this cluster. Currently only zones are supported. i.e "us-east-1b"

  • nodes (Integer) —

    The number of nodes allocated to this cluster. More nodes enable higher throughput and more consistent performance.

  • storage_type (Symbol) —

    Type of storage type. The type of storage used by this cluster to serve its parent instance's tables. Valid types are:

    • :SSD - Flash (SSD) storage.
    • :HDD - Magnetic drive (HDD).

Returns:



396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/google/cloud/bigtable/instance.rb', line 396

def create_cluster cluster_id, location, nodes: nil, storage_type: nil
  ensure_service!
  attrs = {
    serve_nodes: nodes,
    default_storage_type: storage_type,
    location: location
  }.delete_if { |_, v| v.nil? }

  cluster = Google::Bigtable::Admin::V2::Cluster.new(attrs)
  grpc = service.create_cluster(instance_id, cluster_id, cluster)
  Cluster::Job.from_grpc(grpc, service)
end

#create_table(name, column_families: nil, granularity: nil, initial_splits: nil) {|column_families| ... } ⇒ Google::Cloud::Bigtable::Table

Create table

The table can be created with a full set of initial column families, specified in the request.

Examples:

Create table without column families.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

table = instance.create_table("my-table")
puts table.name

Create table with column families and initial splits.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

table = instance.create_table(my-table") do |column_families|
  column_families.add('cf1', Google::Cloud::Bigtable::GcRule.max_versions(3))
  column_families.add('cf2', Google::Cloud::Bigtable::GcRule.max_age(100))

  gc_rule = Google::Cloud::Bigtable::GcRule.new
  gc_rule.union = [
    Google::Cloud::Bigtable::GcRule.max_versions(3),
     Google::Cloud::Bigtable::GcRule.max_age(1800),
  ]
  column_families.add('cf3', gc_rule)
end

puts table

Parameters:

  • name (String) —

    The name by which the new table should be referred to within the parent instance, e.g., +foobar+

  • column_families (Hash{String => Google::Cloud::Bigtable::ColumnFamily}) —

    (See Table::ColumnFamilyMap) If passed as an empty use code block to add column families.

  • granularity (Symbol) —

    The granularity at which timestamps are stored in this table. Timestamps not matching the granularity will be rejected. Valid values are :MILLIS. If unspecified, the value will be set to :MILLIS

  • initial_splits (Array<String>) —

    The optional list of row keys that will be used to initially split the table into several tablets (tablets are similar to HBase regions). Given two split keys, +s1+ and +s2+, three tablets will be created, spanning the key ranges: +[, s1), [s1, s2), [s2, )+.

    Example:

    • Row keys := +["a", "apple", "custom", "customer_1", "customer_2",+ +"other", "zz"]+
    • initial_split_keys := +["apple", "customer_1", "customer_2", "other"]+
    • Key assignment:
      • Tablet 1 : +[, apple) => "a".+
      • Tablet 2 : +[apple, customer_1) => "custom".+
      • Tablet 3 : +[customer_1, customer_2) => "customer_1".+
      • Tablet 4 : +[customer_2, other) => "customer_2".+
      • Tablet 5 : +[other, ) => "zz".+ A hash of the same form as Google::Bigtable::Admin::V2::CreateTableRequest::Split can also be provided.

Yields:

  • (column_families) —

    A block for adding column_families.

Yield Parameters:

Returns:



589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
 
# File 'lib/google/cloud/bigtable/instance.rb', line 589

def create_table \
    name,
    column_families: nil,
    granularity: nil,
    initial_splits: nil,
    &block
  ensure_service!
  Table.create(
    service,
    instance_id,
    name,
    column_families: column_families,
    granularity: granularity,
    initial_splits: initial_splits,
    &block
  )
end

#creating? ⇒ Boolean

The instance is currently being created, and may be destroyed if the creation process encounters an error.

Returns:

  • (Boolean) 


142
143
144
 
# File 'lib/google/cloud/bigtable/instance.rb', line 142

def creating?
  state == :CREATING
end

#delete ⇒ Boolean

Permanently deletes the instance from a project.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")
instance.delete

Returns:

  • (Boolean) —

    Returns true if the instance was deleted.



291
292
293
294
295
 
# File 'lib/google/cloud/bigtable/instance.rb', line 291

def delete
  ensure_service!
  service.delete_instance(instance_id)
  true
end

#development? ⇒ Boolean

The instance is meant for development and testing purposes only; it has no performance or uptime guarantees and is not covered by SLA. After a development instance is created, it can be upgraded by updating the instance to type PRODUCTION. An instance created as a production instance cannot be changed to a development instance. When creating a development instance, serve_nodes on the cluster must not be set.

Returns:

  • (Boolean) 


165
166
167
 
# File 'lib/google/cloud/bigtable/instance.rb', line 165

def development?
  type == :DEVELOPMENT
end

#display_name ⇒ String

The descriptive name for this instance as it appears in UIs. Must be unique per project and between 4 and 30 characters in length.

Returns:

  • (String) 


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

def display_name
  @grpc.display_name
end

#display_name=(value) ⇒ Object

Updates the descriptive name for this instance as it appears in UIs. Can be changed at any time, but should be kept globally unique to avoid confusion.

Parameters:

  • value (String) —

    The descriptive name for this instance.



106
107
108
 
# File 'lib/google/cloud/bigtable/instance.rb', line 106

def display_name= value
  @grpc.display_name = value
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


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

def instance_id
  @grpc.name.split("/")[3]
end

#labels ⇒ Hash{String=>String}

Get instance labels.

Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources into groups that reflect a customer's organizational needs and deployment strategies. Cloud Labels can be used to filter collections of resources. They can be used to control how resource metrics are aggregated. And they can be used as arguments to policy management rules (e.g. route, firewall, load balancing, etc.).

  • Label keys must be between 1 and 63 characters long and must conform to the following 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 64 labels can be associated with a given resource.

Returns:

  • (Hash{String=>String}) —

    The label keys and values in a hash.



209
210
211
 
# File 'lib/google/cloud/bigtable/instance.rb', line 209

def labels
  @grpc.labels
end

#labels=(labels) ⇒ Object

Set the Cloud Labels.

Parameters:

  • labels (Hash{String=>String}) —

    The Cloud Labels.



217
218
219
220
221
222
223
 
# File 'lib/google/cloud/bigtable/instance.rb', line 217

def labels= labels
  labels ||= {}
  @grpc.labels = Google::Protobuf::Map.new(
    :string, :string,
    Hash[labels.map { |k, v| [String(k), String(v)] }]
  )
end

#path ⇒ String

The full path for the instance resource. Values are of the form projects/<project_id>/instances/<instance_id>.

Returns:

  • (String) 


115
116
117
 
# File 'lib/google/cloud/bigtable/instance.rb', line 115

def path
  @grpc.name
end

#policy {|policy| ... } ⇒ Policy

Gets the Cloud IAM access control policy for this instance.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")
policy = instance.policy

Update the policy by passing a block:

require "google/cloud/spanner"

bigtable = Google::Cloud::Bigtable.new
instance = bigtable.instance("my-instance")

instance.policy do |p|
  p.add("roles/owner", "user:owner@example.com")
end # 2 API calls

Yields:

  • (policy) —

    A block for updating the policy. The latest policy will be read from the Bigtable 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 instance

Returns:

  • (Policy) —

    The current Cloud IAM Policy for this instance.

See Also:



808
809
810
811
812
813
814
815
 
# File 'lib/google/cloud/bigtable/instance.rb', line 808

def policy
  ensure_service!
  grpc = service.get_instance_policy(instance_id)
  policy = Policy.from_grpc(grpc)
  return policy unless block_given?
  yield policy
  update_policy policy
end

#production? ⇒ Boolean

An instance meant for production use. serve_nodes must be set on the cluster.

Returns:

  • (Boolean) 


174
175
176
 
# File 'lib/google/cloud/bigtable/instance.rb', line 174

def production?
  type == :PRODUCTION
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


79
80
81
 
# File 'lib/google/cloud/bigtable/instance.rb', line 79

def project_id
  @grpc.name.split("/")[1]
end

#ready? ⇒ Boolean

The instance has been successfully created and can serve requests to its tables

Returns:

  • (Boolean) 


133
134
135
 
# File 'lib/google/cloud/bigtable/instance.rb', line 133

def ready?
  state == :READY
end

#reload! ⇒ Google::Cloud::Bigtable::Instance

Reload instance information.

Returns:



274
275
276
277
 
# File 'lib/google/cloud/bigtable/instance.rb', line 274

def reload!
  @grpc = service.get_instance(instance_id)
  self
end

#save ⇒ Google::Cloud::Bigtable::Instance::Job Also known as: update

Update instance.

Updatable attributes are :

  • display_name - The descriptive name for this instance.
  • type - :DEVELOPMENT type instance can be upgraded to :PRODUCTION instance. An instance created as a production instance cannot be changed to a development instance.
  • labels - Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")
instance.display_name = "My app dev instance"  # Set display name
instance.labels = { env: "dev", data: "users" }
job = instance.save

job.done? #=> false

# Reload job until completion.
job.wait_until_done!
job.done? #=> true

if job.error?
  puts job.error
else
  instance = job.instance
  puts instance.name
  puts instance.labels
end

Returns:



260
261
262
263
264
265
266
267
 
# File 'lib/google/cloud/bigtable/instance.rb', line 260

def save
  ensure_service!
  update_mask = Google::Protobuf::FieldMask.new(
    paths: %w[labels display_name type]
  )
  grpc = service.partial_update_instance(@grpc, update_mask)
  Instance::Job.from_grpc(grpc, service)
end

#state ⇒ Symbol

The current instance state. Possible values are :CREATING, :READY, :STATE_NOT_KNOWN.

Returns:

  • (Symbol) 


124
125
126
 
# File 'lib/google/cloud/bigtable/instance.rb', line 124

def state
  @grpc.state
end

#table(table_id, view: nil, perform_lookup: nil, app_profile_id: nil) ⇒ Object 



496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/google/cloud/bigtable/instance.rb', line 496

def table table_id, view: nil, perform_lookup: nil, app_profile_id: nil
  ensure_service!

  table = if perform_lookup
            grpc = service.get_table(instance_id, table_id, view: view)
            Table.from_grpc(grpc, service, view: view)
          else
            Table.from_path(
              service.table_path(instance_id, table_id),
              service
            )
          end

  table.app_profile_id = app_profile_id
  table
rescue Google::Cloud::NotFoundError
  nil
end

#tables ⇒ Array<Google::Cloud::Bigtable::Table>

List all tables.

See to delete table Table#delete and update table Table#save.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

# Default name only view
instance.tables.all do |table|
  puts table.name
end

# Full view
instance.tables(view: :FULL).all do |table|
  puts table.name
  puts table.column_families
end

Returns:



435
436
437
438
439
 
# File 'lib/google/cloud/bigtable/instance.rb', line 435

def tables
  ensure_service!
  grpc = service.list_tables(instance_id)
  Table::List.from_grpc(grpc, service)
end

#test_iam_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the Cloud IAM access control policy.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

permissions = bigtable.test_permissions(
  "bigtable.instances.get",
  "bigtable.instances.update"
)
permissions.include? "bigtable.instances.get" #=> true
permissions.include? "bigtable.instances.update" #=> false

Parameters:

  • permissions (String, Array<String>) —

    permissions The set of permissions to check access for. Permissions with wildcards (such as * or bigtable.*) are not allowed. See (https://cloud.google.com/bigtable/docs/access-control)

    Some of the permissions that can be checked on a instance are:

    • bigtable.instances.create
    • bigtable.instances.list
    • bigtable.instances.get
    • bigtable.tables.create
    • bigtable.tables.delete
    • bigtable.tables.get
    • bigtable.tables.list

Returns:

  • (Array<Strings>) —

    The permissions that have access.

See Also:



886
887
888
889
890
891
892
893
 
# File 'lib/google/cloud/bigtable/instance.rb', line 886

def test_iam_permissions *permissions
  ensure_service!
  grpc = service.test_instance_permissions(
    instance_id,
    Array(permissions).flatten
  )
  grpc.permissions
end

#type ⇒ Symbol

Instance type. Possible values are :DEVELOPMENT, :PRODUCTION, :TYPE_UNSPECIFIED

Returns:

  • (Symbol) 


151
152
153
 
# File 'lib/google/cloud/bigtable/instance.rb', line 151

def type
  @grpc.type
end

#type=(instance_type) ⇒ Object

Set instance type.

Valid values are :DEVELOPMENT, :PRODUCTION. If instance already created then After a development instance is created, it can be upgraded by updating the instance to type PRODUCTION. An instance created as a production instance cannot be changed to a development instance.

Parameters:

  • instance_type (Symbol) 


188
189
190
 
# File 'lib/google/cloud/bigtable/instance.rb', line 188

def type= instance_type
  @grpc.type = instance_type
end

#update_policy(new_policy) ⇒ Policy Also known as: policy=

Updates the Cloud IAM access control policy for this instance. The policy should be read from #policy. See 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 "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance("my-instance")

policy = instance.policy
policy.add("roles/owner", "user:owner@example.com")
updated_policy = instance.update_policy(policy)

puts update_policy.roles

Parameters:

  • new_policy (Policy) —

    a new or modified Cloud IAM Policy for this instance

Returns:

  • (Policy) —

    The policy returned by the API update operation.



843
844
845
846
847
 
# File 'lib/google/cloud/bigtable/instance.rb', line 843

def update_policy new_policy
  ensure_service!
  grpc = service.set_instance_policy(instance_id, new_policy.to_grpc)
  Policy.from_grpc(grpc)
end