Update the description of mirroring resources. (#13255)

duvni · web-flow · commit 50b47b64894f · 2025-03-04T22:51:57.000Z
diff --git a/mmv1/products/networksecurity/MirroringDeployment.yaml b/mmv1/products/networksecurity/MirroringDeployment.yaml
@@ -13,7 +13,11 @@
 
 ---
 name: 'MirroringDeployment'
-description: MirroringDeployment represents the collectors within a Zone and is associated with a deployment group.
+description: |-
+  A deployment represents a zonal mirroring backend ready to accept
+  GENEVE-encapsulated replica traffic, e.g. a zonal instance group fronted by
+  an internal passthrough load balancer. Deployments are always part of a
+  global deployment group which represents a global mirroring service.
 min_version: 'beta'
 references:
   guides:
@@ -55,65 +59,88 @@ examples:
 parameters:
   - name: 'location'
     type: String
-    description: 'Resource ID segment making up resource `name`. It identifies the resource
-    within its parent collection as described in https://google.aip.dev/122. See documentation
-    for resource type `networksecurity.googleapis.com/MirroringDeployment`. '
+    description: |-
+      The cloud location of the deployment, e.g. `us-central1-a` or `asia-south1-b`.
     min_version: 'beta'
     url_param_only: true
     required: true
     immutable: true
   - name: 'mirroringDeploymentId'
     type: String
-    description: "Required. Id of the requesting object\nIf auto-generating Id server-side,
-    remove this field and\nmirroring_deployment_id from the method_signature of Create
-    RPC "
+    description: |-
+      The ID to use for the new deployment, which will become the final
+      component of the deployment's resource name.
     min_version: 'beta'
     url_param_only: true
     required: true
     immutable: true
 properties:
   - name: 'name'
     type: String
-    description: 'Immutable. Identifier. The name of the MirroringDeployment. '
+    description: |-
+      The resource name of this deployment, for example:
+      `projects/123456789/locations/us-central1-a/mirroringDeployments/my-dep`.
+      See https://google.aip.dev/122 for more details.
     min_version: 'beta'
     immutable: true
     output: true
   - name: 'createTime'
     type: String
-    description: 'Output only. [Output only] Create time stamp '
+    description: |-
+      The timestamp when the resource was created.
+      See https://google.aip.dev/148#timestamps.
     min_version: 'beta'
     output: true
   - name: 'updateTime'
     type: String
-    description: 'Output only. [Output only] Update time stamp '
+    description: |-
+      The timestamp when the resource was most recently updated.
+      See https://google.aip.dev/148#timestamps.
     min_version: 'beta'
     output: true
   - name: 'labels'
     type: KeyValueLabels
-    description: 'Optional. Labels as key value pairs '
+    description: |-
+      Labels are key/value pairs that help to organize and filter resources.
     min_version: 'beta'
   - name: 'forwardingRule'
     type: String
-    description: "Required. Immutable. The regional load balancer which the mirrored
-    traffic should be forwarded\nto. Format is:\nprojects/{project}/regions/{region}/forwardingRules/{forwardingRule} "
+    description: |-
+      The regional forwarding rule that fronts the mirroring collectors, for
+      example: `projects/123456789/regions/us-central1/forwardingRules/my-rule`.
+      See https://google.aip.dev/124.
     min_version: 'beta'
     required: true
     immutable: true
   - name: 'mirroringDeploymentGroup'
     type: String
-    description: "Required. Immutable. The Mirroring Deployment Group that this resource
-    is part of. Format is:\n`projects/{project}/locations/global/mirroringDeploymentGroups/{mirroringDeploymentGroup}` "
+    description: |-
+      The deployment group that this deployment is a part of, for example:
+      `projects/123456789/locations/global/mirroringDeploymentGroups/my-dg`.
+      See https://google.aip.dev/124.
     min_version: 'beta'
     required: true
     immutable: true
   - name: 'state'
     type: String
-    description: "Output only. Current state of the deployment. \n Possible values:\n
-    STATE_UNSPECIFIED\nACTIVE\nCREATING\nDELETING\nOUT_OF_SYNC\nDELETE_FAILED"
+    description: |-
+      The current state of the deployment.
+      See https://google.aip.dev/216.
+      Possible values:
+      STATE_UNSPECIFIED
+      ACTIVE
+      CREATING
+      DELETING
+      OUT_OF_SYNC
+      DELETE_FAILED
     min_version: 'beta'
     output: true
   - name: 'reconciling'
     type: Boolean
-    description: "Output only. Whether reconciling is in progress, recommended per\nhttps://google.aip.dev/128. "
+    description: |-
+      The current state of the resource does not match the user's intended state,
+      and the system is working to reconcile them. This part of the normal
+      operation (e.g. linking a new association to the parent group).
+      See https://google.aip.dev/128.
     min_version: 'beta'
     output: true
diff --git a/mmv1/products/networksecurity/MirroringDeploymentGroup.yaml b/mmv1/products/networksecurity/MirroringDeploymentGroup.yaml
@@ -13,7 +13,10 @@
 
 ---
 name: 'MirroringDeploymentGroup'
-description: A Deployment Group represents the collector deployments across different zones within an organization.
+description: |-
+  A deployment group aggregates many zonal mirroring backends (deployments)
+  into a single global mirroring service. Consumers can connect this service
+  using an endpoint group.
 min_version: 'beta'
 references:
   guides:
@@ -51,72 +54,94 @@ examples:
 parameters:
   - name: 'location'
     type: String
-    description: 'Resource ID segment making up resource `name`. It identifies the resource
-    within its parent collection as described in https://google.aip.dev/122. See documentation
-    for resource type `networksecurity.googleapis.com/MirroringDeploymentGroup`. '
+    description: |-
+      The cloud location of the deployment group, currently restricted to `global`.
     min_version: 'beta'
     url_param_only: true
     required: true
     immutable: true
   - name: 'mirroringDeploymentGroupId'
     type: String
-    description: "Required. Id of the requesting object\nIf auto-generating Id server-side,
-    remove this field and\nmirroring_deployment_group_id from the method_signature
-    of Create RPC "
+    description: |-
+      The ID to use for the new deployment group, which will become the final
+      component of the deployment group's resource name.
     min_version: 'beta'
     url_param_only: true
     required: true
     immutable: true
 properties:
   - name: 'name'
     type: String
-    description: 'Immutable. Identifier. Then name of the MirroringDeploymentGroup. '
+    description: |-
+      The resource name of this deployment group, for example:
+      `projects/123456789/locations/global/mirroringDeploymentGroups/my-dg`.
+      See https://google.aip.dev/122 for more details.
     min_version: 'beta'
     immutable: true
     output: true
   - name: 'createTime'
     type: String
-    description: 'Output only. [Output only] Create time stamp '
+    description: |-
+      The timestamp when the resource was created.
+      See https://google.aip.dev/148#timestamps.
     min_version: 'beta'
     output: true
   - name: 'updateTime'
     type: String
-    description: 'Output only. [Output only] Update time stamp '
+    description: |-
+      The timestamp when the resource was most recently updated.
+      See https://google.aip.dev/148#timestamps.
     min_version: 'beta'
     output: true
   - name: 'labels'
     type: KeyValueLabels
-    description: 'Optional. Labels as key value pairs '
+    description: |-
+      Labels are key/value pairs that help to organize and filter resources.
     min_version: 'beta'
   - name: 'network'
     type: String
-    description: "Required. Immutable. The network that is being used for the deployment.
-    Format is:\nprojects/{project}/global/networks/{network}. "
+    description: |-
+      The network that will be used for all child deployments, for example:
+      `projects/{project}/global/networks/{network}`.
+      See https://google.aip.dev/124.
     min_version: 'beta'
     required: true
     immutable: true
   - name: 'connectedEndpointGroups'
     type: Array
-    description: 'Output only. The list of Mirroring Endpoint Groups that are connected
-      to this resource. '
+    description: |-
+      The list of endpoint groups that are connected to this resource.
     min_version: 'beta'
     output: true
     item_type:
       type: NestedObject
       properties:
         - name: 'name'
           type: String
-          description: 'Output only. A connected mirroring endpoint group. '
+          description: |-
+            The connected endpoint group's resource name, for example:
+            `projects/123456789/locations/global/mirroringEndpointGroups/my-eg`.
+            See https://google.aip.dev/124.
           min_version: 'beta'
           output: true
   - name: 'state'
     type: String
-    description: "Output only. Current state of the deployment group. \n Possible values:\n
-    STATE_UNSPECIFIED\nACTIVE\nCREATING\nDELETING"
+    description: |-
+      The current state of the deployment group.
+      See https://google.aip.dev/216.
+      Possible values:
+      STATE_UNSPECIFIED
+      ACTIVE
+      CREATING
+      DELETING
     min_version: 'beta'
     output: true
   - name: 'reconciling'
     type: Boolean
-    description: "Output only. Whether reconciling is in progress, recommended per\nhttps://google.aip.dev/128. "
+    description: |-
+      The current state of the resource does not match the user's intended state,
+      and the system is working to reconcile them. This is part of the normal
+      operation (e.g. adding a new deployment to the group)
+      See https://google.aip.dev/128.
     min_version: 'beta'
     output: true
diff --git a/mmv1/products/networksecurity/MirroringEndpointGroup.yaml b/mmv1/products/networksecurity/MirroringEndpointGroup.yaml
@@ -13,7 +13,12 @@
 
 ---
 name: 'MirroringEndpointGroup'
-description: A mirroring endpoint group is a global resource in the consumer account representing the producer’s deployment group.
+description: |-
+  An endpoint group is a consumer frontend for a deployment group (backend).
+  In order to configure mirroring for a network, consumers must create:
+  - An association between their network and the endpoint group.
+  - A security profile that points to the endpoint group.
+  - A mirroring rule that references the security profile (group).
 min_version: 'beta'
 references:
   guides:
@@ -51,58 +56,80 @@ examples:
 parameters:
   - name: 'location'
     type: String
-    description: 'Resource ID segment making up resource `name`. It identifies the resource
-    within its parent collection as described in https://google.aip.dev/122. See documentation
-    for resource type `networksecurity.googleapis.com/MirroringEndpointGroup`. '
+    description: |-
+      The cloud location of the endpoint group, currently restricted to `global`.
     min_version: 'beta'
     url_param_only: true
     required: true
     immutable: true
   - name: 'mirroringEndpointGroupId'
     type: String
-    description: "Required. Id of the requesting object\nIf auto-generating Id server-side,
-    remove this field and\nmirroring_endpoint_group_id from the method_signature of
-    Create RPC "
+    description: |-
+      The ID to use for the endpoint group, which will become the final component
+      of the endpoint group's resource name.
     min_version: 'beta'
     url_param_only: true
     required: true
     immutable: true
 properties:
   - name: 'name'
     type: String
-    description: 'Immutable. Identifier. The name of the MirroringEndpointGroup. '
+    description: |-
+      The resource name of this endpoint group, for example:
+      `projects/123456789/locations/global/mirroringEndpointGroups/my-eg`.
+      See https://google.aip.dev/122 for more details.
     min_version: 'beta'
     immutable: true
     output: true
   - name: 'createTime'
     type: String
-    description: 'Output only. [Output only] Create time stamp '
+    description: |-
+      The timestamp when the resource was created.
+      See https://google.aip.dev/148#timestamps.
     min_version: 'beta'
     output: true
   - name: 'updateTime'
     type: String
-    description: 'Output only. [Output only] Update time stamp '
+    description: |-
+      The timestamp when the resource was most recently updated.
+      See https://google.aip.dev/148#timestamps.
     min_version: 'beta'
     output: true
   - name: 'labels'
     type: KeyValueLabels
-    description: 'Optional. Labels as key value pairs '
+    description: |-
+      Labels are key/value pairs that help to organize and filter resources.
     min_version: 'beta'
   - name: 'mirroringDeploymentGroup'
     type: String
-    description: "Required. Immutable. The Mirroring Deployment Group that this resource
-    is connected to. Format\nis:\n`projects/{project}/locations/global/mirroringDeploymentGroups/{mirroringDeploymentGroup}` "
+    description: |-
+      The deployment group that this DIRECT endpoint group is connected to, for example:
+      `projects/123456789/locations/global/mirroringDeploymentGroups/my-dg`.
+      See https://google.aip.dev/124.
     min_version: 'beta'
     required: true
     immutable: true
   - name: 'state'
     type: String
-    description: "Output only. Current state of the endpoint group. \n Possible values:\n
-    STATE_UNSPECIFIED\nACTIVE\nCLOSED\nCREATING\nDELETING\nOUT_OF_SYNC"
+    description: |-
+      The current state of the endpoint group.
+      See https://google.aip.dev/216.
+      Possible values:
+      STATE_UNSPECIFIED
+      ACTIVE
+      CLOSED
+      CREATING
+      DELETING
+      OUT_OF_SYNC
+      DELETE_FAILED
     min_version: 'beta'
     output: true
   - name: 'reconciling'
     type: Boolean
-    description: "Output only. Whether reconciling is in progress, recommended per\nhttps://google.aip.dev/128. "
+    description: |-
+      The current state of the resource does not match the user's intended state,
+      and the system is working to reconcile them. This is part of the normal
+      operation (e.g. adding a new association to the group).
+      See https://google.aip.dev/128.
     min_version: 'beta'
     output: true
diff --git a/mmv1/products/networksecurity/MirroringEndpointGroupAssociation.yaml b/mmv1/products/networksecurity/MirroringEndpointGroupAssociation.yaml
