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

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/__init__.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2018 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 Cloud Monitoring notification channels."""
+
+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)
+class Channels(base.Group):
+  """Manage Cloud Monitoring notification channels."""
+
+  detailed_help = {
+      'DESCRIPTION':
+          """\
+          Manage Monitoring notification channels.
+
+          More information can be found here:
+          https://cloud.google.com/monitoring/api/v3/
+          https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.notificationChannels
+          https://cloud.google.com/monitoring/alerts/using-channels-api
+      """
+  }

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/config/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2021 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 managing Monitoring notification channel configurations."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA)
+class Config(base.Group):
+  """Manage Monitoring notification channel configurations."""

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/config/export.yaml

@@ -0,0 +1,38 @@
+release_tracks: [ALPHA]
+command_type: CONFIG_EXPORT
+help_text:
+  brief: Export the configuration for a Monitoring notification channel.
+  description: |
+    *{command}* exports the configuration for a Monitoring notification channel.
+
+    Notification channel configurations can be exported in
+    Kubernetes Resource Model (krm) or Terraform HCL formats. The
+    default format is `krm`.
+
+    Specifying `--all` allows you to export the configurations for all
+    notification channels within the project.
+
+    Specifying `--path` allows you to export the configuration(s) to
+    a local directory.
+  examples: |
+    To export the configuration for a notification channel, run:
+
+      $ {command} my-notification-channel
+
+    To export the configuration for a notification channel to a file, run:
+
+      $ {command} my-notification-channel --path=/path/to/dir/
+
+    To export the configuration for a notification channel in Terraform
+    HCL format, run:
+
+      $ {command} my-notification-channel --resource-format=terraform
+
+    To export the configurations for all notification channels within a
+    project, run:
+
+      $ {command} --all
+arguments:
+  resource:
+    help_text: Notification channel to export the configuration for.
+    spec: !REF googlecloudsdk.command_lib.monitoring.resources:notification_channel

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/create.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2018 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.
+"""`gcloud monitoring channels create` command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.monitoring import channels
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.monitoring import flags
+from googlecloudsdk.command_lib.monitoring import util
+from googlecloudsdk.command_lib.projects import util as projects_util
+from googlecloudsdk.core import log
+from googlecloudsdk.core import properties
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA)
+class Create(base.CreateCommand):
+  """Create a new notification channel."""
+
+  detailed_help = {
+      'DESCRIPTION':
+          """\
+          Creates a new notification channel. A channel can be specified as
+          JSON/YAML passed in as a string through the `--channel-content` flag
+          or as a file through the `--channel-content-from-file` flag.
+          A basic channel can also be specified through command line flags. If
+          a channel is specified through `--channel-content` or
+          `--channel-content-from-file`, and additional flags are supplied, the
+          flags will override the given channel's settings.
+
+          For information about the JSON/YAML format of a notification channel:
+          https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.notificationChannels
+
+          Additional documentation can for this operation can be found at:
+          https://cloud.google.com/monitoring/alerts/using-channels-api
+
+          ## EXAMPLES
+          The following commands setup both email and SMS notification channels for the team lead. Note
+          that the display name and description focus on the purpose/semantics of the channel rather
+          than its destination. This is a best-practice that facilitates swapping/updating notification
+          channels in-place (such as when users change teams, projects, roles, companies, etc.) with
+          minimal impact to the alerting policies that reference the existing channels. It is also
+          a best practice to supply at least two channels of different types for a given person.
+
+            $ {command} \
+              --display-name="Foo Team Lead (Primary)" \
+              --description="Primary contact method for the Foo team lead" \
+              --type=email \
+              --user-labels=team=foo,role=lead,ord=1 \
+              --channel-labels=email_address=user@somedomain.tld
+
+            $ {command} \
+              --display-name="Foo Team Lead (Secondary)" \
+              --description="Secondary contact method for the Foo team lead" \
+              --type=sms \
+              --user-labels=team=foo,role=lead,ord=2 \
+              --channel-labels=number=123-456-7890
+       """
+  }
+
+  @staticmethod
+  def Args(parser):
+    flags.AddMessageFlags(parser, 'channel-content')
+    flags.AddNotificationChannelSettingFlags(parser)
+
+  def Run(self, args):
+    client = channels.NotificationChannelsClient()
+    messages = client.messages
+
+    channel = util.GetNotificationChannelFromArgs(args, messages)
+
+    if args.user_labels:
+      channel.userLabels = util.ParseCreateLabels(
+          args.user_labels, messages.NotificationChannel.UserLabelsValue)
+    if args.channel_labels:
+      channel.labels = util.ParseCreateLabels(
+          args.channel_labels, messages.NotificationChannel.LabelsValue)
+
+    project_ref = (
+        projects_util.ParseProject(properties.VALUES.core.project.Get()))
+
+    result = client.Create(project_ref, channel)
+    log.CreatedResource(result.name, 'notification channel')
+    return result

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/delete.yaml

@@ -0,0 +1,31 @@
+- release_tracks: [ALPHA, BETA]
+  help_text:
+    brief: Delete a notification channel.
+    description: |
+      Delete a notification channel.
+
+      ## EXAMPLES
+      The following command will delete channel `projects/12345/notificationChannels/67890`, but
+      only if the channel is not actively referenced by existing alerting policies:
+
+        $ {command} "projects/12345/notificationChannels/67890"
+
+      The following command will delete channel `projects/12345/notificationChannels/67890`, even
+      if the channel is still actively referenced by alerting policies; if an existing policy
+      references the channel, it will be modified as a side-effect to remove the channel.
+
+        $ {command} "projects/12345/notificationChannels/67890" --force
+
+  request:
+    collection: monitoring.projects.notificationChannels
+
+  arguments:
+    resource:
+      help_text: The notification channel to delete.
+      spec: !REF googlecloudsdk.command_lib.monitoring.resources:notification_channel
+    params:
+    - arg_name: force
+      api_field: force
+      action: store_true
+      help_text: If true, the notification channel will be deleted regardless of its
+        use in alerting policies (the policies will be updated to remove the channel).

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/describe.yaml

@@ -0,0 +1,21 @@
+- release_tracks: [ALPHA, BETA]
+  help_text:
+    brief: Describe a notification channel.
+    description: |
+      Describe a notification channel.
+
+      This retrieves the details about a channel by its programmatic name.
+
+      ## EXAMPLES
+      The following command prints out the JSON format of the configuration for the
+      `NotificationChannel` with the name `projects/12345/notificationChannels/67890`:
+
+        $ {command} "projects/12345/notificationChannels/67890" --format=json
+
+  request:
+    collection: monitoring.projects.notificationChannels
+
+  arguments:
+    resource:
+      help_text: The notification channel to describe.
+      spec: !REF googlecloudsdk.command_lib.monitoring.resources:notification_channel

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/list.yaml

@@ -0,0 +1,40 @@
+- release_tracks: [ALPHA, BETA]
+  help_text:
+    brief: List notification channels.
+    description: |
+      List notification channels.
+
+      This operation supports both --filter and --sort-by arguments.
+
+      ## EXAMPLES
+      The following command lists all notification channels where the user label "team" has
+      value "foo" and where the notification channel is of an "email" type:
+
+        $ {command} --filter='type="email" AND userLabels.team="foo"'
+
+      The following command lists all of the email addresses alphabetically:
+
+        $ {command} \
+          --filter='type="email"' \
+          --sort-by=labels.email_address \
+          --format="value(labels.email_address)"
+
+  request:
+    collection: monitoring.projects.notificationChannels
+    modify_request_hooks:
+    - googlecloudsdk.command_lib.monitoring.hooks:ModifyListNotificationChannelsRequest
+    - googlecloudsdk.command_lib.monitoring.hooks:AddOrderByToListRequest
+
+  response:
+    id_field: name
+
+  arguments:
+    resource:
+      help_text: The project to list notification channels from.
+      spec: !REF googlecloudsdk.command_lib.monitoring.resources:project
+    params:
+    - arg_name: type
+      help_text: List only notification channels of this type.
+
+  output:
+    format: yaml

gcloud auth application-default login/google-cloud-sdk/lib/surface/monitoring/channels/update.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2018 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.
+"""`gcloud monitoring channels update` command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.monitoring import channels
+from googlecloudsdk.calliope import base
+from googlecloudsdk.command_lib.monitoring import flags
+from googlecloudsdk.command_lib.monitoring import resource_args
+from googlecloudsdk.command_lib.monitoring import util
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA)
+class Create(base.CreateCommand):
+  """Update a notification channel."""
+
+  detailed_help = {
+      'DESCRIPTION':
+          """\
+          Updates a notification channel.
+
+          If `--channel-content` or `--channel-content-from-file` are specified:
+
+            * --fields can be specified; only the specified fields will be
+              updated.
+            * Alternatively, the channel will be replaced with the provided
+              channel. The channel can be modified further using the flags
+              from the notification channel settings group below.
+
+          Otherwise, the channel will be updated with the values specified in
+          the flags from the notification channel settings group.
+
+          For information about the JSON/YAML format of a notification channel:
+          https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.notificationChannels
+
+          *Note:* When specifying the Channel as a YAML/JSON, the use of
+          `channelLabels` as an alternative name for `labels` is supported.
+
+          ## EXAMPLES
+          The following command updates an existing email notification channel to point from
+          its original email address to "newaddress@newdomain.tld":
+
+            $ {command} "projects/12345/notificationChannels/67890" \
+              --update-channel-labels=email_address=newaddress@newdomain.tld
+       """
+  }
+
+  @staticmethod
+  def Args(parser):
+    channel_arg = resource_args.CreateNotificationChannelResourceArg(
+        'channel', 'to update')
+    resource_args.AddResourceArgs(parser, [channel_arg])
+    flags.AddMessageFlags(parser, 'channel-content')
+    flags.AddFieldsFlagsWithMutuallyExclusiveSettings(
+        parser,
+        fields_help='The list of fields to update. Must specify '
+                    '`--channel-content` or `--channel-content-from-file` '
+                    'if using this flag.',
+        add_settings_func=flags.AddNotificationChannelSettingFlags,
+        update=True)
+
+  def Run(self, args):
+    util.ValidateUpdateArgsSpecified(
+        args,
+        ['channel_content', 'channel_content_from_file', 'display_name',
+         'enabled', 'type', 'description', 'fields', 'update_user_labels',
+         'remove_user_labels', 'clear_user_labels', 'update_channel_labels',
+         'remove_channel_labels', 'clear_channel_labels'],
+        'channel')
+    flags.ValidateNotificationChannelUpdateArgs(args)
+
+    client = channels.NotificationChannelsClient()
+    messages = client.messages
+
+    channel_ref = args.CONCEPTS.channel.Parse()
+
+    passed_yaml_channel = False
+    channel_str = args.channel_content or args.channel_content_from_file
+    if channel_str:
+      passed_yaml_channel = True
+      channel = util.MessageFromString(
+          channel_str, messages.NotificationChannel, 'NotificationChannel',
+          field_remappings=util.CHANNELS_FIELD_REMAPPINGS)
+    else:
+      channel = client.Get(channel_ref)
+
+    if not args.fields:
+      enabled = args.enabled if args.IsSpecified('enabled') else None
+
+      fields = []
+      util.ModifyNotificationChannel(channel,
+                                     channel_type=args.type,
+                                     display_name=args.display_name,
+                                     description=args.description,
+                                     enabled=enabled,
+                                     field_masks=fields)
+
+      new_user_labels = util.ProcessUpdateLabels(
+          args, 'user_labels', messages.NotificationChannel.UserLabelsValue,
+          channel.userLabels)
+      new_channel_labels = util.ProcessUpdateLabels(
+          args, 'channel_labels', messages.NotificationChannel.LabelsValue,
+          channel.labels)
+      # TODO(b/73120276): Use field masks per key for label updates.
+      if new_user_labels:
+        channel.userLabels = new_user_labels
+        fields.append('user_labels')
+      if new_channel_labels:
+        channel.labels = new_channel_labels
+        fields.append('labels')
+
+      # For more robust concurrent updates, use update masks if we're not
+      # trying to replace the channel using --channel-content or
+      # --channel-content-from-file.
+      fields = None if passed_yaml_channel else ','.join(sorted(fields))
+    else:
+      fields = ','.join(args.fields)
+
+    return client.Update(channel_ref, channel, fields)