google-cloud-bigtable 2.4.1 → 2.6.2

data/lib/google/cloud/bigtable/gc_rule.rb

@@ -49,15 +49,15 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
-      #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
-      #     cfm.add("cf2", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+      #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
+      #     cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
+      #     cfm.add "cf2", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
       #
       #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
       #       Google::Cloud::Bigtable::GcRule.max_age(1800),
       #       Google::Cloud::Bigtable::GcRule.max_versions(3)
       #     )
-      #     cfm.add("cf3", gc_rule: gc_rule)
+      #     cfm.add "cf3", gc_rule: gc_rule
       #   end
       #
       #   puts table.column_families["cf1"].gc_rule.max_versions
@@ -95,8 +95,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
-        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
+        #     cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
         #   end
         #
         #   puts table.column_families["cf1"].gc_rule.max_versions
@@ -131,8 +131,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
-        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
+        #     cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
         #   end
         #
         #   puts table.column_families["cf1"].gc_rule.max_age
@@ -162,12 +162,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
         #     gc_rule = Google::Cloud::Bigtable::GcRule.intersection(
         #       Google::Cloud::Bigtable::GcRule.max_age(1800),
         #       Google::Cloud::Bigtable::GcRule.max_versions(3)
         #     )
-        #     cfm.add("cf1", gc_rule: gc_rule)
+        #     cfm.add "cf1", gc_rule: gc_rule
         #   end
         #
         #   puts table.column_families["cf1"].gc_rule.intersection
@@ -203,12 +203,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
         #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
         #       Google::Cloud::Bigtable::GcRule.max_age(1800),
         #       Google::Cloud::Bigtable::GcRule.max_versions(3)
         #     )
-        #     cfm.add("cf1", gc_rule: gc_rule)
+        #     cfm.add "cf1", gc_rule: gc_rule
         #   end
         #
         #   puts table.column_families["cf1"].gc_rule.union
@@ -231,8 +231,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
-        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
+        #     cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
         #   end
         #
         def self.max_versions versions
@@ -252,8 +252,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
-        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
+        #     cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
         #   end
         #
         def self.max_age age
@@ -274,12 +274,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
         #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
         #       Google::Cloud::Bigtable::GcRule.max_age(1800),
         #       Google::Cloud::Bigtable::GcRule.max_versions(3)
         #     )
-        #     cfm.add("cf1", gc_rule: gc_rule)
+        #     cfm.add "cf1", gc_rule: gc_rule
         #   end
         #
         def self.union *rules
@@ -300,12 +300,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #   table = bigtable.create_table "my-instance", "my-table" do |cfm|
         #     gc_rule = Google::Cloud::Bigtable::GcRule.intersection(
         #       Google::Cloud::Bigtable::GcRule.max_age(1800),
         #       Google::Cloud::Bigtable::GcRule.max_versions(3)
         #     )
-        #     cfm.add("cf1", gc_rule: gc_rule)
+        #     cfm.add "cf1", gc_rule: gc_rule
         #   end
         #
         def self.intersection *rules

data/lib/google/cloud/bigtable/instance.rb

@@ -44,9 +44,9 @@ module Google
       #     "my-instance",
       #     display_name: "Instance for user data",
       #     type: :DEVELOPMENT,
-      #     labels: { "env" => "dev"}
+      #     labels: { "env" => "dev" }
       #   ) do |clusters|
-      #     clusters.add("test-cluster", "us-east1-b") # nodes not allowed
+      #     clusters.add "test-cluster", "us-east1-b" # nodes not allowed
       #   end
       #
       #   job.done? #=> false
@@ -203,7 +203,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   instance.development? # true
         #   instance.type = :PRODUCTION
@@ -267,7 +267,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #   instance.display_name = "My app dev instance"  # Set display name
         #   instance.labels = { env: "dev", data: "users" }
         #   job = instance.save
@@ -314,7 +314,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #   instance.delete
         #
         def delete
@@ -340,7 +340,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   instance.clusters.all do |cluster|
         #     puts cluster.cluster_id
@@ -366,9 +366,9 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
-        #   cluster = instance.cluster("my-instance-cluster")
+        #   cluster = instance.cluster "my-cluster"
         #   puts cluster.cluster_id
         #
         def cluster cluster_id
@@ -403,7 +403,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #   job = instance.create_cluster(
         #     "my-new-cluster",
         #     "us-east-1b",
@@ -450,7 +450,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   # Default name-only view
         #   instance.tables.all do |table|
@@ -490,14 +490,14 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
-        #   table = instance.table("my-table", perform_lookup: true)
+        #   table = instance.table "my-table", perform_lookup: true
         #   puts table.name
         #   puts table.column_families
         #
         #   # Name-only view
-        #   table = instance.table("my-table", view: :NAME_ONLY, perform_lookup: true)
+        #   table = instance.table "my-table", view: :NAME_ONLY, perform_lookup: true
         #   puts table.name
         #
         # @example  Mutate rows.
@@ -505,17 +505,17 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   entry = table.new_mutation_entry("user-1")
+        #   entry = table.new_mutation_entry "user-1"
         #   entry.set_cell(
         #     "cf1",
         #     "field1",
         #     "XYZ",
-        #     timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
-        #   ).delete_cells("cf2", "field02")
+        #     timestamp: (Time.now.to_f * 1_000_000).round(-3) # microseconds
+        #   ).delete_cells "cf2", "field02"
         #
-        #   table.mutate_row(entry)
+        #   table.mutate_row entry
         #
         def table table_id, view: nil, perform_lookup: nil, app_profile_id: nil
           ensure_service!
@@ -581,9 +581,9 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
-        #   table = instance.create_table("my-table")
+        #   table = instance.create_table "my-table"
         #   puts table.name
         #
         # @example Create a table with initial splits and column families.
@@ -591,18 +591,18 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   initial_splits = ["user-00001", "user-100000", "others"]
-        #   table = instance.create_table("my-table", initial_splits: initial_splits) do |cfm|
-        #     cfm.add('cf1', gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
-        #     cfm.add('cf2', gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   table = instance.create_table "my-table", initial_splits: initial_splits do |cfm|
+        #     cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
+        #     cfm.add "cf2", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
         #
         #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
-        #        Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
         #       Google::Cloud::Bigtable::GcRule.max_versions(3)
         #     )
-        #     cfm.add('cf3', gc_rule: gc_rule)
+        #     cfm.add "cf3", gc_rule: gc_rule
         #   end
         #
         #   puts table
@@ -660,10 +660,10 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
-        #     "my-instance-cluster-1",
+        #     "my-cluster",
         #     allow_transactional_writes: true
         #   )
         #
@@ -679,7 +679,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
         #
@@ -695,7 +695,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
         #
@@ -746,9 +746,9 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
-        #   app_profile = instance.app_profile("my-app-profile")
+        #   app_profile = instance.app_profile "my-app-profile"
         #
         #   if app_profile
         #     puts app_profile.name
@@ -776,7 +776,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   instance.app_profiles.all do |app_profile|
         #     puts app_profile.name
@@ -808,17 +808,17 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #   policy = instance.policy
         #
         # @example Update the policy by passing a block.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   instance.policy do |p|
-        #     p.add("roles/owner", "user:owner@example.com")
+        #     p.add "roles/owner", "user:owner@example.com"
         #   end # 2 API calls
         #
         def policy
@@ -849,11 +849,11 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   policy = instance.policy
-        #   policy.add("roles/owner", "user:owner@example.com")
-        #   updated_policy = instance.update_policy(policy)
+        #   policy.add "roles/owner", "user:owner@example.com"
+        #   updated_policy = instance.update_policy policy
         #
         #   puts updated_policy.roles
         #
@@ -892,7 +892,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
+        #   instance = bigtable.instance "my-instance"
         #
         #   permissions = instance.test_iam_permissions(
         #     "bigtable.instances.get",

data/lib/google/cloud/bigtable/instance/cluster_map.rb

@@ -15,28 +15,31 @@
 # limitations under the License.
 
 
+require "google/cloud/bigtable/admin/v2"
+
 module Google
   module Cloud
     module Bigtable
       class Instance
         ##
-        # Instance::ClusterMap is a hash with cluster ID keys and cluster configuration values.
-        # It is used to create a cluster.
+        # Instance::ClusterMap is a hash with cluster ID keys and cluster configuration values. It is used to create a
+        # cluster.
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
-        #  clusters = Google::Cloud::Bigtable::Instance::ClusterMap.new
+        #   bigtable = Google::Cloud::Bigtable.new
         #
-        #  clusters.add("cluster-1", "us-east1-b", nodes: 3, storage_type: :SSD)
+        #   job = bigtable.create_instance "my-instance" do |clusters|
+        #     clusters.add "test-cluster", "us-east1-b", nodes: 3, storage_type: :SSD
+        #   end
         #
-        #  # Or
-        #  clusters.add("cluster-2", "us-east1-b")
+        #   job.wait_until_done!
         #
         class ClusterMap < DelegateClass(::Hash)
           # @private
           #
-          # Creates a new Instance::ClusterMap with an hash of Cluster name and
-          # cluster grpc instances.
+          # Creates a new Instance::ClusterMap with an hash of Cluster name and cluster grpc instances.
           def initialize value = {}
             super value
           end
@@ -45,24 +48,61 @@ module Google
           # Adds a cluster to the cluster map.
           #
           # @param name [String] The unique identifier for the cluster.
-          # @param 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.
-          # @param nodes [Integer] Number of nodes for the cluster. When creating
-          #   an instance of type `:DEVELOPMENT`, `nodes` must not be set.
-          # @param storage_type [Symbol]
-          #   Valid values are:
-          #   * `:SSD`(Flash (SSD) storage should be used),
-          #   *`:HDD`(Magnetic drive (HDD) storage should be used)
+          # @param 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.
+          # @param nodes [Integer] Number of nodes for the cluster. When creating an instance of type `:DEVELOPMENT`,
+          #   `nodes` must not be set.
+          # @param storage_type [Symbol] The type of storage used by this cluster to serve its parent instance's tables,
+          #   unless explicitly overridden. Valid values are:
+          #
+          #   * `:SSD` - Flash (SSD) storage should be used.
+          #   * `:HDD` - Magnetic drive (HDD) storage should be used.
+          #
+          #   If not set then default will set to `:STORAGE_TYPE_UNSPECIFIED`.
+          # @param kms_key [String] The full name of a Cloud KMS encryption key for a CMEK-protected cluster, in the
+          #   format `projects/{key_project_id}/locations/{location}/keyRings/{ring_name}/cryptoKeys/{key_name}`.
+          #
+          #   The requirements for this key are:
+          #
+          #   1. The Cloud Bigtable service account associated with the project that contains this cluster must be
+          #      granted the `cloudkms.cryptoKeyEncrypterDecrypter` role on the CMEK key.
+          #   2. Only regional keys can be used and the region of the CMEK key must match the region of the cluster.
+          #   3. All clusters within an instance must use the same CMEK key.
+          #
+          # @example
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   job = bigtable.create_instance "my-instance" do |clusters|
+          #     clusters.add "test-cluster", "us-east1-b", nodes: 3, storage_type: :SSD
+          #   end
+          #
+          #   job.wait_until_done!
+          #
+          # @example With a Cloud KMS encryption key name for a CMEK-protected cluster:
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #
+          #   kms_key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
+          #   job = bigtable.create_instance "my-instance" do |clusters|
+          #     clusters.add "test-cluster", "us-east1-b", kms_key: kms_key_name
+          #   end
           #
-          #   If not set then default will set to `:STORAGE_TYPE_UNSPECIFIED`
+          #   job.wait_until_done!
           #
-          def add name, location, nodes: nil, storage_type: nil
+          def add name, location, nodes: nil, storage_type: nil, kms_key: nil
+            if kms_key
+              encryption_config = Google::Cloud::Bigtable::Admin::V2::Cluster::EncryptionConfig.new(
+                kms_key_name: kms_key
+              )
+            end
             attrs = {
               serve_nodes:          nodes,
               location:             location,
-              default_storage_type: storage_type
+              default_storage_type: storage_type,
+              encryption_config:    encryption_config
             }.delete_if { |_, v| v.nil? }
 
             self[name] = Google::Cloud::Bigtable::Admin::V2::Cluster.new attrs