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

gcloud auth application-default login/google-cloud-sdk/lib/surface/immersive_stream/xr/instances/__init__.py

@@ -0,0 +1,26 @@
+# -*- 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 group for Immersive Stream for XR instance resources."""
+
+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.GA)
+class Instances(base.Group):
+  """Manage Immersive Stream for XR instances."""

gcloud auth application-default login/google-cloud-sdk/lib/surface/immersive_stream/xr/instances/create.py

@@ -0,0 +1,186 @@
+# -*- 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 to create an Immersive Stream for XR service instance."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.immersive_stream.xr import api_util
+from googlecloudsdk.api_lib.immersive_stream.xr import instances
+from googlecloudsdk.api_lib.util import waiter
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.immersive_stream.xr import flags
+from googlecloudsdk.command_lib.immersive_stream.xr import resource_args
+from googlecloudsdk.core import log
+from googlecloudsdk.core import properties
+from googlecloudsdk.core import resources
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA, base.ReleaseTrack.GA)
+class Create(base.CreateCommand):
+  """Create an Immersive Stream for XR service instance."""
+
+  detailed_help = {
+      'DESCRIPTION': 'Create an Immersive Stream for XR service instance.',
+      'EXAMPLES': """
+          To create a service instance called `my-instance` serving content
+          `my-content` with version `my-version` that has availablilty for 2
+          concurent sessions in us-west1 region and 3 concurrent sessions in
+          us-east4 region, run:
+
+            $ {command} my-instance --content=my-content --version=my-version --add-region=region=us-west1,capacity=2 --add-region=region=us-east4,capacity=3
+
+          Optionally, a fallback url may be specified. Users will be redirected
+          to this fallback url when the service instance is unable to provide
+          the streaming experience.
+          To create a service instance called `my-instance` serving content
+          `my-content` with version `my-version` that has availablilty for 2
+          concurent sessions in us-west1 and uses fallback url
+          `https://www.google.com` run:
+
+            $ {command} my-instance --content=my-content --version=my-version --add-region=region=us-west1,capacity=2 --fallback-url="https://www.google.com"
+
+           By default, the instance is created with mode=ar, which supports both
+           3D and AR experiences. Instances can also be configured to use
+           3D-only mode. This configuration cannot be updated later.
+           To use 3D-only mode, include:
+
+            --mode=3d
+
+           By default, the instance is created with gpu-class=t4. This uses the
+           NVIDIA T4 GPU for the instance. Instances can also be configured to
+           use NVIDIA L4 GPUs at creation. Note that only certain regions are
+           available for L4, and only 3D-only mode is supported. This
+           configuration cannot be updated later.
+           To use NVIDIA L4 GPU for the instance, include:
+
+            --gpu-class=l4
+      """,
+  }
+
+  @staticmethod
+  def __ValidateArgs(args):
+    return flags.ValidateRegionConfigArgs(args.add_region, 'add')
+
+  @staticmethod
+  def Args(parser):
+    resource_args.AddContentResourceArg(
+        parser, verb='served by the instance', positional=False
+    )
+    parser.add_argument('instance', help='Name of the instance to be created')
+    parser.add_argument(
+        '--version',
+        required=True,
+        help='Build version tag of the content served by this instance',
+    )
+    parser.add_argument(
+        '--fallback-url',
+        help=(
+            'Fallback url to redirect users to when this service instance is'
+            ' unable to provide the streaming experience'
+        ),
+        required=False,
+    )
+    parser.add_argument(
+        '--mode',
+        help='The rendering mode that is supported by this service instance',
+        required=False,
+    )
+    parser.add_argument(
+        '--gpu-class',
+        help='The class of GPU that is used by this service instance',
+        required=False,
+    )
+    flags.AddRegionConfigArg('--add-region', parser)
+    base.ASYNC_FLAG.AddToParser(parser)
+
+  def Run(self, args):
+    if not Create.__ValidateArgs(args):
+      return
+
+    region_configs = args.add_region
+    content_ref = args.CONCEPTS.content.Parse()
+    content_name = content_ref.RelativeName()
+    location = content_ref.locationsId
+    instance_name = args.instance
+    version = args.version
+    fallback_url = args.fallback_url
+    mode = args.mode
+    gpu_class = args.gpu_class
+
+    if fallback_url and not flags.ValidateUrl(fallback_url):
+      return
+
+    if mode and not flags.ValidateMode(mode):
+      return
+
+    if gpu_class and not flags.ValidateGpuClass(gpu_class, mode):
+      return
+
+    client = api_util.GetClient(self.ReleaseTrack())
+    target_location_configs = instances.GenerateTargetLocationConfigs(
+        self.ReleaseTrack(),
+        add_region_configs=region_configs,
+        update_region_configs=None,
+        remove_regions=None,
+        current_instance=None,
+    )
+    result_operation = instances.Create(
+        self.ReleaseTrack(),
+        instance_name,
+        content_name,
+        location,
+        version,
+        target_location_configs,
+        fallback_url,
+        mode,
+        gpu_class,
+    )
+    log.status.Print('Create request issued for: [{}]'.format(instance_name))
+    if args.async_:
+      log.status.Print(
+          'Check operation [{}] for status.\n'.format(result_operation.name)
+      )
+      return result_operation
+
+    operation_resource = resources.REGISTRY.Parse(
+        result_operation.name,
+        api_version=api_util.GetApiVersion(self.ReleaseTrack()),
+        collection='stream.projects.locations.operations',
+    )
+    created_instance = waiter.WaitFor(
+        waiter.CloudOperationPoller(
+            client.projects_locations_streamInstances,
+            client.projects_locations_operations,
+        ),
+        operation_resource,
+        'Waiting for operation [{}] to complete'.format(result_operation.name),
+    )
+
+    instance_resource = resources.REGISTRY.Parse(
+        None,
+        collection='stream.projects.locations.streamInstances',
+        api_version=api_util.GetApiVersion(self.ReleaseTrack()),
+        params={
+            'projectsId': properties.VALUES.core.project.Get(required=True),
+            'locationsId': 'global',
+            'streamInstancesId': instance_name,
+        },
+    )
+
+    log.CreatedResource(instance_resource)
+
+    return created_instance

gcloud auth application-default login/google-cloud-sdk/lib/surface/immersive_stream/xr/instances/delete.yaml

@@ -0,0 +1,25 @@
+- release_tracks: [ALPHA, GA]
+
+  help_text:
+    brief: Delete an Immersive Stream for XR service instance.
+    description: |
+      Delete an Immersive Stream for XR service instance.
+    examples: |
+      To delete a service instance called `my-instance`, run:
+
+        $ {command} my-instance
+
+  request:
+    collection: stream.projects.locations.streamInstances
+    ALPHA:
+      api_version: v1alpha1
+    GA:
+      api_version: v1
+
+  arguments:
+    resource:
+      help_text: Immersive Stream for XR service instance to delete.
+      spec: !REF googlecloudsdk.command_lib.immersive_stream.xr.resources:instance
+
+  async:
+    collection: stream.projects.locations.operations

gcloud auth application-default login/google-cloud-sdk/lib/surface/immersive_stream/xr/instances/describe.yaml

@@ -0,0 +1,25 @@
+- release_tracks: [ALPHA, GA]
+
+  help_text:
+    brief: Describe a specific Immersive Stream for XR service instance.
+    description: |
+      Describe a specific Immersive Stream for XR service instance.
+    examples: |
+      To describe the service instance, run:
+
+        $ {command} my-instance
+
+  request:
+    collection: stream.projects.locations.streamInstances
+    ALPHA:
+      api_version: v1alpha1
+    GA:
+      api_version: v1
+
+  response:
+    id_field: name
+
+  arguments:
+    resource:
+      help_text: The name of the service instance you want to describe.
+      spec: !REF googlecloudsdk.command_lib.immersive_stream.xr.resources:instance

gcloud auth application-default login/google-cloud-sdk/lib/surface/immersive_stream/xr/instances/list.yaml

@@ -0,0 +1,25 @@
+- release_tracks: [ALPHA, GA]
+
+  help_text:
+    brief: List Immersive Stream for XR service instances.
+    description: |
+      List Immersive Stream for XR service instances.
+    examples: |
+      To list Immersive Stream for XR service instances, run:
+
+        $ {command}
+
+  request:
+    collection: stream.projects.locations.streamInstances
+    ALPHA:
+      api_version: v1alpha1
+    GA:
+      api_version: v1
+
+  response:
+    id_field: name
+
+  arguments:
+    resource:
+      help_text: Location to list all Immersive Stream for XR service instances, defaults to global.
+      spec: !REF googlecloudsdk.command_lib.immersive_stream.xr.resources:location

gcloud auth application-default login/google-cloud-sdk/lib/surface/immersive_stream/xr/instances/update.py

@@ -0,0 +1,200 @@
+# -*- 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 to update an Immersive Stream for XR service instance."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.immersive_stream.xr import api_util
+from googlecloudsdk.api_lib.immersive_stream.xr import instances
+from googlecloudsdk.api_lib.util import waiter
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.immersive_stream.xr import flags
+from googlecloudsdk.command_lib.immersive_stream.xr import resource_args
+from googlecloudsdk.core import log
+from googlecloudsdk.core import properties
+from googlecloudsdk.core import resources
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA, base.ReleaseTrack.GA)
+class Update(base.Command):
+  """Update an Immersive Stream for XR service instance."""
+
+  detailed_help = {
+      'DESCRIPTION': ("""
+          Update an Immersive Stream for XR service instance.
+          This command can be used to update one of the following:
+            - the capacity for an existing region of the service instance
+            - the content build version served by the instance
+            - the fallback url to redirect users to when the service instance is
+              unable to provide the streaming experience
+
+          If updating the capacity, only one region may be updated for each
+          command execution, and the new capacity may not be 0 or exceed the
+          quota limit.
+      """),
+      'EXAMPLES': ("""
+          To update the service instance `my-instance` to have capacity 2 for an
+          existing region us-west1, run:
+
+            $ {command} my-instance --update-region=region=us-west1,capacity=2
+
+          To update the service instance `my-instance` to have capacity 1 for a
+          new region us-east4, run:
+
+            $ {command} my-instance --add-region=region=us-east4,capacity=1
+
+          To update the service instance `my-instance` to remove the existing
+          region us-east4, run:
+
+            $ {command} my-instance --remove-region=us-east4
+
+          To update the service instance `my-instance` to serve content version
+          `my-version`, run:
+
+            $ {command} my-instance --version=my-version
+
+          To update the service instance `my-instance` to use fallback url
+          `https://www.google.com`, run:
+
+            $ {command} my-instance --fallback-url="https://www.google.com"
+      """)
+  }
+
+  @staticmethod
+  def __ValidateArgs(args):
+    if args.add_region:
+      return flags.ValidateRegionConfigArgs(args.add_region, 'add')
+
+    if args.remove_region:
+      if len(set(args.remove_region)) < len(args.remove_region):
+        log.error('Duplicate regions in --remove-region arguments.')
+        return False
+
+    if args.update_region:
+      return flags.ValidateRegionConfigArgs(args.update_region, 'update')
+
+    return True
+
+  @staticmethod
+  def Args(parser):
+    resource_args.AddInstanceResourceArg(parser, verb='to update')
+    group = parser.add_group(mutex=True, required=True, help='Update options')
+    group.add_argument(
+        '--version',
+        help='Build version tag of the content served by this instance')
+    group.add_argument(
+        '--fallback-url',
+        help='Fallback url to redirect users to when this service instance is unable to provide the streaming experience'
+    )
+    flags.AddRegionConfigArg(
+        '--add-region', group, repeatable=False, required=False)
+    flags.AddRegionConfigArg(
+        '--update-region', group, repeatable=False, required=False)
+    group.add_argument(
+        '--remove-region', help='Region to remove', action='append')
+    base.ASYNC_FLAG.AddToParser(parser)
+
+  def Run(self, args):
+    if not Update.__ValidateArgs(args):
+      return
+
+    version = args.version
+    fallback_url = args.fallback_url
+    add_region_configs = args.add_region
+    remove_regions = args.remove_region
+    update_region_configs = args.update_region
+    instance_name = args.instance
+
+    instance_ref = resources.REGISTRY.Parse(
+        None,
+        collection='stream.projects.locations.streamInstances',
+        api_version=api_util.GetApiVersion(self.ReleaseTrack()),
+        params={
+            'projectsId': properties.VALUES.core.project.Get(required=True),
+            'locationsId': 'global',
+            'streamInstancesId': instance_name
+        })
+
+    if version:
+      result_operation = instances.UpdateContentBuildVersion(
+          self.ReleaseTrack(), instance_ref, version)
+    elif fallback_url:
+      if not flags.ValidateUrl(fallback_url):
+        return
+      result_operation = instances.UpdateFallbackUrl(self.ReleaseTrack(),
+                                                     instance_ref, fallback_url)
+    else:
+      # We limit to one update per call.
+      if add_region_configs:
+        if len(add_region_configs) > 1:
+          log.error(('Only one region may be added at a time. Please try again '
+                     'with only one --add-region argument.'))
+          return
+      elif remove_regions:
+        if len(remove_regions) > 1:
+          log.error(('Only one region may be removed at a time. Please try '
+                     'again with only one --remove-region argument.'))
+          return
+      elif update_region_configs:
+        if len(update_region_configs) > 1:
+          log.error(('Only one region may be updated at a time. Please try '
+                     'again with only one --update-region argument.'))
+          return
+
+      current_instance = instances.Get(self.ReleaseTrack(),
+                                       instance_ref.RelativeName())
+      target_location_configs = instances.GenerateTargetLocationConfigs(
+          self.ReleaseTrack(),
+          add_region_configs=add_region_configs,
+          update_region_configs=update_region_configs,
+          remove_regions=remove_regions,
+          current_instance=current_instance)
+      if target_location_configs is None:
+        return
+      result_operation = instances.UpdateLocationConfigs(
+          self.ReleaseTrack(), instance_ref, target_location_configs)
+
+    client = api_util.GetClient(self.ReleaseTrack())
+
+    log.status.Print('Update request issued for: [{}]'.format(instance_name))
+    if args.async_:
+      log.status.Print('Check operation [{}] for status.\n'.format(
+          result_operation.name))
+      return result_operation
+
+    operation_resource = resources.REGISTRY.Parse(
+        result_operation.name,
+        collection='stream.projects.locations.operations',
+        api_version=api_util.GetApiVersion(self.ReleaseTrack()))
+    updated_instance = waiter.WaitFor(
+        waiter.CloudOperationPoller(client.projects_locations_streamInstances,
+                                    client.projects_locations_operations),
+        operation_resource,
+        'Waiting for operation [{}] to complete'.format(result_operation.name))
+
+    instance_resource = resources.REGISTRY.Parse(
+        None,
+        collection='stream.projects.locations.streamInstances',
+        api_version=api_util.GetApiVersion(self.ReleaseTrack()),
+        params={
+            'projectsId': properties.VALUES.core.project.Get(required=True),
+            'locationsId': 'global',
+            'streamInstancesId': instance_name
+        })
+
+    log.UpdatedResource(instance_resource)
+    return updated_instance