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
Section titled “What’s new”- Plan switches before they arrive. You can create a switch record before the hardware is installed. A planned record holds only the identity of the device (its MAC address or serial number); you add the rest of the details when you have them.
- Zero-touch bring-up from the device record. When a planned switch powers on for the first time, MetalSoft recognizes it, installs the network operating system (NOS), applies the initial configuration and registers it. Nobody needs to log in to the switch.
- You decide when installation starts. A planned switch is ignored until you mark it ready for installation, so you can prepare records weeks in advance.
- Retired switches keep their identity. A decommissioned switch can be returned to planned and brought up again without re-entering its details.
- Secrets are stored per device. Passwords and keys that the switch configuration needs are set on each device.
Device statuses
Section titled “Device statuses”| Status | What it means |
|---|---|
planned | A draft record for hardware that is not installed yet. MetalSoft ignores DHCP requests from this device. |
install_ready | MetalSoft answers the device’s DHCP requests, so zero-touch installation starts as soon as the switch powers on. |
installing_firmware | The switch has requested its NOS image and is installing it. |
ztp | The NOS is running and the switch is loading its initial configuration from MetalSoft. |
register_ready | An installed switch that MetalSoft can reach, queued for registration. |
registering | MetalSoft is discovering the device, pushing its configuration and taking the first configuration backup. |
active | Registered and in service. Most device actions require this status. |
registration_failed | Bring-up did not complete. The device keeps its identity and you can retry. |
defective | The device has been marked as defective, for example before it is replaced. |
deleting | Removal is in progress. The device then moves to decommissioned, or its record is removed if you deleted it. |
decommissioned | The device is retired. Its record and identity are kept so it can be brought back. |
Choose how to add a switch
Section titled “Choose how to add a switch”How you add a switch depends on its state and on its driver.
| Your switch | Create it with status | What happens next |
|---|---|---|
| New from the factory, or reset, and not yet racked | planned | Nothing until you mark it ready for installation. |
| New from the factory, or reset, and ready to power on now | install_ready | Zero-touch bring-up starts when it powers on. |
| Already installed and configured by hand | register_ready | MetalSoft connects to it and registers it straight away. |
Driver support
Section titled “Driver support”Zero-touch bring-up is available only for some drivers. Every other supported driver can register a switch that is already installed.
| Driver | Zero-touch bring-up | Register an installed switch |
|---|---|---|
Cumulus Linux (cumulus_linux) | ✓ | ✓ |
Cisco Nexus 9000 (nexus9000) | ✓ | ✓ |
SONiC Enterprise (sonic_enterprise) | ✓ | ✓ |
Arista EOS (arista_eos) | ✓ | |
Brocade (brocade) | ✓ | |
Cisco ACI (cisco_aci51) | ✓ | |
Cisco NDFC (cisco_ndfc) | ✓ | |
Juniper Junos (junos) | ✓ | |
NVIDIA UFM (nvidia_ufm) | ✓ | |
Dell OS10 (os_10) | ✓ |
To check the drivers on your controller, call GET /api/v2/network-devices/drivers/capabilities. Each driver lists its activationActions: mark-install-ready means zero-touch bring-up is supported, start-registration means an installed switch can be registered.
For a driver without zero-touch support, create the device with status register_ready.
Bring up a new switch with zero touch
Section titled “Bring up a new switch with zero touch”Use this path for a switch that arrives from the factory or has been reset. The device moves through these statuses:
planned → install_ready → installing_firmware → ztp → registering → active
1. Create a planned device
Section titled “1. Create a planned device”Create the device with POST /api/v2/network-devices and "status": "planned". Only the driver and a MAC address or serial number are needed at this stage.
{ "siteId": 1, "status": "planned", "driver": "sonic_enterprise", "managementMAC": "aa:bb:cc:dd:ee:ff"}Add the remaining details whenever you have them, either now or later by updating the device: position, rack location, custom variables and the OS template.
The device appears in the device list straight away and has an ID you can reference. Nothing else happens until you mark it ready for installation.
2. Set the OS template
Section titled “2. Set the OS template”Set osTemplateId to an OS template that uses the ONIE install method. If the osTemplateid is not set correctly, it will be rejected and it will not be moved to installation ready state.
3. Mark the device ready for installation
Section titled “3. Mark the device ready for installation”When the switch is racked and cabled, call:
POST /api/v2/network-devices/{id}/actions/mark-installation-readyThe device moves to install_ready and MetalSoft starts answering its DHCP requests. If you already know the switch is ready, you can skip this step by creating the device with "status": "install_ready" (an ONIE OS template is then required).
4. Power on the switch
Section titled “4. Power on the switch”Bring-up continues on its own:
| Transition | What triggers it |
|---|---|
install_ready → installing_firmware | The switch powers on and requests its NOS. MetalSoft assigns its management IP address and serves the image. |
installing_firmware → ztp | The switch finishes installing the NOS, reboots and requests its configuration. |
ztp → registering | MetalSoft confirms that the initial configuration was applied and that it can connect to the switch. |
registering → active | Discovery, configuration push and the first configuration backup complete. |
If bring-up stops, the device moves to registration_failed. Fix the cause and retry it (see Device actions).
Add a switch that is already installed
Section titled “Add a switch that is already installed”For a switch you installed and configured by hand there is no zero-touch stage. Create the device with "status": "register_ready" and include:
- the driver
- the management address and port
- the management credentials
- the position in the topology
- the identifier string
MetalSoft connects to the switch, discovers it and registers it. When registration finishes, the device is active.
If you created the record as planned first, add these details and call POST /api/v2/network-devices/{id}/actions/start-registration.
Retire or reuse a switch
Section titled “Retire or reuse a switch”You have two options when you take a switch out of service:
- Archive (
POST /api/v2/network-devices/{id}/actions/archive) moves the device todecommissionedand keeps its record. Its identity is preserved: MAC address, hostname, serial number, custom variables and OS template. Its management address, loopback address, VTEP address and ASN are released for reuse. - Delete (
DELETE /api/v2/network-devices/{id}) removes the record entirely.
To bring a decommissioned switch back, call POST /api/v2/network-devices/{id}/actions/return-to-planned. The device returns to planned with its identity intact, ready for another zero-touch bring-up. In the request body you can supply:
| Field | When to use it |
|---|---|
managementMAC | Required only if the archived record has no MAC address. |
serialNumber | To identify the device by serial number instead of MAC address. |
osTemplateId | To install a different OS template than the stored one. |
Syslog and SNMP are disabled on a device returned to planned, because it is no longer reachable.
Device actions
Section titled “Device actions”These actions control the lifecycle:
| Action | Endpoint | Allowed from | Result |
|---|---|---|---|
| Mark installation ready | POST /api/v2/network-devices/{id}/actions/mark-installation-ready | planned, registration_failed | install_ready; zero-touch bring-up starts the next time the switch powers on |
| Start registration | POST /api/v2/network-devices/{id}/actions/start-registration | planned, register_ready, registration_failed | register_ready, then registration runs until the device is active |
| Return to planned | POST /api/v2/network-devices/{id}/actions/return-to-planned | install_ready, decommissioned | planned |
Use Return to planned on an install_ready device to cancel an installation that has not started yet: MetalSoft stops answering its DHCP requests.
Start registration is rejected while a registration for the same device is already in progress.
These existing actions are unchanged:
- Archive and Delete retire a device.
- Re-provision resets a switch and runs the full installation again.
- Replace moves a configuration onto replacement hardware. See Switch replace.
Device secrets
Section titled “Device secrets”Secrets hold values that your switch configuration needs but that should not be stored in clear text, such as BGP peer group passwords, OSPF keys and SNMP user passwords. A custom variable refers to a secret by name, and MetalSoft injects the value when the switch fetches its configuration.
Secrets are set on each device and start empty. There is no global list and no defaults keyed by MAC address.
| Task | Endpoint |
|---|---|
| List the names of a device’s secrets | GET /api/v2/network-devices/{id}/secrets |
| Read the value of one secret | GET /api/v2/network-devices/{id}/secrets/{name}/credentials |
| Create or replace a secret | PATCH /api/v2/network-devices/{id}/secrets |
| Delete one secret | DELETE /api/v2/network-devices/{id}/secrets/{name} |
| Delete all secrets | DELETE /api/v2/network-devices/{id}/secrets |
To create a secret, or replace one with the same name:
{ "name": "peer_group_backbone_password", "secret": "<value>"}Values are stored encrypted. Listing returns only names. Reading a value requires the same permission as reading a device’s management credentials.
Migrating from Network Device Defaults
Section titled “Migrating from Network Device Defaults”Network Device Defaults let you pre-stage a configuration keyed by MAC address or serial number, so that an unknown switch appearing on the network could be picked up and configured. The feature and its endpoints have been removed.
Planned devices replace it. Instead of storing a configuration that waits for a switch to appear, you create the switch record itself, with the same information, and make it installable when you are ready.
| With Network Device Defaults | Now |
|---|---|
| Create a defaults entry keyed by MAC address or serial number | Create a network device with status planned, identified by MAC address or serial number |
| Set the hostname, OS template and custom variables on the defaults entry | Set the same fields on the device record |
| Store default secrets against the MAC address or serial number | Set secrets on the device itself |
| Wait for an unknown switch to appear and be matched | Call Mark installation ready when you want installation to start |
What you gain:
- The switch is visible in the device list from the moment you plan it.
- It has an ID you can reference in automation and in other MetalSoft objects.
- You control exactly when it becomes eligible for installation.
To migrate, create a planned device for each Network Device Defaults entry you used, copy its fields and secrets onto the device, and mark it ready for installation when the hardware is in place.