Refactor(cv_deploy): Add cv_deploy schema files (#6679)

Co-authored-by: Guillaume Mulocher <gmulocher@arista.com>

Author: carl-baillargeon

.gitignore

@@ -54,6 +54,7 @@ uv.lock
 # Hash files created when running pyavd from source
 python-avd/pyavd/*/j2templates/.hash
 python-avd/pyavd/*/schema/schema_fragments/.hash
+schemas/*/schema_fragments/.hash
 
 # gz of schema store
 python-avd/pyavd/_schema/schemas.json.gz

.pre-commit-config.yaml

@@ -51,6 +51,7 @@ repos:
           (ansible_collections/arista/avd/roles/.*/(handlers|tasks)/.*\.yml
           |python-avd/pyavd/_(eos_cli_config_gen|eos_designs)/schema/.*\.yml
           |python-avd/pyavd/_eos_designs/eos_designs_facts/schema/.*\.yml
+          |schemas/.*/.*\.yml
           )
 
         args:
@@ -267,7 +268,7 @@ repos:
         name: Build AVD schemas and documentation.
         entry: sh -c 'exec python-avd/scripts/build_schemas.py'
         language: python
-        files: python-avd/pyavd/[a-z_]+/schema
+        files: (python-avd/pyavd/[a-z_]+/schema|schemas/[a-z_]+)
         pass_filenames: false
         additional_dependencies: ['deepmerge>=1.1.0', 'PyYAML>=6.0.0', 'pydantic>=2.3.0', 'jsonschema-rs>=0.24', 'referencing>=0.35.0', 'ruff==0.7.2']
 
@@ -277,13 +278,15 @@ repos:
         language: python
         args:
           - --root-path
-          - "ansible_collections/arista/avd"
+          - "."
           - --table-files
           - "ansible_collections/arista/avd/roles/eos_cli_config_gen/docs/tables/*.md"
           - "ansible_collections/arista/avd/roles/eos_designs/docs/tables/*.md"
+          - "schemas/cv_deploy/docs/tables/*.md"
           - --global-docs
           - "ansible_collections/arista/avd/roles/eos_cli_config_gen/docs/*.md"
           - "ansible_collections/arista/avd/roles/eos_designs/docs/*.md"
+          - "ansible_collections/arista/avd/roles/cv_deploy/README.md"
           - --ignore-files
           - ansible_collections/arista/avd/roles/eos_cli_config_gen/docs/tables/role-input-validation.md
           - ansible_collections/arista/avd/roles/eos_cli_config_gen/docs/tables/service-unsupported-transceiver.md
@@ -292,6 +295,9 @@ repos:
           - ansible_collections/arista/avd/roles/eos_designs/docs/tables/role-input-validation.md
           - ansible_collections/arista/avd/roles/eos_designs/docs/tables/unsupported-transceiver.md
           - ansible_collections/arista/avd/roles/eos_designs/docs/tables/removed-keys.md
+          - schemas/cv_deploy/docs/tables/metadata.md
+          # TODO: Remove once cv_deploy schema integration is complete.
+          - schemas/cv_deploy/docs/tables/cv_deploy.md
         pass_filenames: false
 
       - id: sort-hosts-yml

pylintrc

@@ -8,6 +8,7 @@ ignore-paths=
   python-avd/pyavd/_eos_cli_config_gen/schema/__init__.py,
   python-avd/pyavd/_eos_designs/schema/__init__.py,
   python-avd/pyavd/_eos_designs/eos_designs_facts/schema/protocol.py,
+  python-avd/pyavd/_cv/schema/__init__.py,
   python-avd/tests/pyavd/schema/data_merging_schema_class.py,
 
 [MESSAGES CONTROL]

python-avd/pyavd/_cv/schema/__init__.py

@@ -0,0 +1,287 @@
+# Copyright (c) 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.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from pyavd._eos_cli_config_gen.schema import EosCliConfigGen
+from pyavd._schema.models.avd_list import AvdList
+from pyavd._schema.models.avd_model import AvdModel
+
+if TYPE_CHECKING:
+    from pyavd._utils import Undefined, UndefinedType
+
+
+class CvDeploy(AvdModel):
+    """Subclass of AvdModel."""
+
+    class CvDeviceTagsItem(AvdModel):
+        """Subclass of AvdModel."""
+
+        _fields: ClassVar[dict] = {"name": {"type": str}, "value": {"type": str}}
+        name: str
+        value: str
+
+        if TYPE_CHECKING:
+
+            def __init__(self, *, name: str | UndefinedType = Undefined, value: str | UndefinedType = Undefined) -> None:
+                """
+                CvDeviceTagsItem.
+
+                Subclass of AvdModel.
+
+                Args:
+                    name: name
+                    value: value
+
+                """
+
+    class CvDeviceTags(AvdList[CvDeviceTagsItem]):
+        """Subclass of AvdList with `CvDeviceTagsItem` items."""
+
+    CvDeviceTags._item_type = CvDeviceTagsItem
+
+    class CvInterfaceTagsItem(AvdModel):
+        """Subclass of AvdModel."""
+
+        class TagsItem(AvdModel):
+            """Subclass of AvdModel."""
+
+            _fields: ClassVar[dict] = {"name": {"type": str}, "value": {"type": str}}
+            name: str
+            value: str
+
+            if TYPE_CHECKING:
+
+                def __init__(self, *, name: str | UndefinedType = Undefined, value: str | UndefinedType = Undefined) -> None:
+                    """
+                    TagsItem.
+
+                    Subclass of AvdModel.
+
+                    Args:
+                        name: name
+                        value: value
+
+                    """
+
+        class Tags(AvdList[TagsItem]):
+            """Subclass of AvdList with `TagsItem` items."""
+
+        Tags._item_type = TagsItem
+
+        _fields: ClassVar[dict] = {"interface": {"type": str}, "tags": {"type": Tags}}
+        interface: str
+        tags: Tags
+        """Subclass of AvdList with `TagsItem` items."""
+
+        if TYPE_CHECKING:
+
+            def __init__(self, *, interface: str | UndefinedType = Undefined, tags: Tags | UndefinedType = Undefined) -> None:
+                """
+                CvInterfaceTagsItem.
+
+                Subclass of AvdModel.
+
+                Args:
+                    interface: interface
+                    tags: Subclass of AvdList with `TagsItem` items.
+
+                """
+
+    class CvInterfaceTags(AvdList[CvInterfaceTagsItem]):
+        """Subclass of AvdList with `CvInterfaceTagsItem` items."""
+
+    CvInterfaceTags._item_type = CvInterfaceTagsItem
+
+    class Metadata(AvdModel):
+        """Subclass of AvdModel."""
+
+        _fields: ClassVar[dict] = {
+            "is_deployed": {"type": bool},
+            "serial_number": {"type": str},
+            "system_mac_address": {"type": str},
+            "cv_tags": {"type": EosCliConfigGen.Metadata.CvTags},
+            "cv_pathfinder": {"type": EosCliConfigGen.Metadata.CvPathfinder},
+        }
+        _allow_other_keys: ClassVar[bool] = True
+        is_deployed: bool | None
+        """Key only used for documentation or validation purposes."""
+        serial_number: str | None
+        """
+        Serial Number of the device.
+        Used only for documentation and deployment purposes. It is used by the
+        'cv_deploy' role.
+        """
+        system_mac_address: str | None
+        cv_tags: EosCliConfigGen.Metadata.CvTags
+        cv_pathfinder: EosCliConfigGen.Metadata.CvPathfinder
+        """Metadata used for CV Pathfinder visualization on CloudVision."""
+
+        if TYPE_CHECKING:
+
+            def __init__(
+                self,
+                *,
+                is_deployed: bool | None | UndefinedType = Undefined,
+                serial_number: str | None | UndefinedType = Undefined,
+                system_mac_address: str | None | UndefinedType = Undefined,
+                cv_tags: EosCliConfigGen.Metadata.CvTags | UndefinedType = Undefined,
+                cv_pathfinder: EosCliConfigGen.Metadata.CvPathfinder | UndefinedType = Undefined,
+            ) -> None:
+                """
+                Metadata.
+
+                Subclass of AvdModel.
+
+                Args:
+                    is_deployed: Key only used for documentation or validation purposes.
+                    serial_number:
+                       Serial Number of the device.
+                       Used only for documentation and deployment purposes. It is used by the
+                       'cv_deploy' role.
+                    system_mac_address: system_mac_address
+                    cv_tags: cv_tags
+                    cv_pathfinder: Metadata used for CV Pathfinder visualization on CloudVision.
+
+                """
+
+    _fields: ClassVar[dict] = {
+        "is_deployed": {"type": bool, "default": True},
+        "serial_number": {"type": str},
+        "system_mac_address": {"type": str},
+        "cv_device_tags": {"type": CvDeviceTags},
+        "cv_interface_tags": {"type": CvInterfaceTags},
+        "cv_pathfinder_metadata": {"type": EosCliConfigGen.Metadata.CvPathfinder},
+        "metadata": {"type": Metadata},
+    }
+    _allow_other_keys: ClassVar[bool] = True
+    is_deployed: bool
+    """
+    When set to `false`, the device will be skipped from all operations performed by the `cv_deploy`
+    role.
+
+    Default value: `True`
+    """
+    serial_number: str | None
+    """
+    Serial number of the device used to identify the device in CloudVision.
+    Takes precedence over
+    `system_mac_address` and `inventory_hostname`.
+
+    Device identification precedence:
+      1.
+    `serial_number` (highest priority)
+      2. `system_mac_address`
+      3. `inventory_hostname` (lowest
+    priority, used only if neither of the above is set)
+    """
+    system_mac_address: str | None
+    """
+    System MAC address of the device used to identify the device in CloudVision.
+    Should match the MAC
+    address shown in "show version" on the device.
+    Used when `serial_number` is not set.
+
+    Device
+    identification precedence:
+      1. `serial_number` (highest priority)
+      2. `system_mac_address`
+      3.
+    `inventory_hostname` (lowest priority, used only if neither of the above is set)
+    """
+    cv_device_tags: CvDeviceTags
+    """
+    List of CloudVision device tags to be assigned to this device.
+
+    Subclass of AvdList with
+    `CvDeviceTagsItem` items.
+    """
+    cv_interface_tags: CvInterfaceTags
+    """
+    List of CloudVision interface tags to be assigned to interfaces on this device.
+
+    Subclass of AvdList
+    with `CvInterfaceTagsItem` items.
+    """
+    cv_pathfinder_metadata: EosCliConfigGen.Metadata.CvPathfinder
+    """Metadata used for CV Pathfinder visualization on CloudVision."""
+    metadata: Metadata
+    """
+    Metadata from the `eos_designs` role, loaded automatically from structured configs.
+    For standalone
+    usage without `eos_designs`, use the other `cv_deploy` schema keys instead.
+    If both are provided,
+    `metadata` takes precedence.
+
+    Subclass of AvdModel.
+    """
+
+    if TYPE_CHECKING:
+
+        def __init__(
+            self,
+            *,
+            is_deployed: bool | UndefinedType = Undefined,
+            serial_number: str | None | UndefinedType = Undefined,
+            system_mac_address: str | None | UndefinedType = Undefined,
+            cv_device_tags: CvDeviceTags | UndefinedType = Undefined,
+            cv_interface_tags: CvInterfaceTags | UndefinedType = Undefined,
+            cv_pathfinder_metadata: EosCliConfigGen.Metadata.CvPathfinder | UndefinedType = Undefined,
+            metadata: Metadata | UndefinedType = Undefined,
+        ) -> None:
+            """
+            CvDeploy.
+
+            Subclass of AvdModel.
+
+            Args:
+                is_deployed:
+                   When set to `false`, the device will be skipped from all operations performed by the `cv_deploy`
+                   role.
+                serial_number:
+                   Serial number of the device used to identify the device in CloudVision.
+                   Takes precedence over
+                   `system_mac_address` and `inventory_hostname`.
+
+                   Device identification precedence:
+                     1.
+                   `serial_number` (highest priority)
+                     2. `system_mac_address`
+                     3. `inventory_hostname` (lowest
+                   priority, used only if neither of the above is set)
+                system_mac_address:
+                   System MAC address of the device used to identify the device in CloudVision.
+                   Should match the MAC
+                   address shown in "show version" on the device.
+                   Used when `serial_number` is not set.
+
+                   Device
+                   identification precedence:
+                     1. `serial_number` (highest priority)
+                     2. `system_mac_address`
+                     3.
+                   `inventory_hostname` (lowest priority, used only if neither of the above is set)
+                cv_device_tags:
+                   List of CloudVision device tags to be assigned to this device.
+
+                   Subclass of AvdList with
+                   `CvDeviceTagsItem` items.
+                cv_interface_tags:
+                   List of CloudVision interface tags to be assigned to interfaces on this device.
+
+                   Subclass of AvdList
+                   with `CvInterfaceTagsItem` items.
+                cv_pathfinder_metadata: Metadata used for CV Pathfinder visualization on CloudVision.
+                metadata:
+                   Metadata from the `eos_designs` role, loaded automatically from structured configs.
+                   For standalone
+                   usage without `eos_designs`, use the other `cv_deploy` schema keys instead.
+                   If both are provided,
+                   `metadata` takes precedence.
+
+                   Subclass of AvdModel.
+
+            """

python-avd/pyavd/_schema/constants.py

@@ -14,10 +14,14 @@
 METASCHEMA_DIR = PYAVD_DIR.joinpath("_schema")
 METASCHEMA_PICKLED_SCHEMA_PATH = METASCHEMA_DIR.joinpath("avd_meta_schema.pickle")
 
+CV_DEPLOY_SCHEMA_DIR = PYAVD_DIR.joinpath("_cv/schema")
+CV_DEPLOY_PICKLED_SCHEMA_PATH = CV_DEPLOY_SCHEMA_DIR.joinpath("cv_deploy.schema.pickle")
+
 PICKLED_SCHEMAS = {
     "avd_meta_schema": METASCHEMA_PICKLED_SCHEMA_PATH,
     "eos_cli_config_gen": EOS_CLI_CONFIG_GEN_PICKLED_SCHEMA_PATH,
     "eos_designs": EOS_DESIGNS_PICKLED_SCHEMA_PATH,
+    "cv_deploy": CV_DEPLOY_PICKLED_SCHEMA_PATH,
 }
 
 ACCEPTED_COERCION_MAP = {

python-avd/pyavd/api/schemas/__init__.py

@@ -1,7 +1,8 @@
 # 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.
+from pyavd._cv.schema import CvDeploy as CVDeploy
 from pyavd._eos_cli_config_gen.schema import EosCliConfigGen as EOSConfig
 from pyavd._eos_designs.schema import EosDesigns as AVDDesign
 
-__all__ = ["AVDDesign", "EOSConfig"]
+__all__ = ["AVDDesign", "CVDeploy", "EOSConfig"]

python-avd/pyproject.toml

@@ -71,6 +71,7 @@ include-package-data = true
 [tool.setuptools.package-data]
 "*" = [
     "avd_meta_schema.pickle",
+    "cv_deploy.schema.pickle",
     "eos_cli_config_gen.schema.pickle",
     "eos_designs.schema.pickle",
     "schemas.json.gz",