feat: Add support for multi region encryption config (#1136)

* feat: Add support for multi region encryption config

docs: fix linting for several doc comments
PiperOrigin-RevId: 630422337

Source-Link: googleapis/googleapis@65db386

Source-Link: googleapis/googleapis-gen@b798ca9
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYjc5OGNhOWY1NmUyYWQzZTBkMTQ5ODJiNjhiNjcyNGQxYzNkNjJiNSJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

google/cloud/spanner_admin_database_v1/services/database_admin/async_client.py

@@ -69,7 +69,7 @@ class DatabaseAdminAsyncClient:
 
     -  create, drop, and list databases
     -  update the schema of pre-existing databases
-    -  create, delete and list backups for a database
+    -  create, delete, copy and list backups for a database
     -  restore a database from an existing backup
     """
 
@@ -351,7 +351,7 @@ async def sample_list_databases():
         Returns:
             google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListDatabasesAsyncPager:
                 The response for
-                [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
+                   [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
 
                 Iterating over this object will yield results and
                 resolve additional pages automatically.
@@ -1168,7 +1168,7 @@ async def sample_get_database_ddl():
         Returns:
             google.cloud.spanner_admin_database_v1.types.GetDatabaseDdlResponse:
                 The response for
-                [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
+                   [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
 
         """
         # Create or coerce a protobuf request object.
@@ -1807,8 +1807,8 @@ async def copy_backup(
         The [response][google.longrunning.Operation.response] field type
         is [Backup][google.spanner.admin.database.v1.Backup], if
         successful. Cancelling the returned operation will stop the
-        copying and delete the backup. Concurrent CopyBackup requests
-        can run on the same source backup.
+        copying and delete the destination backup. Concurrent CopyBackup
+        requests can run on the same source backup.
 
         .. code-block:: python
 
@@ -2347,7 +2347,7 @@ async def sample_list_backups():
         Returns:
             google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListBackupsAsyncPager:
                 The response for
-                [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
+                   [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
 
                 Iterating over this object will yield results and
                 resolve additional pages automatically.
@@ -2889,7 +2889,7 @@ async def sample_list_database_roles():
             parent (:class:`str`):
                 Required. The database whose roles should be listed.
                 Values are of the form
-                ``projects/<project>/instances/<instance>/databases/<database>/databaseRoles``.
+                ``projects/<project>/instances/<instance>/databases/<database>``.
 
                 This corresponds to the ``parent`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -2903,7 +2903,7 @@ async def sample_list_database_roles():
         Returns:
             google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListDatabaseRolesAsyncPager:
                 The response for
-                [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles].
+                   [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles].
 
                 Iterating over this object will yield results and
                 resolve additional pages automatically.

google/cloud/spanner_admin_database_v1/services/database_admin/client.py

@@ -110,7 +110,7 @@ class DatabaseAdminClient(metaclass=DatabaseAdminClientMeta):
 
     -  create, drop, and list databases
     -  update the schema of pre-existing databases
-    -  create, delete and list backups for a database
+    -  create, delete, copy and list backups for a database
     -  restore a database from an existing backup
     """
 
@@ -868,7 +868,7 @@ def sample_list_databases():
         Returns:
             google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListDatabasesPager:
                 The response for
-                [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
+                   [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases].
 
                 Iterating over this object will yield results and
                 resolve additional pages automatically.
@@ -1667,7 +1667,7 @@ def sample_get_database_ddl():
         Returns:
             google.cloud.spanner_admin_database_v1.types.GetDatabaseDdlResponse:
                 The response for
-                [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
+                   [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl].
 
         """
         # Create or coerce a protobuf request object.
@@ -2303,8 +2303,8 @@ def copy_backup(
         The [response][google.longrunning.Operation.response] field type
         is [Backup][google.spanner.admin.database.v1.Backup], if
         successful. Cancelling the returned operation will stop the
-        copying and delete the backup. Concurrent CopyBackup requests
-        can run on the same source backup.
+        copying and delete the destination backup. Concurrent CopyBackup
+        requests can run on the same source backup.
 
         .. code-block:: python
 
@@ -2831,7 +2831,7 @@ def sample_list_backups():
         Returns:
             google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListBackupsPager:
                 The response for
-                [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
+                   [ListBackups][google.spanner.admin.database.v1.DatabaseAdmin.ListBackups].
 
                 Iterating over this object will yield results and
                 resolve additional pages automatically.
@@ -3361,7 +3361,7 @@ def sample_list_database_roles():
             parent (str):
                 Required. The database whose roles should be listed.
                 Values are of the form
-                ``projects/<project>/instances/<instance>/databases/<database>/databaseRoles``.
+                ``projects/<project>/instances/<instance>/databases/<database>``.
 
                 This corresponds to the ``parent`` field
                 on the ``request`` instance; if ``request`` is provided, this
@@ -3375,7 +3375,7 @@ def sample_list_database_roles():
         Returns:
             google.cloud.spanner_admin_database_v1.services.database_admin.pagers.ListDatabaseRolesPager:
                 The response for
-                [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles].
+                   [ListDatabaseRoles][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabaseRoles].
 
                 Iterating over this object will yield results and
                 resolve additional pages automatically.

google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc.py

@@ -44,7 +44,7 @@ class DatabaseAdminGrpcTransport(DatabaseAdminTransport):
 
     -  create, drop, and list databases
     -  update the schema of pre-existing databases
-    -  create, delete and list backups for a database
+    -  create, delete, copy and list backups for a database
     -  restore a database from an existing backup
 
     This class defines the same methods as the primary client, so the
@@ -681,8 +681,8 @@ def copy_backup(
         The [response][google.longrunning.Operation.response] field type
         is [Backup][google.spanner.admin.database.v1.Backup], if
         successful. Cancelling the returned operation will stop the
-        copying and delete the backup. Concurrent CopyBackup requests
-        can run on the same source backup.
+        copying and delete the destination backup. Concurrent CopyBackup
+        requests can run on the same source backup.
 
         Returns:
             Callable[[~.CopyBackupRequest],

google/cloud/spanner_admin_database_v1/services/database_admin/transports/grpc_asyncio.py

@@ -47,7 +47,7 @@ class DatabaseAdminGrpcAsyncIOTransport(DatabaseAdminTransport):
 
     -  create, drop, and list databases
     -  update the schema of pre-existing databases
-    -  create, delete and list backups for a database
+    -  create, delete, copy and list backups for a database
     -  restore a database from an existing backup
 
     This class defines the same methods as the primary client, so the
@@ -695,8 +695,8 @@ def copy_backup(
         The [response][google.longrunning.Operation.response] field type
         is [Backup][google.spanner.admin.database.v1.Backup], if
         successful. Cancelling the returned operation will stop the
-        copying and delete the backup. Concurrent CopyBackup requests
-        can run on the same source backup.
+        copying and delete the destination backup. Concurrent CopyBackup
+        requests can run on the same source backup.
 
         Returns:
             Callable[[~.CopyBackupRequest],

google/cloud/spanner_admin_database_v1/services/database_admin/transports/rest.py

@@ -769,7 +769,7 @@ class DatabaseAdminRestTransport(DatabaseAdminTransport):
 
     -  create, drop, and list databases
     -  update the schema of pre-existing databases
-    -  create, delete and list backups for a database
+    -  create, delete, copy and list backups for a database
     -  restore a database from an existing backup
 
     This class defines the same methods as the primary client, so the

google/cloud/spanner_admin_database_v1/types/backup.py

@@ -111,6 +111,16 @@ class Backup(proto.Message):
         encryption_info (google.cloud.spanner_admin_database_v1.types.EncryptionInfo):
             Output only. The encryption information for
             the backup.
+        encryption_information (MutableSequence[google.cloud.spanner_admin_database_v1.types.EncryptionInfo]):
+            Output only. The encryption information for the backup,
+            whether it is protected by one or more KMS keys. The
+            information includes all Cloud KMS key versions used to
+            encrypt the backup. The
+            ``encryption_status' field inside of each``\ EncryptionInfo\`
+            is not populated. At least one of the key versions must be
+            available for the backup to be restored. If a key version is
+            revoked in the middle of a restore, the restore behavior is
+            undefined.
         database_dialect (google.cloud.spanner_admin_database_v1.types.DatabaseDialect):
             Output only. The database dialect information
             for the backup.
@@ -190,6 +200,13 @@ class State(proto.Enum):
         number=8,
         message=common.EncryptionInfo,
     )
+    encryption_information: MutableSequence[
+        common.EncryptionInfo
+    ] = proto.RepeatedField(
+        proto.MESSAGE,
+        number=13,
+        message=common.EncryptionInfo,
+    )
     database_dialect: common.DatabaseDialect = proto.Field(
         proto.ENUM,
         number=10,
@@ -366,7 +383,7 @@ class CopyBackupRequest(proto.Message):
 
 
 class CopyBackupMetadata(proto.Message):
-    r"""Metadata type for the google.longrunning.Operation returned by
+    r"""Metadata type for the operation returned by
     [CopyBackup][google.spanner.admin.database.v1.DatabaseAdmin.CopyBackup].
 
     Attributes:
@@ -652,8 +669,8 @@ class ListBackupOperationsRequest(proto.Message):
 
                -  The operation's metadata type is
                   [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata].
-               -  The database the backup was taken from has a name
-                  containing the string "prod".
+               -  The source database name of backup contains the string
+                  "prod".
 
             -  ``(metadata.@type=type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata) AND``
                ``(metadata.name:howl) AND``
@@ -673,8 +690,7 @@ class ListBackupOperationsRequest(proto.Message):
 
                -  The operation's metadata type is
                   [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata].
-               -  The source backup of the copied backup name contains
-                  the string "test".
+               -  The source backup name contains the string "test".
                -  The operation started before 2022-01-18T14:50:00Z.
                -  The operation resulted in an error.
 
@@ -688,12 +704,12 @@ class ListBackupOperationsRequest(proto.Message):
 
                   -  The operation's metadata type is
                      [CreateBackupMetadata][google.spanner.admin.database.v1.CreateBackupMetadata]
-                     AND the database the backup was taken from has name
-                     containing string "test_db"
+                     AND the source database name of the backup contains
+                     the string "test_db"
                   -  The operation's metadata type is
                      [CopyBackupMetadata][google.spanner.admin.database.v1.CopyBackupMetadata]
-                     AND the backup the backup was copied from has name
-                     containing string "test_bkp"
+                     AND the source backup name contains the string
+                     "test_bkp"
 
                -  The operation resulted in an error.
         page_size (int):
@@ -819,6 +835,26 @@ class CreateBackupEncryptionConfig(proto.Message):
             [encryption_type][google.spanner.admin.database.v1.CreateBackupEncryptionConfig.encryption_type]
             is ``CUSTOMER_MANAGED_ENCRYPTION``. Values are of the form
             ``projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>``.
+        kms_key_names (MutableSequence[str]):
+            Optional. Specifies the KMS configuration for the one or
+            more keys used to protect the backup. Values are of the form
+            ``projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>``.
+
+            The keys referenced by kms_key_names must fully cover all
+            regions of the backup's instance configuration. Some
+            examples:
+
+            -  For single region instance configs, specify a single
+               regional location KMS key.
+            -  For multi-regional instance configs of type
+               GOOGLE_MANAGED, either specify a multi-regional location
+               KMS key or multiple regional location KMS keys that cover
+               all regions in the instance config.
+            -  For an instance config of type USER_MANAGED, please
+               specify only regional location KMS keys to cover each
+               region in the instance config. Multi-regional location
+               KMS keys are not supported for USER_MANAGED instance
+               configs.
     """
 
     class EncryptionType(proto.Enum):
@@ -854,6 +890,10 @@ class EncryptionType(proto.Enum):
         proto.STRING,
         number=2,
     )
+    kms_key_names: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=3,
+    )
 
 
 class CopyBackupEncryptionConfig(proto.Message):
@@ -868,6 +908,27 @@ class CopyBackupEncryptionConfig(proto.Message):
             [encryption_type][google.spanner.admin.database.v1.CopyBackupEncryptionConfig.encryption_type]
             is ``CUSTOMER_MANAGED_ENCRYPTION``. Values are of the form
             ``projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>``.
+        kms_key_names (MutableSequence[str]):
+            Optional. Specifies the KMS configuration for the one or
+            more keys used to protect the backup. Values are of the form
+            ``projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>``.
+            Kms keys specified can be in any order.
+
+            The keys referenced by kms_key_names must fully cover all
+            regions of the backup's instance configuration. Some
+            examples:
+
+            -  For single region instance configs, specify a single
+               regional location KMS key.
+            -  For multi-regional instance configs of type
+               GOOGLE_MANAGED, either specify a multi-regional location
+               KMS key or multiple regional location KMS keys that cover
+               all regions in the instance config.
+            -  For an instance config of type USER_MANAGED, please
+               specify only regional location KMS keys to cover each
+               region in the instance config. Multi-regional location
+               KMS keys are not supported for USER_MANAGED instance
+               configs.
     """
 
     class EncryptionType(proto.Enum):
@@ -887,8 +948,9 @@ class EncryptionType(proto.Enum):
             GOOGLE_DEFAULT_ENCRYPTION (2):
                 Use Google default encryption.
             CUSTOMER_MANAGED_ENCRYPTION (3):
-                Use customer managed encryption. If specified,
-                ``kms_key_name`` must contain a valid Cloud KMS key.
+                Use customer managed encryption. If specified, either
+                ``kms_key_name`` or ``kms_key_names`` must contain valid
+                Cloud KMS key(s).
         """
         ENCRYPTION_TYPE_UNSPECIFIED = 0
         USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION = 1
@@ -904,6 +966,10 @@ class EncryptionType(proto.Enum):
         proto.STRING,
         number=2,
     )
+    kms_key_names: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=3,
+    )
 
 
 __all__ = tuple(sorted(__protobuf__.manifest))

google/cloud/spanner_admin_database_v1/types/common.py

@@ -42,7 +42,7 @@ class DatabaseDialect(proto.Enum):
             Default value. This value will create a database with the
             GOOGLE_STANDARD_SQL dialect.
         GOOGLE_STANDARD_SQL (1):
-            Google standard SQL.
+            GoogleSQL supported SQL.
         POSTGRESQL (2):
             PostgreSQL supported SQL.
     """
@@ -90,12 +90,36 @@ class EncryptionConfig(proto.Message):
             The Cloud KMS key to be used for encrypting and decrypting
             the database. Values are of the form
             ``projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>``.
+        kms_key_names (MutableSequence[str]):
+            Specifies the KMS configuration for the one or more keys
+            used to encrypt the database. Values are of the form
+            ``projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>``.
+
+            The keys referenced by kms_key_names must fully cover all
+            regions of the database instance configuration. Some
+            examples:
+
+            -  For single region database instance configs, specify a
+               single regional location KMS key.
+            -  For multi-regional database instance configs of type
+               GOOGLE_MANAGED, either specify a multi-regional location
+               KMS key or multiple regional location KMS keys that cover
+               all regions in the instance config.
+            -  For a database instance config of type USER_MANAGED,
+               please specify only regional location KMS keys to cover
+               each region in the instance config. Multi-regional
+               location KMS keys are not supported for USER_MANAGED
+               instance configs.
     """
 
     kms_key_name: str = proto.Field(
         proto.STRING,
         number=2,
     )
+    kms_key_names: MutableSequence[str] = proto.RepeatedField(
+        proto.STRING,
+        number=3,
+    )
 
 
 class EncryptionInfo(proto.Message):