google-cloud-bigtable 2.4.1 → 2.6.2

data/lib/google/cloud/bigtable/backup/job.rb

@@ -34,12 +34,12 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   instance = bigtable.instance("my-instance")
-        #   cluster = instance.cluster("my-cluster")
-        #   table = instance.table("my-table")
+        #   instance = bigtable.instance "my-instance"
+        #   cluster = instance.cluster "my-cluster"
+        #   table = instance.table "my-table"
         #
         #   expire_time = Time.now + 60 * 60 * 7
-        #   job = cluster.create_backup(table, "my-backup", expire_time)
+        #   job = cluster.create_backup table, "my-backup", expire_time
         #
         #   job.wait_until_done!
         #   job.done? #=> true
@@ -61,12 +61,12 @@ module Google
           #   require "google/cloud/bigtable"
           #
           #   bigtable = Google::Cloud::Bigtable.new
-          #   instance = bigtable.instance("my-instance")
-          #   cluster = instance.cluster("my-cluster")
-          #   table = instance.table("my-table")
+          #   instance = bigtable.instance "my-instance"
+          #   cluster = instance.cluster "my-cluster"
+          #   table = instance.table "my-table"
           #
           #   expire_time = Time.now + 60 * 60 * 7
-          #   job = cluster.create_backup(table, "my-backup", expire_time)
+          #   job = cluster.create_backup table, "my-backup", expire_time
           #
           #   job.wait_until_done!
           #   job.done? #=> true

data/lib/google/cloud/bigtable/backup/list.rb

@@ -46,8 +46,8 @@ module Google
           #
           #   bigtable = Google::Cloud::Bigtable.new
           #
-          #   instance = bigtable.instance("my-instance")
-          #   cluster = instance.cluster("my-cluster")
+          #   instance = bigtable.instance "my-instance"
+          #   cluster = instance.cluster "my-cluster"
           #
           #   backups = cluster.backups
           #
@@ -69,8 +69,8 @@ module Google
           #
           #   bigtable = Google::Cloud::Bigtable.new
           #
-          #   instance = bigtable.instance("my-instance")
-          #   cluster = instance.cluster("my-cluster")
+          #   instance = bigtable.instance "my-instance"
+          #   cluster = instance.cluster "my-cluster"
           #
           #   backups = cluster.backups
           #
@@ -105,8 +105,8 @@ module Google
           #
           #   bigtable = Google::Cloud::Bigtable.new
           #
-          #   instance = bigtable.instance("my-instance")
-          #   cluster = instance.cluster("my-cluster")
+          #   instance = bigtable.instance "my-instance"
+          #   cluster = instance.cluster "my-cluster"
           #
           #   cluster.backups.all do |backup|
           #     puts backup.backup_id
@@ -117,12 +117,10 @@ module Google
           #
           #   bigtable = Google::Cloud::Bigtable.new
           #
-          #   instance = bigtable.instance("my-instance")
-          #   cluster = instance.cluster("my-cluster")
+          #   instance = bigtable.instance "my-instance"
+          #   cluster = instance.cluster "my-cluster"
           #
-          #   all_backup_ids = cluster.backups.all.map do |backup|
-          #     backup.backup_id
-          #   end
+          #   all_backup_ids = cluster.backups.all.map(&:backup_id)
           #
           def all &block
             return enum_for :all unless block_given?

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

@@ -33,8 +33,8 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   instance = bigtable.instance("my-instance")
-      #   cluster = instance.cluster("my-cluster")
+      #   instance = bigtable.instance "my-instance"
+      #   cluster = instance.cluster "my-cluster"
       #
       #   # Update
       #   cluster.nodes = 3
@@ -168,8 +168,10 @@ module Google
         ##
         # 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)
+        # Valid values are:
+        #
+        #   * `:SSD` - Flash (SSD) storage should be used.
+        #   * `:HDD` - Magnetic drive (HDD) storage should be used.
         #
         # @return [Symbol]
         #
@@ -197,6 +199,24 @@ module Google
           @grpc.location
         end
 
+        ##
+        # The full name of the Cloud KMS encryption key for the cluster, if it is CMEK-protected, 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.
+        #
+        # @return [String, nil] The full name of the Cloud KMS encryption key, or `nil` if the cluster is not
+        #   CMEK-protected.
+        #
+        def kms_key
+          @grpc.encryption_config&.kms_key_name
+        end
+
         ##
         # Creates a new Cloud Bigtable Backup.
         #
@@ -219,12 +239,12 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   instance = bigtable.instance("my-instance")
-        #   cluster = instance.cluster("my-cluster")
-        #   table = instance.table("my-table")
+        #   instance = bigtable.instance "my-instance"
+        #   cluster = instance.cluster "my-cluster"
+        #   table = instance.table "my-table"
         #
         #   expire_time = Time.now + 60 * 60 * 7
-        #   job = cluster.create_backup(table, "my-backup", expire_time)
+        #   job = cluster.create_backup table, "my-backup", expire_time
         #
         #   job.wait_until_done!
         #   job.done? #=> true
@@ -257,10 +277,10 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   cluster = instance.cluster("my-cluster")
+        #   instance = bigtable.instance "my-instance"
+        #   cluster = instance.cluster "my-cluster"
         #
-        #   backup = cluster.backup("my-backup")
+        #   backup = cluster.backup "my-backup"
         #
         #   if backup
         #     puts backup.backup_id
@@ -283,8 +303,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   cluster = instance.cluster("my-cluster")
+        #   instance = bigtable.instance "my-instance"
+        #   cluster = instance.cluster "my-cluster"
         #
         #   cluster.backups.all do |backup|
         #     puts backup.backup_id
@@ -309,8 +329,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   cluster = instance.cluster("my-cluster")
+        #   instance = bigtable.instance "my-instance"
+        #   cluster = instance.cluster "my-cluster"
         #   cluster.nodes = 3
         #   job = cluster.save
         #
@@ -353,8 +373,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   cluster = instance.cluster("my-cluster")
+        #   instance = bigtable.instance "my-instance"
+        #   cluster = instance.cluster "my-cluster"
         #   cluster.delete
         #
         def delete

data/lib/google/cloud/bigtable/cluster/job.rb

@@ -34,7 +34,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",
@@ -67,7 +67,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",

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

@@ -30,8 +30,8 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   instance = bigtable.instance("my-instance")
-      #   table = instance.table("my-table")
+      #   instance = bigtable.instance "my-instance"
+      #   table = instance.table "my-table"
       #
       #   column_family = table.column_families["cf2"]
       #   puts column_family.gc_rule

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

@@ -41,15 +41,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
@@ -59,15 +59,15 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+      #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
       #
       #   table.column_families do |cfm|
       #     cfm.add "cf4", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
       #     cfm.add "cf5", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
       #
-      #     rule_1 = Google::Cloud::Bigtable::GcRule.max_versions(3)
-      #     rule_2 = Google::Cloud::Bigtable::GcRule.max_age(600)
-      #     rule_union = Google::Cloud::Bigtable::GcRule.union(rule_1, rule_2)
+      #     rule_1 = Google::Cloud::Bigtable::GcRule.max_versions 3
+      #     rule_2 = Google::Cloud::Bigtable::GcRule.max_age 600
+      #     rule_union = Google::Cloud::Bigtable::GcRule.union rule_1, rule_2
       #     cfm.update "cf2", gc_rule: rule_union
       #
       #     cfm.delete "cf3"
@@ -196,7 +196,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #
         #   table.column_families do |column_families|
         #     column_families.add "cf4", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
@@ -237,12 +237,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #
         #   table.column_families do |column_families|
-        #     rule_1 = Google::Cloud::Bigtable::GcRule.max_versions(3)
-        #     rule_2 = Google::Cloud::Bigtable::GcRule.max_age(600)
-        #     rule_union = Google::Cloud::Bigtable::GcRule.union(rule_1, rule_2)
+        #     rule_1 = Google::Cloud::Bigtable::GcRule.max_versions 3
+        #     rule_2 = Google::Cloud::Bigtable::GcRule.max_age 600
+        #     rule_union = Google::Cloud::Bigtable::GcRule.union rule_1, rule_2
         #
         #     column_families.update "cf2", gc_rule: rule_union
         #   end
@@ -270,7 +270,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #
         #   table.column_families do |column_families|
         #     column_families.delete "cf3"

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

@@ -32,7 +32,7 @@ module Google
       #   require "google/cloud/bigtable"
       #
       #   bigtable = Google::Cloud::Bigtable.new
-      #   table = bigtable.table("my-instance", "my-table")
+      #   table = bigtable.table "my-instance", "my-table"
       #
       #   # Range that includes all qualifiers including "user-001" up until "user-010"
       #   table.new_column_range("cf").from("user-001").to("user-010")
@@ -89,7 +89,7 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   table.new_column_range("cf").from("qualifier-1")
         #
@@ -97,7 +97,7 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   table.new_column_range("cf").from("qualifier-1", inclusive: false)
         #
@@ -122,7 +122,7 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   table.new_column_range("cf").to("qualifier-10", inclusive: true)
         #
@@ -130,7 +130,7 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   table.new_column_range("cf").to("qualifier-10")
         #
@@ -154,7 +154,7 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   table.new_column_range("cf").between("qualifier-1", "qualifier-10")
         #
@@ -173,7 +173,7 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   table.new_column_range("cf").of("qualifier-1", "qualifier-10")
         #

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/bigtable/status"
+
+module Google
+  module Cloud
+    module Bigtable
+      ##
+      # # EncryptionInfo
+      #
+      # Encryption information for a given resource.
+      #
+      # See {Backup#encryption_info} and {Table::ClusterState#encryption_infos}.
+      #
+      # @example
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #   instance = bigtable.instance "my-instance"
+      #   cluster = instance.cluster "my-cluster"
+      #
+      #   backup = cluster.backup "my-backup"
+      #
+      #   encryption_info = backup.encryption_info
+      #   encryption_info.encryption_type #=> :GOOGLE_DEFAULT_ENCRYPTION
+      #
+      # @example Retrieve a table with cluster states containing encryption info.
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   table = bigtable.table "my-instance", "my-table", view: :ENCRYPTION_VIEW, perform_lookup: true
+      #
+      #   table.cluster_states.each do |cs|
+      #     puts cs.cluster_name
+      #     puts cs.encryption_infos.first.encryption_type
+      #   end
+      #
+      class EncryptionInfo
+        # @private
+        #
+        # Creates a new EncryptionInfo instance.
+        def initialize grpc
+          @grpc = grpc
+        end
+
+        ##
+        # The type of encryption used to protect the resource. Possible values:
+        #
+        # * `ENCRYPTION_TYPE_UNSPECIFIED` - Encryption type was not specified, though data at rest remains encrypted.
+        # * `GOOGLE_DEFAULT_ENCRYPTION` - The data backing the resource is encrypted at rest with a key that is
+        #   fully managed by Google. No key version or status will be populated. This is the default state.
+        # * `CUSTOMER_MANAGED_ENCRYPTION` - The data backing the resource is encrypted at rest with a key that is
+        #   managed by the customer. The in-use version of the key and its status are populated for CMEK-protected
+        #   tables. CMEK-protected backups are pinned to the key version that was in use at the time the backup was
+        #   taken. This key version is populated but its status is not tracked and is reported as `UNKNOWN`.
+        #
+        # See also {#encryption_status}, {#kms_key_version} and {Instance::ClusterMap#add}.
+        #
+        # @return [Symbol] The encryption type code as an uppercase symbol.
+        #
+        def encryption_type
+          @grpc.encryption_type
+        end
+
+        ##
+        # The status of encrypt/decrypt calls on underlying data for the resource. Regardless of status, the existing
+        # data is always encrypted at rest.
+        #
+        # See also {#encryption_type}, {#kms_key_version} and {Instance::ClusterMap#add}.
+        #
+        # @return [Google::Cloud::Bigtable::Status, nil] The encryption status object, or `nil` if not present.
+        #
+        def encryption_status
+          status_grpc = @grpc.encryption_status
+          Status.from_grpc status_grpc if status_grpc
+        end
+
+        ##
+        # The version of the Cloud KMS key specified in the parent cluster that is in use for the data underlying the
+        # table.
+        #
+        # See also {#encryption_type}, {#encryption_status} and {Instance::ClusterMap#add}.
+        #
+        # @return [String, nil] The Cloud KMS key version, or `nil` if not present.
+        #
+        def kms_key_version
+          @grpc.kms_key_version unless @grpc.kms_key_version.empty?
+        end
+
+        # @private
+        #
+        # Creates a new EncryptionInfo instance from a Google::Cloud::Bigtable::Admin::V2::EncryptionInfo.
+        #
+        # @param grpc [Google::Cloud::Bigtable::Admin::V2::EncryptionInfo]
+        # @return [Google::Cloud::Bigtable::EncryptionInfo]
+        def self.from_grpc grpc
+          new grpc
+        end
+      end
+    end
+  end
+end