Network Device Lifecycle

Available from v7.5

This guide details the lifecycle of a network device record within MetalSoft, covering status transitions, zero-touch provisioning workflows, and modern configuration management practices.

What’s New

The following changes significantly enhance how devices are provisioned and managed:

Planned Registration: You can now register a switch before it physically exists. Previously, a record could only be created for hardware that was already installed and configured. You now create the record in planned status first, holding just the device identity, and fill in the rest later.
Zero-Touch Bring-Up: The zero-touch process is driven entirely by the device record itself. When the switch powers on for the first time, MetalSoft automatically recognizes it, installs the network operating system (NOS), pushes the initial configuration, and registers it, requiring no manual login to the physical switch.
Configuration Storage: The dedicated Network Device Defaults feature has been removed. The configuration you used to pre-stage there is now stored directly on the device record itself when using the planned status.
Per-Device Secrets: Credentials and secrets are now managed per individual device through a dedicated set of endpoints, rather than being stored globally or via defaults.

##️ The Device Lifecycle

A device record moves through several distinct statuses that dictate its operational state within MetalSoft.

Statuses Overview

Status	Meaning	Description
`planned`	Draft Record	A draft record for hardware not yet installed. MetalSoft ignores any DHCP request from this device.
`install_ready`	Ready for Zero-Touch	MetalSoft answers this device’s DHCP requests, initiating the zero-touch installation process immediately upon power-on.
`installing_firmware`	Firmware Installation	The switch has requested and is currently installing its network operating system image.
`ztp`	Configuration Loading	The NOS is installed and running; the switch is loading its initial configuration from MetalSoft.
`register_ready`	Ready for Registration	A switch that is already physically installed and connectable to MetalSoft, queued to start registration manually.
`registering`	Active Provisioning	MetalSoft is actively discovering the device, pushing configuration, and taking the first configuration backup.
`active`	In Service	The device is fully registered and in production service. Most advanced actions require this status.
`registration_failed`	Failure State	Bring-up did not complete successfully. The device keeps its identity and can be retried from this state.
`deleting`	Removal Pending	Removal process is underway. The device will either move to `decommissioned` or the record may be removed entirely, depending on the action taken.
`decommissioned`	Retired but Archived	The device is retired but its record is kept with all identity data. It can be returned to `planned` and brought up again without re-entering information.

Zero-Touch Bring-Up Workflow (Planned Devices)

This path describes the automated process for a switch arriving from the factory or undergoing a full reset, moving through defined statuses in sequence.

Lifecycle Path: planned $\rightarrow$ install_ready $\rightarrow$ installing_firmware $\rightarrow$ ztp $\rightarrow$ registering $\rightarrow$ active

Step	Trigger	Status Transition	Description
Create Record	Initial setup by user.	N/A	You create the device with the initial status of `planned`. Only the driver, MAC address, or serial number are required at this stage.
Mark Installation Ready	User calls API action.	`planned` $\rightarrow$ `install_ready`	From this moment, MetalSoft begins answering DHCP requests for this device.
OS Installation	Device powers on.	`install_ready` $\rightarrow$ `installing_firmware`	The switch asks for its operating system image. MetalSoft assigns a management IP address and serves the necessary NOS image.
Configuration Load	OS installation complete, device reboots.	`installing_firmware` $\rightarrow$ `ztp`	The switch finishes installing the OS and asks for its initial configuration details.
Registration Start	MetalSoft validates config load.	`ztp` $\rightarrow$ `registering`	MetalSoft confirms that the initial configuration was applied successfully and can connect to the device.
Completion	Discovery, push, and backup complete.	`registering` $\rightarrow$ `active`	All discovery, configuration pushing, and the first configuration backup are successfully completed.

Note: If a switch already has its operating system installed, it will skip the installing_firmware step and proceed directly from install_ready to ztp. No manual intervention is needed after marking the device as installation ready.

Adding an Already Configured Device

If you have physically installed and configured a switch by hand, there is no zero-touch stage. Use the register_ready status when creating the device record, providing its management address, credentials, and driver information. MetalSoft will connect to it immediately for discovery and registration.

Decommissioning a Device

Archive (decommissioned): This keeps the device’s record entirely intact. The device’s identity (MAC, hostname, serial number, etc.) is preserved. A decommissioned switch can be returned to planned and brought up again without re-entering any information. Its management IP, loopback, VTEP, and ASN are released.
Delete: This removes the device record entirely from the system.

New Device Actions & Endpoints

These endpoints allow administrators to control specific stages of the lifecycle process programmatically.

Action	Endpoint	Accepted From Statuses	Resulting Status	Description
Mark Installation Ready	`POST /network-devices/{id}/actions/mark-installation-ready`	`planned`, `registration_failed`	`install_ready`	Triggers the zero-touch install when the device powers on next.
Start Registration	`POST /network-devices/{id}/actions/start-registration`	`planned`, `register_ready`, `registration_failed`	`registering` (via `register_ready`)	Initiates full discovery and configuration for an already installed switch.
Return to Planned	`POST /network-devices/{id}/actions/return-to-planned`	`install_ready`, `decommissioned`	`planned`	Resets the device, allowing it to restart the entire zero-touch sequence.

Key Workflow Actions

Mark installation ready: Moves a device from a draft or failed state (planned, registration_failed) to install_ready. The install begins upon power-up.
Start registration: Takes an already installed device into the registering phase.
Return to planned: Resets both installation and deployment status, making it eligible for zero-touch provisioning again.

##️ Device Secrets Management

Secrets are sensitive values (e.g., API tokens, passwords) referenced by your OS templates or configuration assets during the bring-up process.

Storage Model: Secrets must be set per device. There is no global list or defaults keyed by MAC address.
Operation Endpoints:

Operation	Endpoint	Description
List Secret Names	`GET /network-devices/{id}/secrets`	Returns a list of secret names configured for the device.
Read One Secret Value	`GET /network-devices/{id}/secrets/{name}/credentials`	Retrieves the actual value of a specified secret name. Requires read permission on management credentials.
Create/Update Secret	`PATCH /network-devices/{id}/secrets`	Creates or updates an existing secret for the device.
Delete One Secret	`DELETE /network-devices/{id}/secrets/{name}`	Removes a specific secret value from the device record.
Delete All Secrets	`DELETE /network-devices/{id}/secrets`	Clears all secrets associated with the device.

Configuration: From Defaults to Planned Records

The previous mechanism of Network Device Defaults is deprecated and has been replaced by using the planned device record itself.

Feature	Old Way (Defaults)	New Way (Planned Record)
Pre-staging Config	Creating a default entry keyed by MAC/Serial, containing config details.	Create the network device record with status `planned`, populated with the required hostname, OS template, and custom variables.
Secrets Storage	Storing secrets against a MAC address or Serial Number key in a global defaults table.	Set secrets directly on the specific device record using dedicated endpoints.
Availability Control	Wait for an unknown switch to appear and be matched by the default entry.	You control when installation is allowed by manually calling `Mark installation ready` on the planned record.

The advantages of the new model are that the device is visible in the list from the moment you plan it, it has a stable reference identifier (id), and its eligibility for deployment is explicitly controlled via API calls.

Driver Capabilities Matrix

Not all drivers support every lifecycle path. The endpoint GET /network-devices/drivers/capabilities returns a detailed capabilities list.

Capability	Supporting Drivers	Description
Zero-touch bring-up and registration	Cumulus Linux, Cisco NX9000, SONiC Enterprise	Supports the full automated path from `planned` to `active`.
Registration only (Device must be installed)	Arista EOS, Brocade, Cisco ACI, Cisco NDFC, JunOS, NVIDIA UFM, Dell OS10	These drivers require a switch that is already physically present. Use the `register_ready` status to bypass zero-touch stages.

️ Limitation: Drivers in the “Registration only” group cannot use the Mark installation ready action. Always create devices with the appropriate initial status (register_ready) if this driver group applies.