google-cloud-bigtable 2.2.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 864b31028834907aa872f0f5aec7a31a682e419c286744c1cc3243072597e739
-  data.tar.gz: 543de2a38416692f95400157b4ca67520b5a6765bed60dd1237b3be405a10d2e
+  metadata.gz: 87e7128a687d06d1e5dc3e74f2b529ab43b3c9ea28717d738c433ea86fb297ad
+  data.tar.gz: a04ca13f900445078568a3a1cf64ef84d57686a494f3a652cc6ec461af41712e
 SHA512:
-  metadata.gz: a62102b9792b017c396477aa79435a29b1c495e2234c8a34c6040c74883c9aaa7f07cf9e945606a139e7f8d032f57663da235a8a6f3e8922eeaad72f5a582b46
-  data.tar.gz: 5d474fd9b72cb0d2474be964d1c0af670266f577af221d6ae76256c34f935ec239040b824e2eadd7e391ad09fde511406f210f0e007796cea69e163d244827f9
+  metadata.gz: dc329bd4e9f0d1ed5c5376c40da2924a41f83681df93803aafcadd9ed846bdd2119b913661054b95cfc70cbbfada891b58563b3146396acd872ae2fa79cbff2b
+  data.tar.gz: af466ef435035adae503c5368b0e7c899e84424151044d49efb51f2920e121854ca8af51708c9fce7181e1116410408c635a040442b8b004df45d76b5184c721

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Release History
 
+### 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
+
+* Use consistent column family and field names in samples
+
 ### 2.2.0 / 2020-11-11
 
 #### Features

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).
@@ -45,7 +45,7 @@ there is a small amount of setup:
 
    ```sh
    $ cd google-cloud-bigtable/
-   $ bundle exec rake bundleupdate
+   $ bundle install
    ```
 
 ## Console
@@ -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

@@ -194,8 +194,8 @@ table = bigtable.table("my-instance", "my-table")
 
 entry = table.new_mutation_entry("user-1")
 entry.set_cell(
-  "cf-1",
-  "field-1",
+  "cf1",
+  "field1",
   "XYZ",
   timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
 ).delete_cells("cf2", "field02")
@@ -245,8 +245,8 @@ table = bigtable.table("my-instance", "my-table")
 predicate_filter = Google::Cloud::Bigtable::RowFilter.key("user-10")
 on_match_mutations = Google::Cloud::Bigtable::MutationEntry.new
 on_match_mutations.set_cell(
-  "cf-1",
-  "field-1",
+  "cf1",
+  "field1",
   "XYZ",
   timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
 ).delete_cells("cf2", "field02")
@@ -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.

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

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

@@ -28,6 +28,8 @@ module Google
       # so it is possible for reads to return a cell even if it matches the
       # active GC expression for its column family.
       #
+      # @see https://cloud.google.com/bigtable/docs/garbage-collection Garbage collection
+      #
       # GC Rule types:
       #   * `max_num_versions` - A garbage-collection rule that explicitly
       #     states the maximum number of cells to keep for all columns in a