pyavd 6.2.0.dev2__py3-none-any.whl → 6.3.0.dev1__py3-none-any.whl

pyavd/__init__.py

@@ -18,7 +18,7 @@ PYAVD_PRERELEASE = ""  # Set this to aN or bN for alpha and beta releases of pya
 __author__ = "Arista Networks"
 __copyright__ = "Copyright 2023-2026 Arista Networks"
 __license__ = "Apache 2.0"
-__version__ = "6.2.0.dev2"
+__version__ = "6.3.0.dev1"
 
 __all__ = [
     "get_avd_facts",

pyavd/_anta/input_factories/hardware.py

@@ -80,7 +80,11 @@ class VerifyTransceiversManufacturersInputFactory(AntaTestInputFactory[VerifyTra
     @skip_if_hardware_validation_disabled
     def create(self) -> Iterator[VerifyTransceiversManufacturers.Input]:
         """Generate the inputs for the `VerifyTransceiversManufacturers` test."""
-        yield VerifyTransceiversManufacturers.Input(manufacturers=list(self.structured_config.metadata.validate_hardware.transceiver_manufacturers))
+        validate_hardware = self.structured_config.metadata.validate_hardware
+        manufacturers = list(validate_hardware.transceiver_manufacturers)
+        if validate_hardware.ignore_no_transceivers and "Not Present" not in manufacturers:
+            manufacturers.append("Not Present")
+        yield VerifyTransceiversManufacturers.Input(manufacturers=manufacturers)
 
 
 class VerifyInventoryInputFactory(AntaTestInputFactory[VerifyInventory.Input]):

pyavd/_cv/api/arista/alert/v1/__init__.py

@@ -32,6 +32,7 @@ __all__ = (
     "Settings",
     "EmailSettings",
     "AzureOAuth",
+    "OAuth2ClientCredentials",
     "HttpSettings",
     "HttpHeaders",
     "HeaderValues",
@@ -959,7 +960,7 @@ class EmailSettings(aristaproto.Message):
 @dataclass(eq=False, repr=False)
 class AzureOAuth(aristaproto.Message):
     """
-    AzureOAuth contains the settings for the sending of emails on Azure smtp server
+    AzureOAuth contains the settings for authenticating against Azure using OAuth2
     """
 
     client_id: Optional[str] = aristaproto.message_field(1, wraps=aristaproto.TYPE_STRING)
@@ -982,6 +983,33 @@ class AzureOAuth(aristaproto.Message):
     """scopes are the scopes that auth is granted for"""
 
 
+@dataclass(eq=False, repr=False)
+class OAuth2ClientCredentials(aristaproto.Message):
+    """
+    OAuth2ClientCredentials contains generic settings for authenticating webhook
+    requests using the OAuth2 client credentials (including OpenID Connect) flow.
+    """
+
+    client_id: Optional[str] = aristaproto.message_field(1, wraps=aristaproto.TYPE_STRING)
+    """client_id of the OAuth2 client"""
+
+    client_secret: Optional[str] = aristaproto.message_field(2, wraps=aristaproto.TYPE_STRING)
+    """client_secret for the OAuth2 client"""
+
+    token_url: Optional[str] = aristaproto.message_field(3, wraps=aristaproto.TYPE_STRING)
+    """
+    token_url is the full URL of the OAuth2/OIDC token endpoint
+    e.g. https://example.com/oauth2/token
+    """
+
+    scope: Optional[str] = aristaproto.message_field(4, wraps=aristaproto.TYPE_STRING)
+    """
+    scope is the optional OAuth2 scope string requested for the access token.
+    Multiple scopes can be defined by separating them with spaces,
+    e.g. \"scope1 scope2 scope3\".
+    """
+
+
 @dataclass(eq=False, repr=False)
 class HttpSettings(aristaproto.Message):
     """
@@ -1088,8 +1116,12 @@ class WebhookSettings(aristaproto.Message):
 
     azure_o_auth: "AzureOAuth" = aristaproto.message_field(1)
     """
-    azure_o_auth used for auth when using an Azure smtp server
-    uses auth_username
+    azure_o_auth used for auth when using Azure to authenticate webhook requests
+    """
+
+    oauth2_client_credentials: "OAuth2ClientCredentials" = aristaproto.message_field(2)
+    """
+    oauth2_client_credentials used for generic OAuth2/OIDC client-credentials auth for webhook
     """
 
 
@@ -1508,6 +1540,11 @@ class Matches(aristaproto.Message):
     intf_tags is a string tag query that is used to match on the event's interface tags
     """
 
+    virtual_tags: Optional[str] = aristaproto.message_field(7, wraps=aristaproto.TYPE_STRING)
+    """
+    virtual_tags is a string tag query that is used to match on the event's virtual tags
+    """
+
     rule_ids: "___fmp__.RepeatedString" = aristaproto.message_field(6)
     """
     rule_ids is a list of rule IDs to filter on,

pyavd/_cv/api/arista/endpointlocation/v1/__init__.py

@@ -206,6 +206,16 @@ class MacType(aristaproto.Enum):
     MAC_TYPE_CONFIGURED_STATIC_FRR indicates a MAC configured statically and protected by an EVPN FRR backup tunnel.
     """
 
+    VPLS_DYNAMIC_REMOTE = 32
+    """
+    MAC_TYPE_VPLS_DYNAMIC_REMOTE indicates a remote MAC learned dynamically from the VPLS.
+    """
+
+    CONFIGURED_SYS = 33
+    """
+    MAC_TYPE_CONFIGURED_SYS indicates a system MAC address configured on an interface.
+    """
+
     OTHER = 99999
     """MAC_TYPE_OTHER is used for capturing future MAC types."""
 

pyavd/_cv/api/arista/imagestatus/v1/__init__.py

@@ -13,6 +13,7 @@ __all__ = (
     "ErrorCode",
     "WarningCode",
     "InfoCode",
+    "ImageSource",
     "SoftwareImage",
     "ImageMetadata",
     "Extension",
@@ -378,6 +379,25 @@ class InfoCode(aristaproto.Enum):
     """
 
 
+class ImageSource(aristaproto.Enum):
+    """ImageSource indicates the source type for the image configuration."""
+
+    UNSPECIFIED = 0
+    """IMAGE_SOURCE_UNSPECIFIED uninitialized value"""
+
+    STUDIO = 1
+    """IMAGE_SOURCE_STUDIO - image configured from studio"""
+
+    NETWORK_PROVISIONING = 2
+    """
+    IMAGE_SOURCE_NETWORK_PROVISIONING - image configured from
+    network provisioning workflow
+    """
+
+    HIERARCHY = 3
+    """IMAGE_SOURCE_HIERARCHY - image configured from hierarchy workflow"""
+
+
 @dataclass(eq=False, repr=False)
 class SoftwareImage(aristaproto.Message):
     """

pyavd/_cv/api/arista/studio/v1/__init__.py

@@ -243,6 +243,9 @@ class EntityType(aristaproto.Enum):
     entity type for static config studio.
     """
 
+    DEPENDENCIES = 8
+    """ENTITY_TYPE_DEPENDENCIES indicates the Dependencies entity type."""
+
 
 class TemplateType(aristaproto.Enum):
     """
@@ -578,10 +581,17 @@ class Entities(aristaproto.Message):
 
     values: Dict[str, "Entity"] = aristaproto.map_field(1, aristaproto.TYPE_STRING, aristaproto.TYPE_MESSAGE)
     """
-    values is a map from entity type name to entity
-    The possible keys to this map are ENTITY_TYPE_STUDIO,
-    ENTITY_TYPE_INPUTS, ENTITY_TYPE_ASSIGNED_TAGS,
-    ENTITY_TYPE_BUILD_HOOK and ENTITY_TYPE_AUTOFILL_ACTION.
+    values is a map from EntityType enum name to Entity.
+    Keys are the EntityType enum names defined below, e.g.:
+
+    ```
+    \"ENTITY_TYPE_INPUTS\" -> Entity{
+        entity_type:      ENTITY_TYPE_INPUTS,
+        last_modified_at: 2026-05-07T12:34:56Z,
+        last_modified_by: \"admin\",
+        removed:          false,
+    }
+    ```
     """
 
 
@@ -930,10 +940,13 @@ class FloatInputFieldProps(aristaproto.Message):
     `{ fieldId: field_id }`.
 
     E.g,
+
+    ```
     [
-      `{ fieldId: floatField1ID }`,
-      `{ fieldId: floatField2ID }`
+      { fieldId: floatField1ID },
+      { fieldId: floatField2ID }
     ]
+    ```
     Here, the possible values for the floats identified by
     `floatField1ID` and `floatField2ID` are used as the
     possible values for this float.

pyavd/_cv/api/arista/workspace/v1/__init__.py

@@ -675,6 +675,9 @@ class EntityType(aristaproto.Enum):
     NODE = 13
     """ENTITY_TYPE_NODE indicates the Node entity type."""
 
+    DEPENDENCIES = 14
+    """ENTITY_TYPE_DEPENDENCIES indicates the dependencies entity type."""
+
 
 class DiffType(aristaproto.Enum):
     """DiffType enumerates types of diff."""
@@ -855,6 +858,15 @@ class Workspace(aristaproto.Message):
     configured to exclude Network Provisioning.
     """
 
+    decommission_request_ids: "___fmp__.MapStringString" = aristaproto.message_field(16)
+    """
+    decommission_request_ids provides, for each device staged for
+    decommission in this workspace, the corresponding request UUID passed
+    to inventory.v1.DeviceDecommissioningConfig. These request UUIDs can
+    be used to track the status using the inventory.v1.DeviceDecommissioning
+    resource.
+    """
+
 
 @dataclass(eq=False, repr=False)
 class InputError(aristaproto.Message):
@@ -1084,6 +1096,9 @@ class ImageValidationResult(aristaproto.Message):
     infos: "__imagestatus_v1__.ImageInfos" = aristaproto.message_field(5)
     """infos are any info messages about the generated image."""
 
+    image_source: "__imagestatus_v1__.ImageSource" = aristaproto.enum_field(6)
+    """image_source identifies the source of the image."""
+
 
 @dataclass(eq=False, repr=False)
 class ConfigSyncResult(aristaproto.Message):
@@ -1391,9 +1406,12 @@ class DiffEntry(aristaproto.Message):
     - value: the element’s identifier
 
     Example:
-      users = [\{\"id\":\"u1\",\"name\":\"Alice\"\}]
-      key_path = [\"users\", \"[id=u1]\", \"name\"]
-      path     = [\"users\", \"0\", \"name\"]
+
+    ```
+    users = [{\"id\":\"u1\",\"name\":\"Alice\"}]
+    key_path = [\"users\", \"[id=u1]\", \"name\"]
+    path     = [\"users\", \"0\", \"name\"]
+    ```
     """
 
 
@@ -1418,28 +1436,28 @@ class DiffKey(aristaproto.Message):
     by [key1, value1, key2, value2, ...]
     studio_id are well known e.g studio-date-time
     e.g entity_ids for entity types
-    studio, inputs, assigned tags: [“studio_id”, <id>]
-    buildhook: [“studio_id”, <id>, “hook_id”, <id>]
-    autofill: [“studio_id”, <id>, “input_field_id”, <id>]
-    configlet: [“configlet_id”, <id>]
-    configletassignment : [“configlet_assignment_id”, <id>]
-    tags:
-    element_type is one of \"1\" (device), \"2\" (interface)
-    [\"creator_type\", \"2\", \"element_type\", <element_type>,
-    \"element_sub_type\", \"1\", \"label\", <label>, \"value\", <value>]
-    tag assignments:
-    For element_type = \"1\" (device)
-    [\"creator_type\", \"2\", \"element_type\", \"1\", \"element_sub_type\", \"1\",
-    \"label\", <label>, \"value\", <value>, \"device_id\", <id>]
-    For element_type = \"2\" (interface)
-    [\"creator_type\", \"2\", \"element_type\", \"2\", \"element_sub_type\", \"1\",
-    \"label\", <label>, \"value\", <value>, \"device_id\", <id>,
-    \"interface_id\", <id>]
-    hierarchy related entities:
-    node: [\"node_id\", <id>]
-    fixture_class: [\"fixture_class_id\", <id>]
-    fixture_instance: [\"fixture_instance_id\", <id>]
-    processor: [\"processor_id\", <id>]
+      studio, inputs, assigned tags, dependencies: [“studio_id”, <id>]
+      buildhook: [“studio_id”, <id>, “hook_id”, <id>]
+      autofill: [“studio_id”, <id>, “input_field_id”, <id>]
+      configlet: [“configlet_id”, <id>]
+      configletassignment: [“configlet_assignment_id”, <id>]
+      tags:
+        element_type is one of “1” (device), “2” (interface)
+        [“creator_type”, “2”, “element_type”, <element_type>,
+         “element_sub_type”, “1”, “label”, <label>, “value”, <value>]
+      tag assignments:
+        For element_type = “1” (device)
+          [“creator_type”, “2”, “element_type”, “1”, “element_sub_type”, “1”,
+           “label”, <label>, “value”, <value>, “device_id”, <id>]
+        For element_type = “2” (interface)
+          [“creator_type”, “2”, “element_type”, “2”, “element_sub_type”, “1”,
+           “label”, <label>, “value”, <value>, “device_id”, <id>,
+           “interface_id”, <id>]
+      hierarchy related entities:
+        node: [“node_id”, <id>]
+        fixture_class: [“fixture_class_id”, <id>]
+        fixture_instance: [“fixture_instance_id”, <id>]
+        processor: [“processor_id”, <id>]
     """
 
 

pyavd/_cv/client/__init__.py

@@ -8,9 +8,12 @@ import platform
 import ssl
 import sys
 from importlib.metadata import PackageNotFoundError, version
+from logging import getLogger
+from os import environ
 from typing import TYPE_CHECKING, Protocol
 
 from grpclib.client import Channel
+from grpclib.config import Configuration
 from requests import JSONDecodeError, get, post
 from requests.exceptions import HTTPError, RequestException
 
@@ -18,8 +21,10 @@ from .change_control import ChangeControlMixin
 from .configlet import ConfigletMixin
 from .exceptions import CVClientException
 from .inventory import InventoryMixin
+from .models import CVTLSSettings
 from .proxy import HTTPProxyManager
 from .studio import StudioMixin
+from .studio_topology import StudioTopologyMixin
 from .swg import SwgMixin
 from .tag import TagMixin
 from .utils import UtilsMixin
@@ -32,12 +37,17 @@ if TYPE_CHECKING:
     from grpclib.protocol import H2Protocol
     from typing_extensions import Self
 
+    from pyavd._cv.workflows.models import CVGRPCChannelConfiguration
+
+LOGGER = getLogger(__name__)
+
 
 class CVClientProtocol(
     ChangeControlMixin,
     ConfigletMixin,
     InventoryMixin,
     StudioMixin,
+    StudioTopologyMixin,
     SwgMixin,
     TagMixin,
     WorkspaceMixin,
@@ -51,11 +61,14 @@ class CVClientProtocol(
     _servers: list[str]
     _port: int
     _verify_certs: bool
+    _use_system_certs: bool
     _token: str | None
     _username: str | None
     _password: str | None
     _cv_version: CvVersion | None = None
     _proxy_manager: HTTPProxyManager | None = None
+    _grpc_channel_configuration: CVGRPCChannelConfiguration | None = None
+    _tls: CVTLSSettings
 
     async def __aenter__(self) -> Self:
         """Using asynchronous context manager since grpclib must be initialized inside an asyncio loop."""
@@ -71,9 +84,6 @@ class CVClientProtocol(
         # TODO: Verify connection
         # TODO: Handle multinode clusters
 
-        # Ensure that the default ssl context is initialized before doing any requests.
-        ssl_context = self._ssl_context()
-
         if not self._token:
             self._set_token()
 
@@ -81,13 +91,13 @@ class CVClientProtocol(
 
         if self._channel is None:
             if self._proxy_manager is not None:
-                self._channel = await self._create_proxy_channel(ssl_context)
+                self._channel = await self._create_proxy_channel(self._tls.grpc_ssl)
             else:
-                self._channel = Channel(host=self._servers[0], port=self._port, ssl=ssl_context)
+                self._channel = Channel(host=self._servers[0], port=self._port, ssl=self._tls.grpc_ssl, config=self._grpclib_channel_config)
 
         self._metadata = {"authorization": "Bearer " + self._token}
 
-    async def _create_proxy_channel(self, ssl_context: ssl.SSLContext | bool) -> Channel:
+    async def _create_proxy_channel(self, ssl_context: ssl.SSLContext | ssl.DefaultVerifyPaths | bool) -> Channel:
         """
         Create a gRPC channel using the proxy manager.
 
@@ -98,7 +108,7 @@ class CVClientProtocol(
             Configured gRPC Channel instance.
         """
         # Create the channel first
-        channel = Channel(host=self._servers[0], port=self._port, ssl=ssl_context)
+        channel = Channel(host=self._servers[0], port=self._port, ssl=ssl_context, config=self._grpclib_channel_config)
 
         # Create custom connector that uses proxy
         async def proxy_connection() -> H2Protocol:
@@ -126,13 +136,36 @@ class CVClientProtocol(
         channel._create_connection = proxy_connection
         return channel
 
-    def _ssl_context(self) -> ssl.SSLContext | bool:
+    @property
+    def _grpclib_channel_config(self) -> Configuration:
+        """Build the grpclib Channel `config` from the optional gRPC channel configuration."""
+        if self._grpc_channel_configuration is None:
+            return Configuration()
+        return self._grpc_channel_configuration.as_grpclib_configuration()
+
+    def _resolve_tls_settings(self) -> CVTLSSettings:
         """
-        Initialize the default SSL context with relaxed verification if needed.
+        Resolve TLS settings for grpclib and requests based on `verify_certs` and `use_system_certs`.
+
+        `verify_certs=False`: No verification on either transport.
+            grpclib gets a permissive SSLContext (CERT_NONE, no hostname check).
+            requests gets `verify=False`.
+
+        `verify_certs=True`, `use_system_certs=False`: certifi.
+            grpclib gets `True` and resolves to certifi internally.
+            requests gets `verify=True`. If `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE` is set, requests uses that bundle instead of certifi (this override only
+                applies when `verify is True`, never when it is an explicit path).
 
-        Otherwise we just return True.
-        The return value (The default ssl context or True) will be passed to grpclib.
-        Requests will pick it up from ssl lib itself.
+        `verify_certs=True`, `use_system_certs=True`: OS trust store via `ssl.get_default_verify_paths()`, which already reads
+            `SSL_CERT_FILE` / `SSL_CERT_DIR` and falls back to compiled-in defaults.
+
+            grpclib gets the full `DefaultVerifyPaths` and loads both `cafile` and `capath`. The result is additive (OS defaults plus any user env overrides).
+
+            requests takes a single path. Default rule: `cafile or capath`. Override: when user sets `SSL_CERT_DIR` -> return `capath` instead,
+                otherwise the OS-default cafile overrides it. This is the reason why resolver reads env vars even though `get_default_verify_paths()`
+                already does it behind the scene.
+
+            On systems with no usable trust store (distroless) -> warn and fall back to certifi for both transports.
         """
         if not self._verify_certs:
             # Accepting SonarLint issue: We are purposely implementing no verification of certs.
@@ -140,9 +173,25 @@ class CVClientProtocol(
             context.check_hostname = False
             context.verify_mode = ssl.CERT_NONE  # NOSONAR
             context.set_alpn_protocols(["h2"])
-        else:
-            context = True
-        return context
+            return CVTLSSettings(grpc_ssl=context, requests_verify=False)
+
+        if self._use_system_certs:
+            verify_paths = ssl.get_default_verify_paths()
+            user_set_capath_only = "SSL_CERT_DIR" in environ and "SSL_CERT_FILE" not in environ
+            if user_set_capath_only and verify_paths.capath:
+                return CVTLSSettings(grpc_ssl=verify_paths, requests_verify=verify_paths.capath)
+            if path := (verify_paths.cafile or verify_paths.capath):
+                return CVTLSSettings(grpc_ssl=verify_paths, requests_verify=path)
+            # No usable OS trust store — warn and fall through to the certifi default.
+            LOGGER.warning(
+                "CVClient: 'use_system_certs' is enabled but no system trust store was found "
+                "(neither SSL_CERT_FILE/SSL_CERT_DIR nor OpenSSL's compiled-in default paths "
+                "resolve to a readable file or directory). Falling back to the 'certifi' bundle for "
+                "both gRPC and REST. To use the OS trust store, install a CA bundle package "
+                "(e.g. 'ca-certificates') or set SSL_CERT_FILE / SSL_CERT_DIR explicitly."
+            )
+
+        return CVTLSSettings(grpc_ssl=True, requests_verify=True)
 
     def _set_token(self) -> None:
         """
@@ -163,7 +212,7 @@ class CVClientProtocol(
             response = post(  # noqa: S113 TODO: Add configurable timeout
                 "https://" + self._servers[0] + "/cvpservice/login/authenticate.do",
                 auth=(self._username, self._password),
-                verify=self._verify_certs,
+                verify=self._tls.requests_verify,
                 proxies=self._proxy_manager.get_requests_proxies() if self._proxy_manager is not None else None,
                 json={},
             )
@@ -194,7 +243,7 @@ class CVClientProtocol(
             response = get(  # noqa: S113 TODO: Add configurable timeout
                 "https://" + self._servers[0] + "/cvpservice/cvpInfo/getCvpInfo.do",
                 headers={"Authorization": f"Bearer {self._token}", "User-Agent": self._get_user_agent()},
-                verify=self._verify_certs,
+                verify=self._tls.requests_verify,
                 proxies=self._proxy_manager.get_requests_proxies() if self._proxy_manager is not None else None,
                 json={},
             )
@@ -250,10 +299,12 @@ class CVClient(CVClientProtocol):
         password: str | None = None,
         port: int = 443,
         verify_certs: bool = True,
+        use_system_certs: bool = False,
         proxy_host: str | None = None,
         proxy_port: int = 8080,
         proxy_username: str | None = None,
         proxy_password: str | None = None,
+        grpc_channel_configuration: CVGRPCChannelConfiguration | None = None,
     ) -> None:
         """
         CVClient is a high-level API library for using CloudVision Resource APIs.
@@ -268,10 +319,15 @@ class CVClient(CVClientProtocol):
             password: Password to use for authentication if token is not set.
             port: TCP port to use for the connection.
             verify_certs: Disables SSL certificate verification if set to False. Not recommended for production.
+            use_system_certs: Use system certificates and honor overrides with `SSL_CERT_FILE` and
+                `SSL_CERT_DIR`. Prefer the OS trust store over the bundled `certifi` Python package
+                (certifi is only used as a fallback when the OS provides no usable trust store).
+                Applied to both the gRPC channel and the REST calls. Ignored when `verify_certs=False`.
             proxy_host: HTTP proxy hostname.
             proxy_port: HTTP proxy port.
             proxy_username: Proxy authentication username.
             proxy_password: Proxy authentication password.
+            grpc_channel_configuration: Optional gRPC channel configuration settings.
         """
         if isinstance(servers, list):
             self._servers = servers
@@ -283,7 +339,11 @@ class CVClient(CVClientProtocol):
         self._username = username
         self._password = password
         self._verify_certs = verify_certs
+        self._use_system_certs = use_system_certs
+        self._grpc_channel_configuration = grpc_channel_configuration
         self._proxy_manager = None
+        # Resolve TLS settings.
+        self._tls = self._resolve_tls_settings()
 
         # Initialize proxy manager if proxy is configured
         if proxy_host is not None:

pyavd/_cv/client/async_decorators.py

@@ -16,7 +16,8 @@ from typing import TYPE_CHECKING, Any, ClassVar, ParamSpec, TypeVar, get_args, g
 from grpclib import Status
 from grpclib.exceptions import GRPCError, StreamTerminatedError
 
-from pyavd._cv.client.exceptions import CVClientBulkAPIError, CVClientException, CVGRPCError, CVResourceNotFound, CVTimeoutError
+from pyavd._cv.client.exceptions import CVClientBulkAPIError, CVClientException, CVClientInvalidServerName, CVGRPCError, CVResourceNotFound, CVTimeoutError
+from pyavd._cv.constants import CV_REGION_TO_SERVER_MAP, CVAAS_API_PREFIX, CVAAS_STREAMING_PREFIX
 from pyavd._utils import batch
 
 from .constants import CVAAS_VERSION_STRING
@@ -269,6 +270,17 @@ class GRPCRequestHandler:
                                     new_exception.size = int(matches.group("size"))
                                     raise new_exception
 
+                            case Status.UNKNOWN:
+                                caller = call_args[0]
+                                invalid_cvaas_fqdn, hint_msg = self._invalid_cvaas_fqdn(
+                                    getattr(caller, "_servers", []),
+                                    getattr(caller, "_cv_version", None) or CvVersion(CVAAS_VERSION_STRING),
+                                )
+                                if invalid_cvaas_fqdn:
+                                    raise CVClientInvalidServerName(hint_msg)
+
+                                # gRPC UNKNOWN received from non-CVaaS endpoint or correctly configured CVaaS
+                                raise CVGRPCError(*e.args, call_args, call_kwargs)
                             case _:
                                 # All other gRPC errors are converted to CVGRPCError
                                 raise CVGRPCError(*e.args, call_args, call_kwargs)
@@ -383,3 +395,49 @@ class GRPCRequestHandler:
 
         if found_errors:
             raise CVClientBulkAPIError(func_name, found_errors)
+
+    def _invalid_cvaas_fqdn(self, cv_servers: list[str], cv_version: CvVersion) -> tuple[bool, str]:
+        """
+        Check if targeted CVaaS FQDN is invalid.
+
+        Args:
+            cv_servers: List of configured CloudVision server FQDNs. Only the first entry is inspected.
+            cv_version: Version negotiated with the connected CloudVision server. Used to suppress CVaaS-specific
+                hints when an arista.io FQDN actually resolves to an on-prem CVP (spoofed DNS zone).
+
+        Returns:
+            A tuple of <bool> and <str>, indicating if FQDN of the API endpoint is invalid and a hint explaining invalidity details and possible mitigation.
+        """
+        first_cv_server = cv_servers[0] if cv_servers else ""
+        if not first_cv_server.endswith("arista.io"):
+            return False, ""
+
+        # Guard against locally-spoofed arista.io DNS zone pointing to an on-prem CVP
+        if cv_version.version != CVAAS_VERSION_STRING:
+            return False, ""
+
+        base_fqdns = set(CV_REGION_TO_SERVER_MAP.values())
+        prefix, _, base = first_cv_server.partition(".")
+
+        if base in base_fqdns:
+            # Correctly configured API endpoint
+            if prefix == CVAAS_API_PREFIX:
+                return False, ""
+            # Target CVaaS is pointing to the streaming endpoint
+            if prefix == CVAAS_STREAMING_PREFIX:
+                return True, (
+                    f"CVaaS FQDN '{first_cv_server}' is pointing to the streaming endpoint. Please use API endpoint '{CVAAS_API_PREFIX}.{base}' instead."
+                )
+
+        # Target CVaaS is missing api prefix
+        if first_cv_server in base_fqdns:
+            return True, (
+                f"CVaaS FQDN '{first_cv_server}' is missing the required '{CVAAS_API_PREFIX}.' prefix. "
+                f"Please use '{CVAAS_API_PREFIX}.{first_cv_server}' instead."
+            )
+
+        # Unknown arista.io FQDN
+        return True, (
+            f"Provided CVaaS FQDN '{first_cv_server}' may be incorrect. "
+            "Please check 'https://www.arista.io/help' for the full list of supported CVaaS clusters."
+        )

pyavd/_cv/client/exceptions.py

@@ -89,3 +89,7 @@ class CVClientBulkAPIError(CVClientException):
 
 class CVGRPCError(CVClientException):
     """GRPC call failed."""
+
+
+class CVClientInvalidServerName(CVClientException):
+    """CloudVision server FQDN is invalid."""

pyavd/_cv/client/models.py

@@ -1,6 +1,7 @@
 # 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.
+import ssl
 from dataclasses import dataclass
 from typing import Literal
 
@@ -21,6 +22,16 @@ ELEMENT_TYPE_TO_STRING_MAP = {
 }
 
 
+@dataclass(frozen=True)
+class CVTLSSettings:
+    """Resolved TLS settings for a CVClient, used for the gRPC channel and REST calls."""
+
+    grpc_ssl: ssl.SSLContext | ssl.DefaultVerifyPaths | bool
+    """Value passed to grpclib's `Channel(ssl=...)`."""
+    requests_verify: bool | str
+    """Value passed to `requests` as `verify=...`."""
+
+
 @dataclass(frozen=True)
 class CVTag:
     """Represent the input model for a CloudVision Tag."""