lib/google/cloud/storage/file.rb in google-cloud-storage-1.11.0 vs lib/google/cloud/storage/file.rb in google-cloud-storage-1.12.0
- old
+ new
@@ -307,10 +307,27 @@
return nil unless @gapi.customer_encryption
Base64.decode64 @gapi.customer_encryption.key_sha256
end
##
+ # The Cloud KMS encryption key that was used to protect the file, or
+ # `nil` if none has been configured.
+ #
+ # @see https://cloud.google.com/kms/docs/ Cloud Key Management Service
+ # Documentation
+ #
+ # @return [String, nil] A Cloud KMS encryption key, or `nil` if none has
+ # been configured.
+ #
+ # @see https://cloud.google.com/kms/docs/ Cloud Key Management Service
+ # Documentation
+ #
+ def kms_key
+ @gapi.kms_key_name
+ end
+
+ ##
# The file's storage class. This defines how the file is stored and
# determines the SLA and the cost of storage. For more information, see
# [Storage
# Classes](https://cloud.google.com/storage/docs/storage-classes) and
# [Per-Object Storage
@@ -318,15 +335,20 @@
def storage_class
@gapi.storage_class
end
##
- # Updates how the file is stored and determines the SLA and the cost of
- # storage. Accepted values include `:multi_regional`, `:regional`,
- # `:nearline`, and `:coldline`, as well as the equivalent strings
- # returned by {File#storage_class} or {Bucket#storage_class}. For more
- # information, see [Storage
+ # Rewrites the file with a new storage class, which determines the SLA
+ # and the cost of storage. Accepted values include:
+ #
+ # * `:multi_regional`
+ # * `:regional`
+ # * `:nearline`
+ # * `:coldline`
+ #
+ # as well as the equivalent strings returned by {File#storage_class} or
+ # {Bucket#storage_class}. For more information, see [Storage
# Classes](https://cloud.google.com/storage/docs/storage-classes) and
# [Per-Object Storage
# Class](https://cloud.google.com/storage/docs/per-object-storage-class).
# The default value is the default storage class for the bucket. See
# {Bucket#storage_class}.
@@ -716,13 +738,22 @@
# @param [Integer] generation Select a specific revision of the file to
# rewrite. The default is the latest version.
# @param [String] encryption_key Optional. The customer-supplied,
# AES-256 encryption key used to decrypt the file, if the existing
# file is encrypted.
- # @param [String] new_encryption_key Optional. The customer-supplied,
- # AES-256 encryption key used to encrypt the file, if the rewritten
- # file is intended to be encrypted.
+ # @param [String, nil] new_encryption_key Optional. The new
+ # customer-supplied, AES-256 encryption key with which to encrypt the
+ # file. If not provided, the rewritten file will be encrypted using
+ # the default server-side encryption, or the `new_kms_key` if one is
+ # provided. Do not provide if `new_kms_key` is used.
+ # @param [String] new_kms_key Optional. Resource name of the Cloud KMS
+ # key, of the form
+ # `projects/my-prj/locations/kr-loc/keyRings/my-kr/cryptoKeys/my-key`,
+ # that will be used to encrypt the file. The KMS key ring must use
+ # the same location as the bucket.The Service Account associated with
+ # your project requires access to this encryption key. Do not provide
+ # if `new_encryption_key` is used.
# @yield [file] a block yielding a delegate object for updating
#
# @return [Google::Cloud::Storage::File]
#
# @example The file can be rewritten to a new path in the bucket:
@@ -768,11 +799,11 @@
# file.rewrite "new-destination-bucket",
# "path/to/destination/file.ext" do |f|
# f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
# end
#
- # @example The file can be rewritten with a new encryption key:
+ # @example Rewriting with a customer-supplied encryption key:
# require "google/cloud/storage"
#
# storage = Google::Cloud::Storage.new
#
# bucket = storage.bucket "my-bucket"
@@ -791,13 +822,35 @@
# encryption_key: old_key,
# new_encryption_key: new_key do |f|
# f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
# end
#
+ # @example Rewriting with a customer-managed Cloud KMS encryption key:
+ # require "google/cloud/storage"
+ #
+ # storage = Google::Cloud::Storage.new
+ #
+ # bucket = storage.bucket "my-bucket"
+ #
+ # # KMS key ring must use the same location as the bucket.
+ # kms_key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
+ #
+ # # Old customer-supplied key was stored securely for later use.
+ # old_key = "y\x03\"\x0E\xB6\xD3\x9B\x0E\xAB*\x19\xFAv\xDEY\xBEI..."
+ #
+ # file = bucket.file "path/to/my-file.ext"
+ # file.rewrite "new-destination-bucket",
+ # "path/to/destination/file.ext",
+ # encryption_key: old_key,
+ # new_kms_key: kms_key_name do |f|
+ # f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
+ # end
+ #
def rewrite dest_bucket_or_path, dest_path = nil,
acl: nil, generation: nil,
- encryption_key: nil, new_encryption_key: nil
+ encryption_key: nil, new_encryption_key: nil,
+ new_kms_key: nil
ensure_service!
dest_bucket, dest_path = fix_rewrite_args dest_bucket_or_path,
dest_path
update_gapi = nil
@@ -813,10 +866,11 @@
new_gapi = rewrite_gapi bucket, name, update_gapi,
new_bucket: dest_bucket, new_name: dest_path,
acl: acl, generation: generation,
encryption_key: encryption_key,
new_encryption_key: new_encryption_key,
+ new_kms_key: new_kms_key,
user_project: user_project
File.from_gapi new_gapi, service, user_project: user_project
end
@@ -839,17 +893,24 @@
# @param [String, nil] encryption_key Optional. The last
# customer-supplied, AES-256 encryption key used to encrypt the file,
# if one was used.
# @param [String, nil] new_encryption_key Optional. The new
# customer-supplied, AES-256 encryption key with which to encrypt the
- # file. If `nil`, the rewritten file will be encrypted using the
- # default server-side encryption, not customer-supplied encryption
- # keys.
+ # file. If not provided, the rewritten file will be encrypted using
+ # the default server-side encryption, or the `new_kms_key` if one is
+ # provided. Do not provide if `new_kms_key` is used.
+ # @param [String] new_kms_key Optional. Resource name of the Cloud KMS
+ # key, of the form
+ # `projects/my-prj/locations/kr-loc/keyRings/my-kr/cryptoKeys/my-key`,
+ # that will be used to encrypt the file. The KMS key ring must use
+ # the same location as the bucket.The Service Account associated with
+ # your project requires access to this encryption key. Do not provide
+ # if `new_encryption_key` is used.
#
# @return [Google::Cloud::Storage::File]
#
- # @example The file will be rewritten with a new encryption key:
+ # @example Rotating to a new customer-supplied encryption key:
# require "google/cloud/storage"
#
# storage = Google::Cloud::Storage.new
# bucket = storage.bucket "my-bucket"
#
@@ -863,13 +924,31 @@
# cipher.encrypt
# new_key = cipher.random_key
#
# file.rotate encryption_key: old_key, new_encryption_key: new_key
#
- def rotate encryption_key: nil, new_encryption_key: nil
+ # @example Rotating to a customer-managed Cloud KMS encryption key:
+ # require "google/cloud/storage"
+ #
+ # storage = Google::Cloud::Storage.new
+ # bucket = storage.bucket "my-bucket"
+ #
+ # # KMS key ring must use the same location as the bucket.
+ # kms_key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
+ #
+ # # Old key was stored securely for later use.
+ # old_key = "y\x03\"\x0E\xB6\xD3\x9B\x0E\xAB*\x19\xFAv\xDEY\xBEI..."
+ #
+ # file = bucket.file "path/to/my-file.ext", encryption_key: old_key
+ #
+ # file.rotate encryption_key: old_key, new_kms_key: kms_key_name
+ #
+ def rotate encryption_key: nil, new_encryption_key: nil,
+ new_kms_key: nil
rewrite bucket, name, encryption_key: encryption_key,
- new_encryption_key: new_encryption_key
+ new_encryption_key: new_encryption_key,
+ new_kms_key: new_kms_key
end
##
# Permanently deletes the file.
#
@@ -1231,11 +1310,12 @@
update_gapi = gapi_from_attrs attributes
return if update_gapi.nil?
ensure_service!
- @gapi = if attributes.include? :storage_class
+ rewrite_attrs = %i[storage_class kms_key_name]
+ @gapi = if attributes.any? { |a| rewrite_attrs.include? a }
rewrite_gapi \
bucket, name, update_gapi, user_project: user_project
else
service.patch_file \
bucket, name, update_gapi, user_project: user_project
@@ -1252,15 +1332,17 @@
end
def rewrite_gapi bucket, name, updated_gapi,
new_bucket: nil, new_name: nil, acl: nil,
generation: nil, encryption_key: nil,
- new_encryption_key: nil, user_project: nil
+ new_encryption_key: nil, new_kms_key: nil,
+ user_project: nil
new_bucket ||= bucket
new_name ||= name
options = { acl: File::Acl.predefined_rule_for(acl),
generation: generation, source_key: encryption_key,
destination_key: new_encryption_key,
+ destination_kms_key: new_kms_key,
user_project: user_project }.delete_if { |_k, v| v.nil? }
resp = service.rewrite_file \
bucket, name, new_bucket, new_name, updated_gapi, options
until resp.done