feat: Add new gcloud commands, API clients, and third-party libraries across various services.

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2019 Google LLC. All Rights Reserved.
+#
+# 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
+#
+#    http://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.
+
+"""The backups command group for spanner."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA,
+                    base.ReleaseTrack.GA)
+class Backups(base.Group):
+  """Manage Cloud Spanner backups."""

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/add_iam_policy_binding.yaml

@@ -0,0 +1,42 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Add IAM policy binding to a Cloud Spanner backup.
+    description: |
+      Add an IAM policy binding to a Cloud Spanner backup. One binding consists of
+      a member, a role, and an optional condition.
+
+    examples: |
+      To add an IAM policy binding for the role of 'roles/spanner.backupAdmin' for the user
+      'test-user@gmail.com' with backup 'example-backup' and instance 'example-instance', run:
+
+        $ {command} example-backup \
+            --instance='example-instance' \
+            --member='user:test-user@gmail.com' \
+            --role='roles/spanner.backupAdmin'
+
+      To add an IAM policy binding which expires at the end of the year 2018 for the role of
+      'roles/spanner.backupAdmin' and the user 'test-user@gmail.com' with backup 'example-backup'
+      and instance 'example-instance', run:
+
+        $ {command} example-backup \
+            --instance='example-instance' \
+            --member='user:test-user@gmail.com' \
+            --role='roles/spanner.backupAdmin' \
+            --condition='expression=request.time < timestamp("2019-01-01T00:00:00Z"),title=expires_end_of_2018,description=Expires at midnight on 2018-12-31'
+
+      See https://cloud.google.com/iam/docs/managing-policies for details of
+      policy role and member types.
+
+  request:
+    collection: spanner.projects.instances.backups
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup to which to add the IAM policy binding.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup
+
+  iam:
+    enable_condition: true
+    policy_version: 3
+    get_iam_policy_version_path: getIamPolicyRequest.options.requestedPolicyVersion

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/copy.py

@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2022 Google LLC. All Rights Reserved.
+#
+# 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
+#
+#    http://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.
+"""Command for spanner backup copy."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+import textwrap
+
+from googlecloudsdk.api_lib.spanner import backup_operations
+from googlecloudsdk.api_lib.spanner import backups
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import resource_args
+from googlecloudsdk.core import log
+
+
+class Copy(base.Command):
+  """Copies a backup of a Cloud Spanner database."""
+
+  detailed_help = {
+      'EXAMPLES':
+          textwrap.dedent("""\
+        To copy a backup within the same project, run:
+
+          $ {command} --source-instance=SOURCE_INSTANCE_ID --source-backup=SOURCE_BACKUP_ID  --destination-instance=DESTINATION_INSTANCE_ID --destination-backup=DESTINATION_BACKUP_ID --expiration-date=2020-03-29T10:49:41Z
+
+        To copy a backup to a different project, run:
+
+          $ {command} --source-backup=projects/SOURCE_PROJECT_ID/instances/SOURCE_INSTANCE_ID/backups/SOURCE_BACKUP_ID --destination-backup=projects/DESTINATION_PROJECT_ID/instances/DESTINATION_INSTANCE_ID/backups/DESTINATION_BACKUP_ID --expiration-date=2020-03-29T10:49:41Z
+
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Register flags for this command."""
+
+    resource_args.AddCopyBackupResourceArgs(parser)
+    group_parser = parser.add_argument_group(mutex=True, required=True)
+    group_parser.add_argument(
+        '--expiration-date',
+        help='Expiration time of the backup, must be at least 6 hours and at '
+        'most 366 days from the time when the source backup is created. See '
+        '`$ gcloud topic datetimes` for information on date/time formats.')
+    group_parser.add_argument(
+        '--retention-period',
+        help='Retention period of the backup relative from now, must be at '
+        'least 6 hours and at most 366 days from the time when the source '
+        'backup is created. See `$ gcloud topic datetimes` for information '
+        'on duration formats.')
+    base.ASYNC_FLAG.AddToParser(parser)
+    encryption_group_parser = parser.add_argument_group()
+    resource_args.AddCopyBackupEncryptionTypeArg(encryption_group_parser)
+    resource_args.AddKmsKeyResourceArg(encryption_group_parser,
+                                       'to copy the Cloud Spanner backup')
+
+  def Run(self, args):
+    """This is what gets called when the user runs this command."""
+
+    source_backup_ref = args.CONCEPTS.source.Parse()
+    destination_backup_ref = args.CONCEPTS.destination.Parse()
+    encryption_type = resource_args.GetCopyBackupEncryptionType(args)
+    kms_key = resource_args.GetAndValidateKmsKeyName(args)
+    op = backups.CopyBackup(source_backup_ref, destination_backup_ref, args,
+                            encryption_type, kms_key)
+    if args.async_:
+      log.status.Print('Copy request issued from [{}] to [{}]\n'
+                       'Check operation [{}] for status.'.format(
+                           source_backup_ref.RelativeName(),
+                           destination_backup_ref.RelativeName(), op.name))
+      return op
+
+    op_result = backup_operations.Await(
+        op, 'Waiting for operation [{}] to complete'.format(op.name))
+    if op.error is None:
+      log.CreatedResource(op_result)
+    return op_result

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/create.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2020 Google LLC. All Rights Reserved.
+#
+# 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
+#
+#    http://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.
+"""Command for spanner backup create."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+import textwrap
+
+from googlecloudsdk.api_lib.spanner import backup_operations
+from googlecloudsdk.api_lib.spanner import backups
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import resource_args
+from googlecloudsdk.core import log
+
+
+class Create(base.CreateCommand):
+  """Creates a backup of a Cloud Spanner database.
+
+  Creates a backup of a Cloud Spanner database.
+  """
+
+  detailed_help = {
+      'EXAMPLES':
+          textwrap.dedent("""\
+        To create a backup asynchronously, run:
+
+          $ {command} BACKUP_ID --instance=INSTANCE_NAME --database=DATABASE --expiration-date=2020-03-29T10:49:41Z --async
+
+        To create a backup synchronously, run:
+
+          $ {command} BACKUP_ID --instance=INSTANCE_NAME --database=DATABASE --retention-period=2w
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Register flags for this command."""
+
+    resource_args.AddBackupResourceArg(parser, 'to create')
+    parser.add_argument(
+        '--database',
+        required=True,
+        help='ID of the database from which the backup will be created.')
+
+    group_parser = parser.add_argument_group(mutex=True, required=True)
+    group_parser.add_argument(
+        '--expiration-date',
+        help='Expiration time of the backup, must be at least 6 hours and at '
+        'most 30 days from the time the request is received. See '
+        '`$ gcloud topic datetimes` for information on date/time formats.')
+    group_parser.add_argument(
+        '--retention-period',
+        help='Retention period of the backup relative from now, must be at '
+        'least 6 hours and at most 30 days. See `$ gcloud topic '
+        'datetimes` for information on duration formats.')
+
+    parser.add_argument(
+        '--version-time',
+        metavar='TIMESTAMP',
+        help='The backup will contain an externally consistent copy of the '
+        'database at the timestamp specified by `--version-time`. If '
+        '`--version-time` is not specified, the system will use the creation '
+        'time of the backup.')
+
+    base.ASYNC_FLAG.AddToParser(parser)
+    encryption_group_parser = parser.add_argument_group()
+    resource_args.AddCreateBackupEncryptionTypeArg(encryption_group_parser)
+    resource_args.AddKmsKeyResourceArg(encryption_group_parser,
+                                       'to create the Cloud Spanner backup')
+
+  def Run(self, args):
+    """This is what gets called when the user runs this command."""
+
+    backup_ref = args.CONCEPTS.backup.Parse()
+    encryption_type = resource_args.GetCreateBackupEncryptionType(args)
+    kms_key = resource_args.GetAndValidateKmsKeyName(args)
+    op = backups.CreateBackup(backup_ref, args, encryption_type, kms_key)
+    if args.async_:
+      log.status.Print('Create request issued for: [{}]\n'
+                       'Check operation [{}] for status.'.format(
+                           args.backup, op.name))
+      return op
+
+    op_result = backup_operations.Await(
+        op, 'Waiting for operation [{}] to complete'.format(op.name))
+    if op.error is None:
+      log.CreatedResource(op_result)
+    return op_result

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/delete.yaml

@@ -0,0 +1,18 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Delete an existing backup.
+    description: Delete an existing backup.
+    examples: |
+      To delete a backup, run:
+
+        $ {command} BACKUP_NAME --instance=INSTANCE_NAME
+
+  request:
+    collection: spanner.projects.instances.backups
+    modify_request_hooks:
+    - googlecloudsdk.api_lib.spanner.backups:CheckBackupExists
+  arguments:
+    resource:
+      help_text: Cloud Spanner backup to delete.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/describe.yaml

@@ -0,0 +1,17 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Retrieves information about a backup.
+    description: Retrieves information about a backup.
+    examples: |
+      To describe a backup, run:
+
+        $ {command} BACKUP_ID --instance=INSTANCE_NAME
+
+  request:
+    collection: spanner.projects.instances.backups
+
+  arguments:
+    resource:
+      help_text: Cloud Spanner backup to describe.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/get_iam_policy.yaml

@@ -0,0 +1,23 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Get the IAM policy for a Cloud Spanner backup.
+    description: |
+      *{command}* displays the IAM policy associated with a Cloud Spanner
+      database. If formatted as JSON, the output can be edited and used as
+      a policy file for *set-iam-policy*. The output includes an "etag"
+      field identifying the version emitted and allowing detection of
+      concurrent policy updates; see
+      $ {parent} set-iam-policy for additional details.
+    examples: |
+      To print the IAM policy for a given Cloud Spanner backup, run:
+
+        $ {command} example-backup --instance=example-instance
+
+  request:
+    collection: spanner.projects.instances.backups
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup for which to display the IAM policy.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/list.yaml

@@ -0,0 +1,85 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: List existing Cloud Spanner Cloud Spanner backups.
+    description: List existing Cloud Spanner Cloud Spanner backups.
+    examples: |
+      To list existing backups for the instance, run:
+
+        $ {command} --instance=INSTANCE_NAME
+
+      To list existing backups for a database, run:
+
+        $ {command} --instance=INSTANCE_NAME --database=DATABASE
+
+  request:
+    collection: spanner.projects.instances.backups
+    modify_request_hooks:
+    - googlecloudsdk.api_lib.spanner.backups:ModifyListRequest
+
+  arguments:
+    params:
+    - arg_name: database
+      api_field: filter
+      required: false
+      help_text: |
+        ID of the source database. The database flag will take precedence over filters added for
+        database.
+    resource:
+      help_text: Cloud Spanner instance ID.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:instance
+
+  response:
+    modify_response_hooks:
+    - googlecloudsdk.api_lib.spanner.backups:FormatListBackups
+
+  # TODO: b/358133268 - Remove the alpha and beta track overrides once we have the instance
+  # partitions column in the GA track.
+  output:
+    ALPHA:
+      format: |
+        table(
+          name.basename(): label=BACKUP,
+          database.basename(): label=SOURCE_DATABASE,
+          versionTime: label=VERSION_TIME,
+          createTime: label=CREATION_TIME,
+          expireTime: label=EXPIRATION_TIME,
+          state: label=STATE,
+          backupSchedules.join(", "): label=BACKUP_SCHEDULES,
+          instancePartitions.instancePartition.join(", "): label=INSTANCE_PARTITIONS,
+          encryptionInfo.encryptionType: label=ENCRYPTION_TYPE,
+          sizeBytes: label=BACKUP_SIZE_BYTES,
+          exclusiveSizeBytes: label=EXCLUSIVE_SIZE_BYTES,
+          oldestVersionTime: label=OLDEST_VERSION_TIME
+        )
+    BETA:
+      format: |
+        table(
+          name.basename(): label=BACKUP,
+          database.basename(): label=SOURCE_DATABASE,
+          versionTime: label=VERSION_TIME,
+          createTime: label=CREATION_TIME,
+          expireTime: label=EXPIRATION_TIME,
+          state: label=STATE,
+          backupSchedules.join(", "): label=BACKUP_SCHEDULES,
+          instancePartitions.instancePartition.join(", "): label=INSTANCE_PARTITIONS,
+          encryptionInfo.encryptionType: label=ENCRYPTION_TYPE,
+          sizeBytes: label=BACKUP_SIZE_BYTES,
+          exclusiveSizeBytes: label=EXCLUSIVE_SIZE_BYTES,
+          oldestVersionTime: label=OLDEST_VERSION_TIME
+        )
+    GA:
+      format: |
+        table(
+          name.basename(): label=BACKUP,
+          database.basename(): label=SOURCE_DATABASE,
+          versionTime: label=VERSION_TIME,
+          createTime: label=CREATION_TIME,
+          expireTime: label=EXPIRATION_TIME,
+          state: label=STATE,
+          backupSchedules.join(", "): label=BACKUP_SCHEDULES,
+          encryptionInfo.encryptionType: label=ENCRYPTION_TYPE,
+          sizeBytes: label=BACKUP_SIZE_BYTES,
+          exclusiveSizeBytes: label=EXCLUSIVE_SIZE_BYTES,
+          oldestVersionTime: label=OLDEST_VERSION_TIME
+        )

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/remove_iam_policy_binding.yaml

@@ -0,0 +1,42 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Remove IAM policy binding of a Cloud Spanner backup.
+    description: |
+      Remove an IAM policy binding of a Cloud Spanner backup. One binding
+      consists of a member, a role, and an optional condition.
+
+    examples: |
+      To remove an IAM policy binding for the role of 'roles/spanner.backupAdmin' for the user
+      'test-user@gmail.com' with backup 'example-backup' and instance 'example-instance', run:
+
+        $ {command} example-backup \
+            --instance='example-instance' \
+            --member='user:test-user@gmail.com' \
+            --role='roles/spanner.backupAdmin'
+
+      To remove an IAM policy binding which expires at the end of the year 2018 for the role of
+      'roles/spanner.backupAdmin' and the user 'test-user@gmail.com' with backup 'example-backup'
+      and instance 'example-instance', run:
+
+        $ {command} example-backup \
+            --instance='example-instance' \
+            --member='user:test-user@gmail.com' \
+            --role='roles/spanner.backupAdmin' \
+            --condition='expression=request.time < timestamp("2019-01-01T00:00:00Z"),title=expires_end_of_2018,description=Expires at midnight on 2018-12-31'
+
+      See https://cloud.google.com/iam/docs/managing-policies for details of
+      policy role and member types.
+
+  request:
+    collection: spanner.projects.instances.backups
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup to remove the IAM policy binding from.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup
+
+  iam:
+    enable_condition: true
+    policy_version: 3
+    get_iam_policy_version_path: getIamPolicyRequest.options.requestedPolicyVersion

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/set_iam_policy.yaml

@@ -0,0 +1,23 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Set the IAM policy for a Cloud Spanner backup.
+    description: |
+      Set the IAM policy for a Cloud Spanner backup given a backup ID and
+      a file encoded in JSON or YAML that contains the IAM policy.
+    examples: |
+      The following command reads an IAM policy defined in a JSON file
+      `policy.json` and sets it for a spanner instance with the ID
+      `example-instance`:
+
+        $ {command} example-backup --instance=example-instance policy.json
+
+      See https://cloud.google.com/iam/docs/managing-policies for details of the
+      policy file format and contents.
+  request:
+    collection: spanner.projects.instances.backups
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup to set the IAM policy for.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backups/update_metadata.yaml

@@ -0,0 +1,40 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Updates the metadata of a Cloud Spanner a backup.
+    description: Updates the metadata of a Cloud Spanner a backup.
+    examples: |
+      To update the backup metadata with an exact expiration date, run:
+
+        $ {command} BACKUP_ID --instance=INSTANCE_NAME --expiration-date=2020-03-29T10:49:41Z
+
+      To update the backup metadata with a retention period, run:
+
+        $ {command} BACKUP_ID --instance=INSTANCE_NAME --retention-period=2w
+
+  request:
+    collection: spanner.projects.instances.backups
+    method: 'patch'
+    modify_request_hooks:
+    - googlecloudsdk.api_lib.spanner.backups:ModifyUpdateMetadataRequest
+  arguments:
+    params:
+    - group:
+        mutex: true
+        required: true
+        params:
+        - arg_name: expiration-date
+          api_field: backup.expireTime
+          help_text: |
+            Expiration time of the backup, must be at least 6 hours and at most 366 days from
+            the time of creation. See `$ gcloud topic datetimes` for information on
+            date/time formats.
+        - arg_name: retention-period
+          api_field: backup.expireTime
+          help_text: |
+            Retention period of the backup relative from now, must be at least 6 hours and at most
+            a year from the time of creation. See `$ gcloud topic datetimes` for information on
+            duration formats.
+    resource:
+      help_text: The Cloud Spanner backup to update.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backup