acex-devkit 2.10.0__tar.gz → 2.11.0__tar.gz

{acex_devkit-2.10.0 → acex_devkit-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acex-devkit
-Version: 2.10.0
+Version: 2.11.0
 Summary: ACE-X DevKit - Development kit for building ACE-X drivers and plugins
 License: AGPL-3.0
 Keywords: automation,devkit,sdk,drivers,plugins

{acex_devkit-2.10.0 → acex_devkit-2.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "acex-devkit"
-version = "2.10.0"
+version = "2.11.0"
 description = "ACE-X DevKit - Development kit for building ACE-X drivers and plugins"
 authors = ["Johan Lahti <johan.lahti@acebit.se>"]
 readme = "README.md"

{acex_devkit-2.10.0 → acex_devkit-2.11.0}/src/acex_devkit/__init__.py

@@ -1,6 +1,8 @@
 """ACE-X DevKit - Development kit for building ACE-X drivers and plugins."""
 
-__version__ = "1.0.0"
+import importlib.metadata
+
+__version__ = importlib.metadata.version("acex-devkit")
 
 from acex_devkit.drivers import (
     NetworkElementDriver,

{acex_devkit-2.10.0 → acex_devkit-2.11.0}/src/acex_devkit/drivers/base.py

@@ -4,7 +4,6 @@ from abc import ABC, abstractmethod
 from contextlib import contextmanager
 from typing import Any
 
-from acex_devkit.models.management_connection import ManagementConnection
 from acex_devkit.models.node_response import NodeListItem
 
 
@@ -50,12 +49,12 @@ class TransportBase(ABC):
 
     Args:
         node: The node instance (identity, hostname, vendor, os, ned_id)
-        connection: Management connection (target_ip, connection_type)
+        target_ip: Management IP or hostname of the device
         **kwargs: Future use (credentials, options, etc.)
     """
 
     @contextmanager
-    def session(self, connection: ManagementConnection, **kwargs):
+    def session(self, target_ip: str, **kwargs):
         """Open a reusable session for multiple ops on one device.
 
         Default is a no-op: methods continue to open/close per call.
@@ -65,20 +64,20 @@ class TransportBase(ABC):
         yield self
 
     @abstractmethod
-    def get_config(self, node: NodeListItem, connection: ManagementConnection, **kwargs) -> str:
+    def get_config(self, node: NodeListItem, target_ip: str, **kwargs) -> str:
         """Fetch the full running configuration from a device."""
         pass
 
     @abstractmethod
-    def send_config(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> str:
+    def send_config(self, node: NodeListItem, target_ip: str, commands: list[str], **kwargs) -> str:
         """Apply configuration commands to a device."""
         pass
 
-    def execute(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> list[str]:
+    def execute(self, node: NodeListItem, target_ip: str, commands: list[str], **kwargs) -> list[str]:
         """Run arbitrary commands and return output per command. Opt-in per driver."""
         raise NotImplementedError(f"{self.__class__.__name__} does not implement execute()")
 
-    def get_lldp_neighbors(self, node: NodeListItem, connection: ManagementConnection, **kwargs) -> list[dict]:
+    def get_lldp_neighbors(self, node: NodeListItem, target_ip: str, **kwargs) -> list[dict]:
         """Fetch LLDP/CDP neighbor table from a device.
 
         Returns list of dicts with keys:

{acex_devkit-2.10.0 → acex_devkit-2.11.0}/src/acex_devkit/drivers/base_driver.py

@@ -3,7 +3,6 @@ from typing import Any
 
 from acex_devkit.models.asset import Asset
 from acex_devkit.models.composed_configuration import ComposedConfiguration
-from acex_devkit.models.management_connection import ManagementConnection
 from acex_devkit.models.node_response import NodeListItem
 
 
@@ -22,16 +21,16 @@ class RendererBase(ABC):
 
 class TransportBase(ABC):
     @abstractmethod
-    def get_config(self, node: NodeListItem, connection: ManagementConnection, **kwargs) -> str:
+    def get_config(self, node: NodeListItem, target_ip: str, **kwargs) -> str:
         """Fetch the full running configuration from a device."""
         pass
 
     @abstractmethod
-    def send_config(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> str:
+    def send_config(self, node: NodeListItem, target_ip: str, commands: list[str], **kwargs) -> str:
         """Apply configuration commands to a device."""
         pass
 
-    def execute(self, node: NodeListItem, connection: ManagementConnection, commands: list[str], **kwargs) -> list[str]:
+    def execute(self, node: NodeListItem, target_ip: str, commands: list[str], **kwargs) -> list[str]:
         """Run arbitrary commands. Opt-in per driver."""
         raise NotImplementedError(f"{self.__class__.__name__} does not implement execute()")
 

acex_devkit-2.11.0/src/acex_devkit/models/job.py

@@ -0,0 +1,96 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, model_validator
+
+from acex_devkit.models.base import PersistedResponse
+
+
+class JobState(StrEnum):
+    queued = "queued"
+    running = "running"
+    succeeded = "succeeded"
+    failed = "failed"
+    cancelled = "cancelled"
+
+
+class JobSubjectType(StrEnum):
+    """The kind of object a job is about, for finding every job that concerns it."""
+
+    node = "node"
+    logical_node = "logical_node"
+    asset = "asset"
+
+
+class JobBase(BaseModel):
+    #: The job type, e.g. "acex.ztp.discover". Also the Celery task name.
+    type: str
+    #: Set on the jobs of a batch. Only one level: a child has no children.
+    parent_id: int | None = None
+    #: Derived from the job type and its data, never set by the caller.
+    subject_type: JobSubjectType | None = None
+    subject_id: int | None = None
+    #: Typed per job type, and only ids: workers fetch the rest from the API.
+    data: dict | None = None
+    #: Typed per job type; set when a worker reports success.
+    result: dict | None = None
+    state: JobState = JobState.queued
+    attempts: int = 0
+    error: str | None = None
+    #: The user's `sub`, or "system" for jobs the backend creates itself.
+    created_by: str
+    claimed_by: str | None = None
+    #: The `sub` of whoever cancelled the job.
+    cancelled_by: str | None = None
+    created_at: datetime
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class JobResponse(PersistedResponse, JobBase):
+    #: On a batch's parent: how many of its jobs are in each state. The
+    #: parent's own state is derived from these.
+    children: dict[JobState, int] | None = None
+
+
+class JobSummary(PersistedResponse):
+    """A job in a listing. Its data, result and error are fetched one job at a time."""
+
+    type: str
+    state: JobState
+    parent_id: int | None = None
+    subject_type: JobSubjectType | None = None
+    subject_id: int | None = None
+    attempts: int
+    claimed_by: str | None = None
+    created_at: datetime
+    finished_at: datetime | None = None
+    children: dict[JobState, int] | None = None
+
+
+class JobPurge(BaseModel):
+    """How many jobs a purge deleted, batch parents included."""
+
+    deleted: int
+
+
+class JobUpdate(BaseModel):
+    """What a worker reports on a job it runs: that it has claimed it, or how it ended."""
+
+    #: running claims the job; succeeded and failed finish it.
+    state: Literal[JobState.running, JobState.succeeded, JobState.failed]
+    #: With succeeded, for job types that give a result.
+    result: dict | None = None
+    #: With failed: why.
+    error: str | None = None
+
+    @model_validator(mode="after")
+    def _fits_state(self) -> "JobUpdate":
+        if self.result is not None and self.state != JobState.succeeded:
+            raise ValueError("a result is only reported with state succeeded")
+        if self.state == JobState.failed and not self.error:
+            raise ValueError("state failed needs an error")
+        if self.error is not None and self.state != JobState.failed:
+            raise ValueError("an error is only reported with state failed")
+        return self

{acex_devkit-2.10.0 → acex_devkit-2.11.0}/src/acex_devkit/models/node_response.py

@@ -27,15 +27,19 @@ class NodeAdminStatus(StrEnum):
 
 
 class NodeProvisionStatus(StrEnum):
-    """Where the node's device is in the provisioning lifecycle. Set by the provisioning flow, not by operators."""
+    """Where the node's device is in the provisioning lifecycle. Set by the provisioning flow, not by operators.
 
-    unprovisioned = "unprovisioned"  # never provisioned by ACEX
-    adopted = "adopted"  # brownfield: already running when brought under management
-    pending = "pending"  # ZTP armed, waiting for the device to show up
-    bootstrapping = "bootstrapping"  # bootstrap config fetched, waiting for SSH reachability
+    With no provisioning under way the node sits in a steady state (unprovisioned, adopted,
+    provisioned). While it is in ZTP it is enrolled, provisioning or failed; an enrolled
+    node's ZTP stage (awaiting device, awaiting approval, ready) comes from its asset.
+    """
+
+    unprovisioned = "unprovisioned"  # steady: no provisioning requested, never provisioned by ACEX
+    adopted = "adopted"  # steady: brownfield, already running when brought under management
+    enrolled = "enrolled"  # in ZTP, waiting for its device to be discovered, approved and provisioned
     provisioning = "provisioning"  # full config being pushed and verified
-    provisioned = "provisioned"  # provisioned by ACEX and verified
-    failed = "failed"
+    provisioned = "provisioned"  # steady: provisioned by ACEX and verified
+    failed = "failed"  # in ZTP, stuck until retried or cancelled; the reason is on the job
 
 
 class NodeBase(BaseModel):

acex_devkit-2.11.0/src/acex_devkit/models/worker.py

@@ -0,0 +1,44 @@
+from pydantic import BaseModel, Field, SecretStr, field_serializer
+
+
+class JobTypeInfo(BaseModel):
+    """A job type the backend creates, and the queue that carries it."""
+
+    name: str
+    queue: str
+
+
+class WorkerConnectRequest(BaseModel):
+    """What a starting worker can run, so it is told which queues carry those jobs."""
+
+    job_types: list[str] = Field(min_length=1)
+
+
+class BrokerConnection(BaseModel):
+    """The RabbitMQ broker a worker consumes from."""
+
+    host: str
+    port: int
+    vhost: str
+    user: str | None = None
+    #: Hidden in repr and logs, but sent in full: the worker has to log in with it.
+    password: SecretStr | None = None
+
+    @field_serializer("password", when_used="json")
+    def _send_password(self, password: SecretStr | None) -> str | None:
+        return password.get_secret_value() if password is not None else None
+
+
+class QueueDeclaration(BaseModel):
+    """A queue as the backend declares it. A worker must declare it the same
+    way: RabbitMQ refuses a second declaration with different arguments."""
+
+    name: str
+    durable: bool
+
+
+class WorkerConnection(BaseModel):
+    """Everything a worker needs to start consuming, handed out by the API."""
+
+    broker: BrokerConnection
+    queues: list[QueueDeclaration]

acex_devkit-2.11.0/src/acex_devkit/models/ztp.py

@@ -0,0 +1,434 @@
+from datetime import datetime
+from enum import StrEnum
+from ipaddress import IPv4Address, IPv4Network
+
+from pydantic import BaseModel, IPvAnyAddress
+
+from acex_devkit.models.base import PersistedResponse
+from acex_devkit.models.job import JobResponse, JobState
+
+
+class ZtpMethod(StrEnum):
+    """How a device bootstraps itself. One OS can have several methods."""
+
+    #: The device downloads and runs a Python script (Cisco IOS XE guestshell).
+    cisco_iosxe_python = "cisco_iosxe_python"
+
+
+class ZtpMethodInfo(BaseModel):
+    """How a ZTP method is presented to an administrator."""
+
+    label: str
+    description: str
+
+
+#: One entry per ZtpMethod; add one with every new method.
+ZTP_METHOD_INFO: dict[ZtpMethod, ZtpMethodInfo] = {
+    ZtpMethod.cisco_iosxe_python: ZtpMethodInfo(
+        label="Cisco IOS XE — Python",
+        description="The device downloads ztp.py over HTTP and runs it in guestshell.",
+    ),
+}
+
+
+class ZtpMethodResponse(ZtpMethodInfo):
+    """A ZTP method, and what an administrator has chosen for it."""
+
+    method: ZtpMethod
+    #: The NED discovery uses for devices that bootstrap this way. None until one is chosen.
+    ned: str | None = None
+    #: The temporary login the bootstrap gives a device and discovery logs in with,
+    #: until onboarding rotates it. Not a secret: the bootstrap is public.
+    bootstrap_username: str | None = None
+    bootstrap_password: str | None = None
+    #: Devices whose vendor class matches no mapping bootstrap with this method. At most one method is.
+    is_default: bool = False
+    updated_by: str | None = None
+    updated_at: datetime | None = None
+
+
+class ZtpMethodUpdate(BaseModel):
+    """Change what is chosen for a ZTP method. Only the fields sent change; None clears one."""
+
+    ned: str | None = None
+    bootstrap_username: str | None = None
+    bootstrap_password: str | None = None
+    #: True makes this the default method, and no other; false leaves no default.
+    is_default: bool | None = None
+
+
+class ZtpVendorClassMatch(StrEnum):
+    """How the vendor class (option 60) a device sends is compared to a mapped one."""
+
+    exact = "exact"
+    #: The device's vendor class starts with it, for vendors that add model or serial.
+    prefix = "prefix"
+
+
+class ZtpVendorClassCreate(BaseModel):
+    """A DHCP vendor class (option 60) a device may send, and the ZTP method it bootstraps with."""
+
+    #: Free text, matched by the DHCP server as `match` says.
+    vendor_class: str
+    match: ZtpVendorClassMatch = ZtpVendorClassMatch.exact
+    #: None until an administrator maps it.
+    method: ZtpMethod | None = None
+
+
+class ZtpVendorClassUpdate(BaseModel):
+    """Change a vendor class. Only the fields sent change; method None unmaps it."""
+
+    vendor_class: str | None = None
+    match: ZtpVendorClassMatch | None = None
+    method: ZtpMethod | None = None
+
+
+class ZtpVendorClassResponse(PersistedResponse):
+    vendor_class: str
+    match: ZtpVendorClassMatch
+    method: ZtpMethod | None = None
+    updated_by: str | None = None
+    updated_at: datetime | None = None
+
+
+class ZtpDhcpScopeCreate(BaseModel):
+    """An IPv4 network the ZTP DHCP server hands out addresses in."""
+
+    network: IPv4Network
+    #: The addresses handed out, both inclusive, inside the network.
+    pool_start: IPv4Address
+    pool_end: IPv4Address
+    #: Option 3. Inside the network, outside the pool.
+    gateway: IPv4Address
+    #: Option 6.
+    dns_servers: list[IPv4Address] = []
+    #: Option 15.
+    domain_name: str | None = None
+    description: str | None = None
+
+
+class ZtpDhcpScopeUpdate(BaseModel):
+    """Change a scope. Only the fields sent change; None clears an optional one."""
+
+    network: IPv4Network | None = None
+    pool_start: IPv4Address | None = None
+    pool_end: IPv4Address | None = None
+    gateway: IPv4Address | None = None
+    dns_servers: list[IPv4Address] | None = None
+    domain_name: str | None = None
+    description: str | None = None
+
+
+class ZtpDhcpScopeResponse(PersistedResponse, ZtpDhcpScopeCreate):
+    updated_by: str | None = None
+    updated_at: datetime | None = None
+
+
+class ZtpDiscoverData(BaseModel):
+    """Data of an acex.ztp.discover job: a device that fetched its ZTP bootstrap."""
+
+    #: The address the device fetched its bootstrap from, which discovery logs in to.
+    ip: IPvAnyAddress
+    #: The bootstrap method it used. Decides how it is discovered.
+    method: ZtpMethod
+
+
+class ZtpProvisionData(BaseModel):
+    """Data of an acex.ztp.provision job: a node whose approved device gets its full configuration."""
+
+    node_id: int
+    #: The bootstrap method the device used. Decides which bootstrap login provisioning logs in with.
+    method: ZtpMethod
+
+
+class ZtpProvisionResult(BaseModel):
+    """Worker response from accessing the node
+    during provision"""
+
+    lines_sent: int
+    output: str
+
+
+class ZtpDiscoverResult(BaseModel):
+    """Result of an acex.ztp.discover job: what the device says it is.
+
+    Self-reported and unverified, so plain strings: a value ACEX has no enum
+    member for is still worth showing to the administrator who reviews it.
+    """
+
+    serial_number: str
+    vendor: str | None = None
+    hardware_model: str | None = None
+    os: str | None = None
+    os_version: str | None = None
+
+
+class ZtpReviewStatus(StrEnum):
+    """Where a discovery stands with the administrator who has to approve it."""
+
+    unreviewed = "unreviewed"
+    approved = "approved"
+    rejected = "rejected"
+
+
+class ZtpConflictKind(StrEnum):
+    #: The same serial number was reported from another IP.
+    serial_on_other_ip = "serial_on_other_ip"
+    #: The same IP has reported another serial number.
+    ip_with_other_serial = "ip_with_other_serial"
+    #: The serial belongs to a provisioned node: the device may have been reset.
+    serial_of_provisioned_node = "serial_of_provisioned_node"
+
+
+#: Conflicts that put the device's identity in doubt. A bulk approval skips a
+#: discovery with one; it can still be approved on its own.
+IDENTITY_CONFLICTS = frozenset({ZtpConflictKind.serial_on_other_ip, ZtpConflictKind.ip_with_other_serial})
+
+
+class ZtpConflict(BaseModel):
+    """Something about a discovery an administrator should look at before approving it."""
+
+    kind: ZtpConflictKind
+    message: str
+    #: The other discovery involved, for the kinds that compare two.
+    discovery_id: int | None = None
+    #: The node involved, for serial_of_provisioned_node.
+    node_id: int | None = None
+
+
+class ZtpApprovalAction(StrEnum):
+    """What approving a discovery does to the asset with its serial number."""
+
+    #: No asset has the serial; one is created from the reported facts.
+    create = "create"
+    #: The asset exists; the reported facts that differ are written to it.
+    update = "update"
+    #: The asset exists and already matches.
+    unchanged = "unchanged"
+    #: The discovery cannot be approved; `blocked_by` says why.
+    blocked = "blocked"
+
+
+class ZtpFactChange(BaseModel):
+    field: str
+    current: str | None = None
+    reported: str | None = None
+
+
+class ZtpProposedAsset(BaseModel):
+    """The asset as it will be once the discovery is approved."""
+
+    serial_number: str
+    vendor: str | None = None
+    hardware_model: str | None = None
+    os: str | None = None
+    os_version: str | None = None
+    ned_id: str | None = None
+
+
+class ZtpApprovalProposal(BaseModel):
+    """What approving the discovery would do, computed by the same code that approves it."""
+
+    action: ZtpApprovalAction
+    #: The existing asset; None for create and for some blocked proposals.
+    asset_id: int | None = None
+    asset: ZtpProposedAsset | None = None
+    #: For update: the facts that will be written.
+    changes: list[ZtpFactChange] = []
+    blocked_by: list[str] = []
+    #: Identifies this exact proposal. Sent back on approve, so nothing is
+    #: written that differs from what the administrator saw.
+    hash: str
+
+
+class ZtpDiscoveryResponse(PersistedResponse, ZtpDiscoverResult):
+    """A discovery: the device at `source_ip` says it is `serial_number`."""
+
+    job_id: int | None = None
+    source_ip: str
+    #: The asset the discovery was approved as; None until approved.
+    asset_id: int | None = None
+    #: The node the asset with this serial is bound to, if any. Approval never changes it.
+    node_id: int | None = None
+    #: Hostname of that node's logical node.
+    node_hostname: str | None = None
+    review_status: ZtpReviewStatus
+    reviewed_by: str | None = None
+    reviewed_at: datetime | None = None
+    created_at: datetime
+    conflicts: list[ZtpConflict] = []
+    #: What approving would do; None once reviewed.
+    proposal: ZtpApprovalProposal | None = None
+
+
+class ZtpApproveRequest(BaseModel):
+    #: The hash of the proposal the administrator saw. Approval is refused if it
+    #: no longer matches. Leave out to approve whatever the proposal now is.
+    proposal_hash: str | None = None
+
+
+class ZtpBulkApproveItem(BaseModel):
+    discovery_id: int
+    proposal_hash: str | None = None
+
+
+class ZtpBulkApprove(BaseModel):
+    items: list[ZtpBulkApproveItem]
+    #: Work out what would happen without writing anything.
+    dry_run: bool = False
+
+
+class ZtpBulkReject(BaseModel):
+    discovery_ids: list[int]
+
+
+class ZtpBulkOutcome(StrEnum):
+    approved = "approved"
+    #: A dry run would approve it.
+    would_approve = "would_approve"
+    rejected = "rejected"
+    skipped = "skipped"
+
+
+class ZtpBulkItemResult(BaseModel):
+    discovery_id: int
+    outcome: ZtpBulkOutcome
+    #: Why it was skipped.
+    reason: str | None = None
+    proposal: ZtpApprovalProposal | None = None
+
+
+class ZtpBulkResult(BaseModel):
+    results: list[ZtpBulkItemResult]
+    #: Counts per proposal action (approve) and per outcome.
+    summary: dict[str, int]
+
+
+class ZtpCallStage(StrEnum):
+    """Where a device that called in stands before anyone reviews it, from its latest discovery job."""
+
+    #: Fetched its bootstrap; no worker has picked up the discovery yet.
+    waiting = "waiting"
+    #: A worker is logging in to it.
+    discovering = "discovering"
+    #: The worker could not find out what it is.
+    failed = "failed"
+    #: It said what it is; the discovery waits in review.
+    reported = "reported"
+
+
+class ZtpCallAttempt(BaseModel):
+    """One bootstrap fetch and the discovery job it started."""
+
+    job_id: int
+    state: JobState
+    attempts: int
+    error: str | None = None
+    created_at: datetime
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    #: Set once the worker reported what the device is.
+    discovery_id: int | None = None
+    serial_number: str | None = None
+    review_status: ZtpReviewStatus | None = None
+
+
+class ZtpCall(BaseModel):
+    """A device that called in, by the IP it fetched its bootstrap from.
+
+    A device that reboots calls in again, so one IP gathers several attempts.
+    """
+
+    source_ip: str
+    method: ZtpMethod
+    stage: ZtpCallStage
+    #: When it last fetched its bootstrap.
+    last_seen: datetime
+    #: Newest first.
+    attempts: list[ZtpCallAttempt]
+
+
+class ZtpAssetReadiness(StrEnum):
+    """How far a node's device has come before provisioning, from the discoveries of its serial."""
+
+    #: No discovery of the serial, or only rejected ones.
+    unseen = "unseen"
+    #: The latest discovery waits for an administrator.
+    awaiting_review = "awaiting_review"
+    #: The latest discovery is approved: identity and address are trusted.
+    ready = "ready"
+
+
+class ZtpStage(StrEnum):
+    """Where a node stands in ZTP.
+
+    Before provisioning starts this comes from the asset's readiness; from then
+    on it is the node's provision_status.
+    """
+
+    awaiting_device = "awaiting_device"
+    awaiting_approval = "awaiting_approval"
+    ready = "ready"
+    provisioning = "provisioning"
+    provisioned = "provisioned"
+    failed = "failed"
+    adopted = "adopted"
+    unprovisioned = "unprovisioned"
+
+
+#: The stages a node is in the pipeline for.
+PIPELINE_STAGES = (
+    ZtpStage.awaiting_device,
+    ZtpStage.awaiting_approval,
+    ZtpStage.ready,
+    ZtpStage.provisioning,
+    ZtpStage.failed,
+)
+
+
+class ZtpNodeAsset(BaseModel):
+    id: int
+    serial_number: str
+    vendor: str | None = None
+    hardware_model: str | None = None
+    os: str | None = None
+    os_version: str | None = None
+    ned_id: str | None = None
+
+
+class ZtpPipelineNode(BaseModel):
+    """A node and where it stands in ZTP."""
+
+    node_id: int
+    hostname: str | None = None
+    site: str | None = None
+    admin_status: str
+    provision_status: str
+    #: The status the node had when it was enrolled; cancelling ZTP returns it there.
+    ztp_previous_status: str | None = None
+    stage: ZtpStage
+    #: Why a provisioning node is not getting anywhere: no job, or a job lost on its queue or its worker.
+    stalled: str | None = None
+    #: None when the node is bound to an asset cluster.
+    asset: ZtpNodeAsset | None = None
+    readiness: ZtpAssetReadiness | None = None
+    #: When the device was last discovered.
+    last_seen: datetime | None = None
+    #: The address of the approved discovery, which provisioning uses.
+    approved_ip: str | None = None
+
+
+class ZtpNodeDetail(ZtpPipelineNode):
+    #: Discoveries of the asset's serial, newest first.
+    discoveries: list[ZtpDiscoveryResponse] = []
+    #: Provisioning jobs of the node, newest first.
+    provision_jobs: list[JobResponse] = []
+
+
+class ZtpPipelineSummary(BaseModel):
+    #: Nodes per stage, every node counted once.
+    stages: dict[ZtpStage, int]
+    #: Approved assets not bound to any node: ready for a node to be assigned.
+    pool: int
+    #: Provisioning nodes that are not getting anywhere.
+    stalled: int = 0