Feat(cv_deploy): Expose the details of the Workspace build validation errors (#4629)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Claus Holbech <[email protected]>
Co-authored-by: Carl Baillargeon <[email protected]>

Author: 4 people

ansible_collections/arista/avd/plugins/action/cv_workflow.py

@@ -32,6 +32,7 @@
         CVPathfinderMetadata,
         CVTimeOuts,
         CVWorkspace,
+        CVWorkspaceBuildWarningsConfig,
         DeployToCvResult,
     )
     from pyavd._utils import get, strip_empties_from_dict
@@ -70,6 +71,14 @@
             "id": {"type": "str", "required": False},
             "requested_state": {"type": "str", "default": "built", "choices": ["pending", "built", "submitted", "abandoned", "deleted"]},
             "force": {"type": "bool", "default": False},
+            "build_warnings": {
+                "type": "dict",
+                "options": {
+                    "enabled": {"type": "bool", "required": False, "default": True},
+                    "suppress_patterns": {"type": "list", "elements": "str", "required": False, "default": []},
+                    "suppress_portfast": {"type": "bool", "required": False, "default": False},
+                },
+            },
         },
     },
     "change_control": {
@@ -190,6 +199,11 @@ async def deploy(self, validated_args: dict, result: dict) -> dict:
             )
 
             if work_to_do:
+                # Pre-process workspace args to convert build_warnings to CVWorkspaceBuildWarningsConfig object.
+                workspace_args = get(validated_args, "workspace", default={})
+                if "build_warnings" in workspace_args:
+                    workspace_args["build_warnings"] = CVWorkspaceBuildWarningsConfig(**workspace_args["build_warnings"])
+
                 # Perform deployment of all objects, getting a DeployToCVResult object back.
                 result_object = await deploy_to_cv(
                     change_control=CVChangeControl(**get(validated_args, "change_control", default={})),
@@ -203,7 +217,7 @@ async def deploy(self, validated_args: dict, result: dict) -> dict:
                     strict_system_mac_address=get(validated_args, "strict_system_mac_address"),
                     strict_tags=get(validated_args, "strict_tags"),
                     timeouts=CVTimeOuts(**get(validated_args, "timeouts", default={})),
-                    workspace=CVWorkspace(**get(validated_args, "workspace", default={})),
+                    workspace=CVWorkspace(**workspace_args),
                 )
                 # Errors and warnings are converted to JSON compatible strings.
                 result_object.errors = [str(error) for error in result_object.errors]

ansible_collections/arista/avd/plugins/modules/cv_workflow.py

@@ -154,6 +154,23 @@
         description: Force submit the workspace even if some devices are not actively streaming to CloudVision.
         type: bool
         default: false
+      build_warnings:
+        description: Configuration for Workspace build warnings handling.
+        type: dict
+        suboptions:
+          enabled:
+            description: Fetch and expose Workspace build warnings.
+            type: bool
+            default: true
+          suppress_patterns:
+            description: Arbitrary list of regex patterns used with fullmatch to suppress EOS CLI warnings.
+            type: list
+            elements: str
+            default: []
+          suppress_portfast:
+            description: Suppress Workspace build warnings related to the usage of the `portfast` feature on switchports.
+            type: bool
+            default: false
   change_control:
     description: CloudVision Change Control to create for the deployment.
     type: dict
@@ -255,6 +272,10 @@
         #   id: <uuid or similar>
           requested_state: submitted
           force: true
+          build_warnings:
+            # enabled: true
+            suppress_patterns: [".*/32 IPv4 address is not configured on the interface.*"]
+            # suppress_portfast: false
         change_control:
         #   name:
         #   description:

ansible_collections/arista/avd/roles/cv_deploy/README.md

@@ -201,7 +201,8 @@ By default the role will
 2. Push all configurations and tags.
 3. Unassign tags
 4. Build and submit the Workspace.
-5. Leave any created Change Control in `pending approval` state.
+5. Fetch and expose errors and warnings raised during the Workspace Build phase.
+6. Leave any created Change Control in `pending approval` state.
 
 !!! warning
     When deploying CloudVision Tag assignments, the builtin behavior is to unassign any other tags
@@ -220,6 +221,12 @@ cv_submit_workspace: true
 # If set, configurations will not be validated for non-streaming devices.
 cv_submit_workspace_force: false
 
+# Fetch and expose Workspace build warnings.
+# Suppress specific warnings based on pre-defined options or custom regex fullmatch pattern(s).
+cv_workspace_build_warnings_enabled: true
+cv_workspace_build_warnings_suppress_patterns: []
+cv_workspace_build_warnings_suppress_portfast: false
+
 # Approve, start and wait for the Change Control to Complete. Otherwise the Change Control will be left in "pending approval" mode.
 cv_run_change_control: false
 

ansible_collections/arista/avd/roles/cv_deploy/defaults/main/main.yml

@@ -42,6 +42,12 @@ cv_submit_workspace: true
 # If set, configurations will not be validated for non-streaming devices.
 cv_submit_workspace_force: false
 
+# Fetch and expose Workspace build warnings.
+# Suppress specific warnings based on pre-defined options or custom regex fullmatch pattern(s).
+cv_workspace_build_warnings_enabled: true
+cv_workspace_build_warnings_suppress_patterns: []
+cv_workspace_build_warnings_suppress_portfast: false
+
 # Approve and Start Change Control. Otherwise the Change Control will be left in "pending approval" mode.
 cv_run_change_control: false
 

ansible_collections/arista/avd/roles/cv_deploy/tasks/main.yml

@@ -40,6 +40,10 @@
       id: "{{ cv_workspace_id | arista.avd.default }}"
       requested_state: "{{ cv_workspace_requested_state | arista.avd.default('submitted' if cv_submit_workspace else 'built') }}"
       force: "{{ cv_submit_workspace_force }}"
+      build_warnings:
+        enabled: "{{ cv_workspace_build_warnings_enabled }}"
+        suppress_patterns: "{{ cv_workspace_build_warnings_suppress_patterns }}"
+        suppress_portfast: "{{ cv_workspace_build_warnings_suppress_portfast }}"
     change_control:
       name: "{{ cv_change_control_name | arista.avd.default }}"
       description: "{{ cv_change_control_description | arista.avd.default }}"

docs/plugins/Modules_and_action_plugins/cv_workflow.md

@@ -58,6 +58,10 @@ The `arista.avd.cv_workflow` module is an Ansible Action Plugin providing the fo
 | <samp>&nbsp;&nbsp;&nbsp;&nbsp;id</samp> | str | optional | None | - | Optional ID to use for the created Workspace. If there is already a workspace with the same ID, it must be in the &#39;pending&#39; state. |
 | <samp>&nbsp;&nbsp;&nbsp;&nbsp;requested_state</samp> | str | optional | built | Valid values:<br>- <code>pending</code><br>- <code>built</code><br>- <code>submitted</code><br>- <code>abandoned</code><br>- <code>deleted</code> | The requested state for the Workspace.<br><br>- `pending`: Leave the Workspace in pending state.<br>- `built`: Build the Workspace but do not submit.<br>- `submitted` (default): Build and submit the Workspace.<br>- `abandoned`: Build and then abandon the Workspace.<br>    Used for dry-run where no changes will be committed to CloudVision.<br>- `deleted`: Build, abort and then delete the Workspace.<br>    Used for dry-run where no changes will be committed to CloudVision and the temporary Workspace will be removed to avoid &#34;clutter&#34;. |
 | <samp>&nbsp;&nbsp;&nbsp;&nbsp;force</samp> | bool | optional | False | - | Force submit the workspace even if some devices are not actively streaming to CloudVision. |
+| <samp>&nbsp;&nbsp;&nbsp;&nbsp;build_warnings</samp> | dict | optional | None | - | Configuration for Workspace build warnings handling. |
+| <samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enabled</samp> | bool | optional | True | - | Fetch and expose Workspace build warnings. |
+| <samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;suppress_patterns</samp> | list | optional | [] | - | Arbitrary list of regex patterns used with fullmatch to suppress EOS CLI warnings. |
+| <samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;suppress_portfast</samp> | bool | optional | False | - | Suppress Workspace build warnings related to the usage of the `portfast` feature on switchports. |
 | <samp>change_control</samp> | dict | optional | None | - | CloudVision Change Control to create for the deployment. |
 | <samp>&nbsp;&nbsp;&nbsp;&nbsp;name</samp> | str | optional | None | - | Optional name to use for the created Change Control. By default the name generated by CloudVision will be kept. |
 | <samp>&nbsp;&nbsp;&nbsp;&nbsp;description</samp> | str | optional | None | - | Optional description to use for the created Change Control. |
@@ -129,6 +133,10 @@ The `arista.avd.cv_workflow` module is an Ansible Action Plugin providing the fo
         #   id: <uuid or similar>
           requested_state: submitted
           force: true
+          build_warnings:
+            # enabled: true
+            suppress_patterns: [".*/32 IPv4 address is not configured on the interface.*"]
+            # suppress_portfast: false
         change_control:
         #   name:
         #   description:

python-avd/pyavd/_cv/client/workspace.py

@@ -13,6 +13,10 @@
     Response,
     ResponseStatus,
     Workspace,
+    WorkspaceBuildDetails,
+    WorkspaceBuildDetailsKey,
+    WorkspaceBuildDetailsServiceStub,
+    WorkspaceBuildDetailsStreamRequest,
     WorkspaceConfig,
     WorkspaceConfigDeleteRequest,
     WorkspaceConfigServiceStub,
@@ -317,3 +321,36 @@ async def wait_for_workspace_state(
         # Use case where stream completed without getting Workspace update in the desired state
         msg = f"Workspace '{workspace_id}' has not reached desired state '{state}'."
         raise CVWorkspaceFailed(msg)
+
+    @GRPCRequestHandler()
+    async def get_workspace_build_details(
+        self: CVClientProtocol,
+        workspace_id: str,
+        build_id: str,
+        time: datetime | None = None,
+        timeout: float = DEFAULT_API_TIMEOUT,
+    ) -> list[WorkspaceBuildDetails]:
+        """
+        Get Workspace Build Details using arista.workspace.v1.WorkspaceBuildDetailsService.GetAll API.
+
+        Parameters:
+            workspace_id: Unique identifier the workspace.
+            build_id: Unique identifier of the last WS build attempt.
+            time: Timestamp from which the information is fetched. `now()` if not set.
+            timeout: Timeout in seconds.
+
+        Returns:
+            List of WorkspaceBuildDetails objects.
+        """
+        request = WorkspaceBuildDetailsStreamRequest(
+            partial_eq_filter=[
+                WorkspaceBuildDetails(
+                    key=WorkspaceBuildDetailsKey(workspace_id=workspace_id, build_id=build_id),
+                ),
+            ],
+            time=time,
+        )
+        client = WorkspaceBuildDetailsServiceStub(self._channel)
+        responses = client.get_all(request, metadata=self._metadata, timeout=timeout)
+
+        return [response.value async for response in responses]

python-avd/pyavd/_cv/workflows/constants.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025-2026 Arista Networks, Inc.
+# Use of this source code is governed by the Apache License 2.0
+# that can be found in the LICENSE file.
+
+EOS_CLI_WARNINGS = {
+    # Text pattern to match EOS CLI warning regarding utilization of the spanning-tree portfast feature.
+    "portfast": (
+        "^! portfast should only be enabled on ports connected to a single host. Connecting hubs, concentrators, switches, bridges, etc. "
+        "to this interface when portfast is enabled can cause temporary bridging loops. Use with CAUTION.$"
+    )
+}