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/backup_schedules/__init__.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2024 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 group for spanner backup schedules."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+from googlecloudsdk.calliope import base
+
+
+@base.DefaultUniverseOnly
+@base.ReleaseTracks(
+    base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA, base.ReleaseTrack.GA
+)
+class BackupSchedules(base.Group):
+  """Manage Cloud Spanner backup schedules."""
+
+  pass

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

@@ -0,0 +1,43 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Add IAM policy binding to a Cloud Spanner backup schedule.
+    description: |
+      Add an IAM policy binding to a Cloud Spanner backup schedule. One binding consists of
+      a member, a role, and an optional condition.
+
+    examples: |
+      To add an IAM policy binding for the role of 'roles/editor' for the user
+      'test-user@gmail.com', run:
+
+        $ {command} backup-schedule-id \
+            --instance=instance-id \
+            --database=database-id \
+            --member='user:test-user@gmail.com' \
+            --role='roles/editor'
+
+      To add an IAM policy binding which expires at the end of the year 2025 for the role of
+      'roles/editor' and the user 'test-user@gmail.com', run:
+
+        $ {command} backup-schedule-id \
+            --instance=instance-id \
+            --database=database-id \
+            --member='user:test-user@gmail.com' \
+            --role='roles/editor' \
+            --condition='expression=request.time < timestamp("2026-01-01T00:00:00Z"),title=expires_end_of_2025,description=Expires at midnight on 2025-12-31'
+
+      See https://cloud.google.com/iam/docs/managing-policies for details of
+      policy role and member types.
+
+  request:
+    collection: spanner.projects.instances.databases.backupSchedules
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup schedule to which to add the IAM policy binding.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backupSchedule
+
+  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/backup_schedules/create.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2024 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 schedule create."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+import textwrap
+
+from googlecloudsdk.api_lib.spanner import backup_schedules
+from googlecloudsdk.calliope import arg_parsers
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import resource_args
+
+
+@base.DefaultUniverseOnly
+@base.ReleaseTracks(
+    base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA, base.ReleaseTrack.GA
+)
+class Create(base.CreateCommand):
+  """Create a Cloud Spanner backup schedule."""
+
+  detailed_help = {
+      'EXAMPLES': textwrap.dedent("""\
+        To create a Cloud Spanner backup schedule, run:
+
+          $ {command} backup-schedule-id --instance=instance-id --database=database-id --cron="0 2 * * *" --retention-duration=2w --backup-type=full-backup
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Args is called by calliope to gather arguments for this command.
+
+    Please add arguments in alphabetical order except for no- or a clear- pair
+    for that argument which can follow the argument itself.
+
+    Args:
+      parser: An argparse parser that you can use to add arguments that go on
+        the command line after this command. Positional arguments are allowed.
+    """
+    resource_args.AddBackupScheduleResourceArg(parser, 'to create')
+    backup_type_choices = ['full-backup', 'incremental-backup']
+    parser.add_argument(
+        '--backup-type',
+        metavar='BACKUP_TYPE',
+        required=True,
+        help=("""\
+Type of backups created by this schedule.
+
+Supported backup types:
+
+`full-backup`
+  A full backup stores the entire contents of the database at a given version time.
+
+`incremental-backup`
+  An incremental backup contains only the data that has changed since a previous backup.
+"""),
+        type=arg_parsers.ArgList(
+            choices=backup_type_choices,
+            max_length=1,
+        ),
+    )
+    parser.add_argument(
+        '--cron',
+        required=True,
+        help=(
+            'Textual representation of the crontab. User can customize the'
+            ' backup frequency and the backup version time using the cron'
+            ' expression. The version time must be in UTC timzeone. The backup'
+            ' will contain an externally consistent copy of the database at the'
+            ' version time. Allowed frequencies are 12 hour, 1 day, 1 week and'
+            ' 1 month. Examples of valid cron specifications: * `0 2/12 * * * `'
+            ' : every 12 hours at (2, 14) hours past midnight in UTC. * `0 2,14'
+            ' * * * ` : every 12 hours at (2,14) hours past midnight in UTC. *'
+            ' `0 2 * * * ` : once a day at 2 past midnight in UTC. * `0 2 * * 0'
+            ' ` : once a week every Sunday at 2 past midnight in UTC. * `0 2 8'
+            ' * * ` : once a month on 8th day at 2 past midnight in UTC.'
+        ),
+    )
+    parser.add_argument(
+        '--retention-duration',
+        required=True,
+        help=(
+            'The retention duration of a backup that must be at least 6 hours'
+            ' and at most 366 days. The backup is eligible to be automatically'
+            ' deleted once the retention period has elapsed.'
+        ),
+    )
+    encryption_group_parser = parser.add_argument_group()
+    resource_args.AddCreateBackupEncryptionConfigTypeArg(
+        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.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation.
+
+    Returns:
+      Some value that we want to have printed later.
+    """
+    backup_schedule_ref = args.CONCEPTS.backup_schedule.Parse()
+    encryption_type = resource_args.GetCreateBackupEncryptionConfigType(args)
+    kms_key = resource_args.GetAndValidateKmsKeyName(args)
+    return backup_schedules.Create(
+        backup_schedule_ref, args, encryption_type, kms_key
+    )

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backup_schedules/delete.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2024 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 schedule delete."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+import textwrap
+
+from googlecloudsdk.api_lib.spanner import backup_schedules
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import flags
+from googlecloudsdk.command_lib.spanner import resource_args
+from googlecloudsdk.core.console import console_io
+
+
+@base.DefaultUniverseOnly
+@base.ReleaseTracks(
+    base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA, base.ReleaseTrack.GA
+)
+class Delete(base.DeleteCommand):
+  """Delete a Cloud Spanner backup schedule."""
+
+  detailed_help = {
+      'EXAMPLES': textwrap.dedent("""\
+        To delete a Cloud Spanner backup schedule, run:
+
+          $ {command} backup-schedule-id --instance=instance-id --database=database-id
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Args is called by calliope to gather arguments for this command.
+
+    Please add arguments in alphabetical order except for no- or a clear- pair
+    for that argument which can follow the argument itself.
+
+    Args:
+      parser: An argparse parser that you can use to add arguments that go on
+        the command line after this command. Positional arguments are allowed.
+    """
+    resource_args.AddBackupScheduleResourceArg(parser, 'to delete')
+    parser.display_info.AddCacheUpdater(flags.BackupScheduleCompleter)
+
+  def Run(self, args):
+    """This is what gets called when the user runs this command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation.
+
+    Returns:
+      Some value that we want to have printed later.
+    """
+    backup_schedule_ref = args.CONCEPTS.backup_schedule.Parse()
+    console_io.PromptContinue(
+        message='Delete backup schedule [{0}]. Are you sure?'.format(
+            args.backup_schedule
+        ),
+        cancel_on_no=True,
+    )
+    return backup_schedules.Delete(backup_schedule_ref)

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backup_schedules/describe.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2024 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 schedules describe."""
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+import textwrap
+from googlecloudsdk.api_lib.spanner import backup_schedules
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import resource_args
+
+
+@base.DefaultUniverseOnly
+@base.ReleaseTracks(
+    base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA, base.ReleaseTrack.GA
+)
+class Describe(base.DescribeCommand):
+  """Describe a Cloud Spanner backup schedule."""
+
+  detailed_help = {
+      'EXAMPLES': textwrap.dedent("""\
+        To describe a Cloud Spanner backup schedule, run:
+
+          $ {command} backup-schedule-id --instance=instance-id --database=database-id
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Args is called by calliope to gather arguments for this command.
+
+    Please add arguments in alphabetical order except for no- or a clear- pair
+    for that argument which can follow the argument itself.
+
+    Args:
+      parser: An argparse parser that you can use to add arguments that go on
+        the command line after this command. Positional arguments are allowed.
+    """
+    resource_args.AddBackupScheduleResourceArg(parser, 'to describe')
+
+  def Run(self, args):
+    """This is what gets called when the user runs this command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation.
+
+    Returns:
+      Some value that we want to have printed later.
+    """
+    return backup_schedules.Get(args.CONCEPTS.backup_schedule.Parse())

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backup_schedules/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 schedule.
+    description: |
+      *{command}* displays the IAM policy associated with a Cloud Spanner
+      backup schedule. 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 schedule, run:
+
+        $ {command} backup-schedule-id --instance=instance-id --database=database-id
+
+  request:
+    collection: spanner.projects.instances.databases.backupSchedules
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup schedule for which to display the IAM policy.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backupSchedule

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backup_schedules/list.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2024 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 schedule list."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+import textwrap
+
+from googlecloudsdk.api_lib.spanner import backup_schedules
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import resource_args
+
+
+def _TransformBackupTypeSpec(schedule):
+  """Transforms the backup type spec field to a human readable string."""
+  if 'fullBackupSpec' in schedule:
+    return 'FULL'
+  elif 'incrementalBackupSpec' in schedule:
+    return 'INCREMENTAL'
+  # This should never happen.
+  return 'UNSPECIFIED'
+
+
+@base.DefaultUniverseOnly
+@base.ReleaseTracks(
+    base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA, base.ReleaseTrack.GA
+)
+class List(base.ListCommand):
+  """List Cloud Spanner backup schedules."""
+
+  detailed_help = {
+      'EXAMPLES': textwrap.dedent("""\
+        To list Cloud Spanner backup schedules, run:
+
+          $ {command} --instance=instance-id --database=database-id
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Args is called by calliope to gather arguments for this command.
+
+    Please add arguments in alphabetical order except for no- or a clear- pair
+    for that argument which can follow the argument itself.
+
+    Args:
+      parser: An argparse parser that you can use to add arguments that go on
+        the command line after this command.
+    """
+    resource_args.AddDatabaseResourceArg(
+        parser, 'in which to list schedules', positional=False)
+    parser.display_info.AddFormat("""
+          table(
+            name.basename(),
+            backup_type_spec():label=BACKUP_TYPE,
+            spec.cronSpec.text:label=CRON,
+            retentionDuration,
+            encryptionConfig.encryptionType,
+            encryptionConfig.kmsKeyName,
+            encryptionConfig.kmsKeyNames
+          )
+        """)
+    parser.display_info.AddTransforms({
+        'backup_type_spec': _TransformBackupTypeSpec,
+    })
+
+  def Run(self, args):
+    """This is what gets called when the user runs this command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation.
+
+    Returns:
+      Some value that we want to have printed later.
+    """
+    return backup_schedules.List(args.CONCEPTS.database.Parse())

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

@@ -0,0 +1,43 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Remove IAM policy binding of a Cloud Spanner backup schedule.
+    description: |
+      Remove an IAM policy binding of a Cloud Spanner backup schedule. One binding
+      consists of a member, a role, and an optional condition.
+
+    examples: |
+      To remove an IAM policy binding for the role of 'roles/editor' for the user
+      'test-user@gmail.com', run:
+
+        $ {command} backup-schedule-id \
+            --instance=instance-id \
+            --database=database-id \
+            --member='user:test-user@gmail.com' \
+            --role='roles/editor'
+
+      To remove an IAM policy binding which expires at the end of the year 2025 for the role of
+      'roles/editor' and the user 'test-user@gmail.com', run:
+
+        $ {command} backup-schedule-id \
+            --instance=instance-id \
+            --database=database-id \
+            --member='user:test-user@gmail.com' \
+            --role='roles/editor' \
+            --condition='expression=request.time < timestamp("2026-01-01T00:00:00Z"),title=expires_end_of_2025,description=Expires at midnight on 2025-12-31'
+
+      See https://cloud.google.com/iam/docs/managing-policies for details of
+      policy role and member types.
+
+  request:
+    collection: spanner.projects.instances.databases.backupSchedules
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup schedule to remove the IAM policy binding from.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backupSchedule
+
+  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/backup_schedules/set_iam_policy.yaml

@@ -0,0 +1,22 @@
+- release_tracks: [ALPHA, BETA, GA]
+
+  help_text:
+    brief: Set the IAM policy for a Cloud Spanner backup schedule.
+    description: |
+      Set the IAM policy for a Cloud Spanner backup schedule given a backup schedule 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 Cloud Spanner backup schedule:
+
+        $ {command} backup-schedule-id --instance=instance-id --database=database-id 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.databases.backupSchedules
+
+  arguments:
+    resource:
+      help_text: The Cloud Spanner backup schedule to set the IAM policy for.
+      spec: !REF googlecloudsdk.command_lib.spanner.resources:backupSchedule

gcloud auth application-default login/google-cloud-sdk/lib/surface/spanner/backup_schedules/update.py

@@ -0,0 +1,105 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2024 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 schedule update."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+import textwrap
+
+from googlecloudsdk.api_lib.spanner import backup_schedules
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.spanner import resource_args
+
+
+@base.DefaultUniverseOnly
+@base.ReleaseTracks(
+    base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA, base.ReleaseTrack.GA
+)
+class Create(base.UpdateCommand):
+  """Update a Cloud Spanner backup schedule."""
+
+  detailed_help = {
+      'EXAMPLES': textwrap.dedent("""\
+        To update a Cloud Spanner backup schedule, run:
+
+          $ {command} backup-schedule-id --instance=instance-id --database=database-id --cron="0 2 * * *" --retention-duration=2w --encryption-type=GOOGLE_DEFAULT_ENCRYPTION
+        """),
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Args is called by calliope to gather arguments for this command.
+
+    Please add arguments in alphabetical order except for no- or a clear- pair
+    for that argument which can follow the argument itself.
+
+    Args:
+      parser: An argparse parser that you can use to add arguments that go on
+        the command line after this command. Positional arguments are allowed.
+    """
+    resource_args.AddBackupScheduleResourceArg(parser, 'to create')
+    group_parser = parser.add_argument_group(required=True)
+    group_parser.add_argument(
+        '--cron',
+        required=False,
+        help=(
+            'Textual representation of the crontab. User can customize the'
+            ' backup frequency and the backup version time using the cron'
+            ' expression. The version time must be in UTC timzeone. The backup'
+            ' will contain an externally consistent copy of the database at the'
+            ' version time. Allowed frequencies are 12 hour, 1 day, 1 week and'
+            ' 1 month. Examples of valid cron specifications: * `0 2/12 * * * `'
+            ' : every 12 hours at (2, 14) hours past midnight in UTC. * `0 2,14'
+            ' * * * ` : every 12 hours at (2,14) hours past midnight in UTC. *'
+            ' `0 2 * * * ` : once a day at 2 past midnight in UTC. * `0 2 * * 0'
+            ' ` : once a week every Sunday at 2 past midnight in UTC. * `0 2 8'
+            ' * * ` : once a month on 8th day at 2 past midnight in UTC.'
+        ),
+    )
+    group_parser.add_argument(
+        '--retention-duration',
+        required=False,
+        help=(
+            'The retention duration of a backup that must be at least 6 hours'
+            ' and at most 366 days. The backup is eligible to be automatically'
+            ' deleted once the retention period has elapsed.'
+        ),
+    )
+
+    resource_args.AddCreateBackupEncryptionConfigTypeArg(
+        group_parser
+    )
+    resource_args.AddKmsKeyResourceArg(
+        group_parser, 'to create the Cloud Spanner backup'
+    )
+
+  def Run(self, args):
+    """This is what gets called when the user runs this command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation.
+
+    Returns:
+      Some value that we want to have printed later.
+    """
+    backup_schedule_ref = args.CONCEPTS.backup_schedule.Parse()
+    encryption_type = resource_args.GetCreateBackupEncryptionConfigType(args)
+    kms_key = resource_args.GetAndValidateKmsKeyName(args)
+    return backup_schedules.Update(
+        backup_schedule_ref, args, encryption_type, kms_key
+    )