google-cloud-bigtable 2.2.1 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c055b86b9d279e27fdb78ec71ddb8babd48661349c0404db696496c84fb3d8e1
-  data.tar.gz: 4c3557a421b16d56680b9c9a39f1d5073a6886efe5198262df0ca02494a000be
+  metadata.gz: 4349eaa8149e90524a1966a96fcdb6e1c1faee050c25487e594ee6aa87318681
+  data.tar.gz: 0f34a5bee198253cf893e5209dd3230276663a494f94d16734de89e366e2c322
 SHA512:
-  metadata.gz: da4f265ebb057cc6e291104edf56cfdf121efc9a75def53dbc9831aba3708049eb68a53c378c147c9f49277afa8cf46822ce01c4e11aa8fcefd907522408862c
-  data.tar.gz: 79be648c3e85fe49e9a285fcdec140e16e015e510b8d5327a802c0e1d36b825d4c4ab2cb52f63c9d5e8b96ef3177c0f91648ea56e5aac5c045ffba90e0a1c101
+  metadata.gz: bf6355506c1a29fe2a2a149a36cce4b1e80c9713f317c76ea707353a7828f1a299cb6fc2daeb7beea537cc7ae792e7ffed9ccacc0dd22fc49eedb03a63ee26a0
+  data.tar.gz: bbded4a5e2d126580c68df77aa1171d6d8c9f222237dc5fc9a8fe8dafbb13e9c110b65800ea67018e902e3250ea23b9a2cf3ba29bf64653052be16b4c782b7b7

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Release History
 
+### 2.6.0 / 2021-05-03
+
+#### Features
+
+* Add support for Backup restore to different Instance
+  * Add instance to Backup#restore
+
+### 2.5.0 / 2021-04-20
+
+#### Features
+
+* Add CMEK support
+  * Add kms_key to ClusterMap#add
+  * Add Cluster#kms_key
+  * Add EncryptionInfo
+  * Add ClusterState#encryption_infos
+  * Add ENCRYPTION_VIEW support to Table
+  * Update docs in Table::ClusterState
+  * Add Backup#encryption_info
+
+### 2.4.1 / 2021-04-01
+
+#### Bug Fixes
+
+* Update internal management of view states in Table
+
+### 2.4.0 / 2021-03-10
+
+#### Features
+
+* Drop support for Ruby 2.4 and add support for Ruby 3.0
+
+#### Documentation
+
+* Add link to Garbage collection docs
+
+### 2.3.0 / 2021-02-04
+
+#### Features
+
+* Add integer support to RowFilter#value and ValueRange
+  * Encode Integer arguments as 64-bit signed big-endian integer data
+
 ### 2.2.1 / 2021-01-13
 
 #### Documentation

data/CONTRIBUTING.md

@@ -24,7 +24,7 @@ be able to accept your pull requests.
 In order to use the google-cloud-bigtable console and run the project's tests,
 there is a small amount of setup:
 
-1. Install Ruby. google-cloud-bigtable requires Ruby 2.4+. You may choose to
+1. Install Ruby. google-cloud-bigtable requires Ruby 2.5+. You may choose to
    manage your Ruby and gem installations with [RVM](https://rvm.io/),
    [rbenv](https://github.com/rbenv/rbenv), or
    [chruby](https://github.com/postmodern/chruby).
@@ -119,15 +119,14 @@ If you alter an example's title, you may encounter breaking tests.
 ### Bigtable Acceptance Tests
 
 The Bigtable acceptance tests interact with the live service API. Follow the
-instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
 the Bigtable API. Occasionally, some API features may not yet be generally
 available, making it difficult for some contributors to successfully run the
 entire acceptance test suite. However, please ensure that you do successfully
 run acceptance tests for any code areas covered by your pull request.
 
 To run the acceptance tests, first create and configure a project in the Google
-Developers Console, as described in the {file:AUTHENTICATION.md Authentication
-guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
+Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
 the KEYFILE location on your system.
 
 Before you can run the Bigtable acceptance tests, you must first create indexes

data/LOGGING.md

@@ -3,7 +3,7 @@
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
 that you set may be a Ruby stdlib
-[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
 shown below, or a
 [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
 that will write logs to [Stackdriver

data/OVERVIEW.md

@@ -396,5 +396,5 @@ instance.delete
 ## Additional information
 
 Google Bigtable can be configured to use an emulator or to enable gRPC's
-logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
+logging. To learn more, see the {file:EMULATOR.md Emulator guide}} and
 {file:LOGGING.md Logging guide}.

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

@@ -122,12 +122,12 @@ module Google
           #     app_profile.name
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless next?
               grpc.next_page
               results = self.class.from_grpc grpc, service

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

@@ -18,10 +18,10 @@
 require "google/cloud/bigtable/backup/job"
 require "google/cloud/bigtable/backup/list"
 require "google/cloud/bigtable/convert"
+require "google/cloud/bigtable/encryption_info"
 require "google/cloud/bigtable/policy"
 require "google/cloud/bigtable/table/restore_job"
 
-
 module Google
   module Cloud
     module Bigtable
@@ -207,6 +207,27 @@ module Google
           state == :READY
         end
 
+        ##
+        # The encryption information for the backup. See also {Instance::ClusterMap#add}.
+        #
+        # @return [Google::Cloud::Bigtable::EncryptionInfo] The encryption information for the backup.
+        #
+        # @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
+        #
+        def encryption_info
+          EncryptionInfo.from_grpc @grpc.encryption_info
+        end
+
         ##
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for the backup.
@@ -328,9 +349,12 @@ module Google
         end
 
         ##
-        # Creates a new table by restoring from a completed backup.
+        # Creates a new table by restoring data from a completed backup. The new table may be created in an instance
+        # different than that of the backup.
         #
         # @param table_id [String] The table ID for the new table. This table must not yet exist. Required.
+        # @param instance [Instance, String] The instance or the ID of the instance for the new table, if different from
+        #   the instance of the backup. Optional.
         #
         # @return [Google::Cloud::Bigtable::Table::RestoreJob] The job representing the long-running, asynchronous
         #   processing of a backup restore table operation.
@@ -356,8 +380,35 @@ module Google
         #     optimized = job.optimize_table_operation_name
         #   end
         #
-        def restore table_id
-          grpc = service.restore_table table_id, instance_id, cluster_id, backup_id
+        # @example Create the table in a different instance.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   instance = bigtable.instance("my-instance")
+        #   cluster = instance.cluster("my-cluster")
+        #
+        #   backup = cluster.backup("my-backup")
+        #
+        #   table_instance = bigtable.instance("my-other-instance")
+        #   job = backup.restore("my-new-table", instance: table_instance)
+        #
+        #   job.wait_until_done!
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     table = job.table
+        #     optimized = job.optimize_table_operation_name
+        #   end
+        #
+        def restore table_id, instance: nil
+          table_instance_id = instance.respond_to?(:instance_id) ? instance.instance_id : instance
+          grpc = service.restore_table table_id,
+                                       instance_id,
+                                       cluster_id,
+                                       backup_id,
+                                       table_instance_id: table_instance_id
           Table::RestoreJob.from_grpc grpc, service
         end
 

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

@@ -124,12 +124,12 @@ module Google
           #     backup.backup_id
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless next?
               grpc.next_page
               results = self.class.from_grpc grpc, service

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

@@ -57,11 +57,12 @@ module Google
 
           raise_if chunk.value_size.positive?, "Commit rows cannot have a non-zero value_size." if chunk.commit_row
 
-          if state == NEW_ROW
+          case state
+          when NEW_ROW
             process_new_row
-          elsif state == CELL_IN_PROGRESS
+          when CELL_IN_PROGRESS
             process_cell_in_progress
-          elsif state == ROW_IN_PROGRESS
+          when ROW_IN_PROGRESS
             process_row_in_progress
           end
         end

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

@@ -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.
         #

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

@@ -129,12 +129,12 @@ module Google
           #     puts cluster.cluster_id
           #   end
           #
-          def all
+          def all &block
             return enum_for :all unless block_given?
 
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               break unless results.next?
               results = results.next
             end

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

@@ -45,7 +45,11 @@ module Google
         ##
         # The garbage collection rule to be used for the column family.
         # Optional. The service default value will be used when not specified.
+        #
+        # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+        #
         # @return [Google::Cloud::Bigtable::GcRule, nil]
+        #
         attr_accessor :gc_rule
 
         # @private

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

@@ -222,6 +222,8 @@ module Google
         ##
         # Updates an existing column family in the table.
         #
+        # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+        #
         # @param name [String] Column family name.
         # @param gc_rule [Google::Cloud::Bigtable::GcRule] The new garbage
         #   collection rule to be used for the column family. Optional. The

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

@@ -77,6 +77,18 @@ module Google
 
           Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
         end
+
+        ##
+        # Converts an Integer to 64-bit signed big-endian integer data.
+        # Returns a string argument unchanged.
+        #
+        # @param value [String, Integer]
+        # @return [String]
+        #
+        def integer_to_signed_be_64 value
+          return [value].pack "q>" if value.is_a? Integer
+          value
+        end
       end
     end
   end

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