google-cloud-spanner 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9768d839e58d7697a3ec4d57f924c6dd251bf59b1bb531ca2fbcf14da1b6120d
-  data.tar.gz: 2fd33ab3bfddeaed840fd815d057e3ddb81bf3a4b746b88f20dcc72ecca46e44
+  metadata.gz: 0faea5b1e581fbc3981a52fa5ea8b2f1674f79fc71bc3000639020739747b5ea
+  data.tar.gz: bd4d345cbf3cefc8dbba31a2d74d4f729e8a5d9e3364277ba3d168d572c2538b
 SHA512:
-  metadata.gz: ba9f01ea9fc094a4ece357bacddc46cf235704f242eea88393de8ea5b1e5ae56b1f5260ad26e999ad53047d4a4c7f6d855612ea6de139e80ae7d60ec6b305fdf
-  data.tar.gz: fb498abaae70d4b8c56736b8267f87ae3637ddfe6b3aad675ad35c2faa1d4681a3a91be98ce6604454b185557a11aaf5a8294b0e007a849ff08ff19cad3088ae
+  metadata.gz: 8b315bed1e2a9ef29f956333086d2ad35a77f8d8c305440fea90830b89d074269c8969cb5c6002a33f3f660974defa165eb270d4671338a3f7df43c07015d78f
+  data.tar.gz: c2807ef7f0f1289a6515114c34aba03dd3959a50467f4c2fa6ef22efd88c2b75db87b40e1ec8b5a3b29a7e334f5c96d2fc07a1196e3100a3a6c518d726da3ecd

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Release History
 
+### 2.6.0 / 2021-03-31
+
+#### Features
+
+* add cmek backup support - ext of [#8142](https://www.github.com/googleapis/google-cloud-ruby/issues/8142) ([#8168](https://www.github.com/googleapis/google-cloud-ruby/issues/8168))
+  * feat(spanner): add cmek backup support
+  * Add encryption_config to restore database.
+  * doc example for backup create with encryption config
+  * create backup with encryption type
+  * backup restore with encryption type changes
+  * fix typo
+* add cmek db support
+
 ### 2.5.0 / 2021-03-10
 
 #### Features

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

@@ -88,6 +88,12 @@ module Google
           @grpc.database.split("/")[5]
         end
 
+        # Encryption information for a given resource.
+        # @return [Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo, nil]
+        def encryption_info
+          @grpc.encryption_info
+        end
+
         ##
         # The full path for the backup. Values are of the form
         # `projects/<project>/instances/<instance>/backups/<backup_id>`.
@@ -245,6 +251,29 @@ module Google
         #   project and have the same instance configuration as the instance
         #   containing the source backup. Optional. Default value is same as a
         #   backup instance.
+        # @param [Hash] encryption_config An encryption configuration describing
+        #   the encryption type and key resources in Cloud KMS used to
+        #   encrypt/decrypt the database to restore to. If this field is not
+        #   specified, the restored database will use the same encryption
+        #   configuration as the backup by default. Optional. The following
+        #   settings can be provided:
+        #
+        #   * `:kms_key_name` (String) The name of KMS key to use which should
+        #     be the full path, e.g., `projects/<project>/locations/<location>\
+        #     /keyRings/<key_ring>/cryptoKeys/<kms_key_name>`
+        #      This field should be set only when encryption type
+        #     `:CUSTOMER_MANAGED_ENCRYPTION`.
+        #   * `:encryption_type` (Symbol) The encryption type of the backup.
+        #     Valid values are:
+        #       1. `:USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION` - This is the default
+        #         option when config is not specified.
+        #       2. `:GOOGLE_DEFAULT_ENCRYPTION` - Google default encryption.
+        #       3. `:CUSTOMER_MANAGED_ENCRYPTION` - Use customer managed encryption.
+        #         If specified, `:kms_key_name` must contain a valid Cloud KMS key.
+        #
+        #  @raise [ArgumentError] if `:CUSTOMER_MANAGED_ENCRYPTION` specified without
+        #   customer managed kms key.
+        #
         # @return [Database] Restored database.
         #
         # @example
@@ -288,16 +317,50 @@ module Google
         #     database = job.database
         #   end
         #
-        def restore database_id, instance_id: nil
+        # @example Restore database with encryption config
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
+        #   encryption_config = {
+        #     kms_key_name: kms_key_name,
+        #     encryption_type: :CUSTOMER_MANAGED_ENCRYPTION
+        #   }
+        #   job = backup.restore(
+        #     "my-restored-database",
+        #     encryption_config: encryption_config
+        #   )
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        def restore database_id, instance_id: nil, encryption_config: nil
           ensure_service!
 
           instance_id ||= self.instance_id
 
+          if encryption_config&.include?(:kms_key_name) &&
+             encryption_config[:encryption_type] != :CUSTOMER_MANAGED_ENCRYPTION
+            raise Google::Cloud::InvalidArgumentError,
+                  "kms_key_name only used with CUSTOMER_MANAGED_ENCRYPTION"
+          end
+
           grpc = service.restore_database \
             self.instance_id,
             backup_id,
             instance_id,
-            database_id
+            database_id,
+            encryption_config: encryption_config
           Restore::Job.from_grpc grpc, service
         end
 

data/lib/google/cloud/spanner/database.rb

@@ -113,6 +113,31 @@ module Google
           @grpc.state
         end
 
+        # An encryption configuration describing the encryption type and key
+        # resources in Cloud KMS.
+        #
+        # @return [Google::Cloud::Spanner::Admin::Database::V1::EncryptionConfig, nil]
+        def encryption_config
+          @grpc.encryption_config
+        end
+
+        # Encryption information for the database.
+        #
+        # For databases that are using customer managed encryption, this
+        # field contains the encryption information for the database, such as
+        # encryption state and the Cloud KMS key versions that are in use.
+        #
+        # For databases that are using Google default or other types of encryption,
+        # this field is empty.
+        #
+        # This field is propagated lazily from the backend. There might be a delay
+        # from when a key version is being used and when it appears in this field.
+        #
+        # @return [Array<Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo>]
+        def encryption_info
+          @grpc.encryption_info.to_a
+        end
+
         ##
         # The database is still being created. Operations on the database may
         # raise with `FAILED_PRECONDITION` in this state.
@@ -417,6 +442,26 @@ module Google
         #   it will be automatically set to the backup create time. The version
         #   time can be as far in the past as specified by the database earliest
         #   version time. Optional.
+        # @param [Hash] encryption_config An encryption configuration describing
+        #   the encryption type and key resources in Cloud KMS. Optional. The
+        #   following settings can be provided:
+        #
+        #   * `:kms_key_name` (String) The name of KMS key to use which should
+        #     be the full path, e.g., `projects/<project>/locations/<location>\
+        #     /keyRings/<key_ring>/cryptoKeys/<kms_key_name>`
+        #     This field should be set only when encryption type
+        #     `:CUSTOMER_MANAGED_ENCRYPTION`.
+        #   * `:encryption_type` (Symbol) The encryption type of the backup.
+        #     Valid values are:
+        #       1. `:USE_DATABASE_ENCRYPTION` - Use the same encryption configuration as
+        #         the database.
+        #       2. `:GOOGLE_DEFAULT_ENCRYPTION` - Google default encryption.
+        #       3. `:CUSTOMER_MANAGED_ENCRYPTION` - Use customer managed encryption.
+        #         If specified, `:kms_key_name` must contain a valid Cloud KMS key.
+        #
+        # @raise [ArgumentError] if `:CUSTOMER_MANAGED_ENCRYPTION` specified without
+        #   customer managed kms key.
+        #
         # @return [Google::Cloud::Spanner::Backup::Job] The job representing
         #   the long-running, asynchronous processing of a backup create
         #   operation.
@@ -443,14 +488,48 @@ module Google
         #     backup = job.backup
         #   end
         #
-        def create_backup backup_id, expire_time, version_time: nil
+        # @example Create backup with encryption config
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   database = spanner.database "my-instance", "my-database"
+        #
+        #   kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
+        #   encryption_config = {
+        #     kms_key_name: kms_key_name,
+        #     encryption_type: :CUSTOMER_MANAGED_ENCRYPTION
+        #   }
+        #   job = database.create_backup "my-backup",
+        #                                Time.now + 36000,
+        #                                encryption_config: encryption_config
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        def create_backup backup_id, expire_time,
+                          version_time: nil, encryption_config: nil
           ensure_service!
+
+          if encryption_config&.include?(:kms_key_name) &&
+             encryption_config[:encryption_type] != :CUSTOMER_MANAGED_ENCRYPTION
+            raise Google::Cloud::InvalidArgumentError,
+                  "kms_key_name only used with CUSTOMER_MANAGED_ENCRYPTION"
+          end
+
           grpc = service.create_backup \
             instance_id,
             database_id,
             backup_id,
             expire_time,
-            version_time
+            version_time,
+            encryption_config: encryption_config
           Backup::Job.from_grpc grpc, service
         end
 

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

@@ -306,6 +306,13 @@ module Google
         #   These statements execute atomically with the creation of the
         #   database: if there is an error in any statement, the database is not
         #   created. Optional.
+        # @param [Hash] encryption_config An encryption configuration describing
+        #   the encryption type and key resources in Cloud KMS. Optional. The
+        #   following settings can be provided:
+        #
+        #   * `:kms_key_name` (String) The name of KMS key to use which should
+        #     be the full path, e.g., `projects/<project>/locations/<location>\
+        #     /keyRings/<key_ring>/cryptoKeys/<kms_key_name>`
         #
         # @return [Database::Job] The job representing the long-running,
         #   asynchronous processing of a database create operation.
@@ -328,9 +335,30 @@ module Google
         #     database = job.database
         #   end
         #
-        def create_database database_id, statements: []
+        # @example Create with encryption config
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #
+        #   kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
+        #   job = instance.create_database "my-new-database", encryption_config: { kms_key_name: kms_key_name }
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        def create_database database_id, statements: [], encryption_config: nil
           grpc = service.create_database instance_id, database_id,
-                                         statements: statements
+                                         statements: statements,
+                                         encryption_config: encryption_config
           Database::Job.from_grpc grpc, service
         end
 

data/lib/google/cloud/spanner/project.rb

@@ -380,6 +380,13 @@ module Google
         #   These statements execute atomically with the creation of the
         #   database: if there is an error in any statement, the database is not
         #   created. Optional.
+        # @param [Hash] encryption_config An encryption configuration describing
+        #   the encryption type and key resources in Cloud KMS. Optional. The
+        #   following settings can be provided:
+        #
+        #   * `:kms_key_name` (String) The name of KMS key to use which should
+        #     be the full path, e.g., `projects/<project>/locations/<location>\
+        #     /keyRings/<key_ring>/cryptoKeys/<kms_key_name>`
         #
         # @return [Database::Job] The job representing the long-running,
         #   asynchronous processing of a database create operation.
@@ -402,9 +409,32 @@ module Google
         #     database = job.database
         #   end
         #
-        def create_database instance_id, database_id, statements: []
+        # @example Create with encryption config
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
+        #   encryption_config = { kms_key_name: kms_key_name }
+        #   job = spanner.create_database "my-instance",
+        #                                 "my-new-database",
+        #                                 encryption_config: encryption_config
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        def create_database instance_id, database_id, statements: [],
+                            encryption_config: nil
           grpc = service.create_database instance_id, database_id,
-                                         statements: statements
+                                         statements: statements,
+                                         encryption_config: encryption_config
           Database::Job.from_grpc grpc, service
         end
 

data/lib/google/cloud/spanner/service.rb

@@ -214,12 +214,13 @@ module Google
         end
 
         def create_database instance_id, database_id, statements: [],
-                            call_options: nil
+                            call_options: nil, encryption_config: nil
           opts = default_options call_options: call_options
           request = {
             parent: instance_path(instance_id),
             create_statement: "CREATE DATABASE `#{database_id}`",
-            extra_statements: Array(statements)
+            extra_statements: Array(statements),
+            encryption_config: encryption_config
           }
           databases.create_database request, opts
         end
@@ -468,7 +469,8 @@ module Google
         end
 
         def create_backup instance_id, database_id, backup_id, expire_time,
-                          version_time, call_options: nil
+                          version_time, call_options: nil,
+                          encryption_config: nil
           opts = default_options call_options: call_options
           backup = {
             database: database_path(instance_id, database_id),
@@ -478,7 +480,8 @@ module Google
           request = {
             parent:    instance_path(instance_id),
             backup_id: backup_id,
-            backup:    backup
+            backup:    backup,
+            encryption_config: encryption_config
           }
           databases.create_backup request, opts
         end
@@ -545,12 +548,13 @@ module Google
 
         def restore_database backup_instance_id, backup_id,
                              database_instance_id, database_id,
-                             call_options: nil
+                             call_options: nil, encryption_config: nil
           opts = default_options call_options: call_options
           request = {
             parent:      instance_path(database_instance_id),
             database_id: database_id,
-            backup:      backup_path(backup_instance_id, backup_id)
+            backup:      backup_path(backup_instance_id, backup_id),
+            encryption_config: encryption_config
           }
           databases.restore_database request, opts
         end

data/lib/google/cloud/spanner/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.5.0".freeze
+      VERSION = "2.6.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-spanner
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-11 00:00:00.000000000 Z
+date: 2021-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core