Skip to content

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.

  • 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.
StatusWhat it means
plannedA draft record for hardware that is not installed yet. MetalSoft ignores DHCP requests from this device.
install_readyMetalSoft answers the device’s DHCP requests, so zero-touch installation starts as soon as the switch powers on.
installing_firmwareThe switch has requested its NOS image and is installing it.
ztpThe NOS is running and the switch is loading its initial configuration from MetalSoft.
register_readyAn installed switch that MetalSoft can reach, queued for registration.
registeringMetalSoft is discovering the device, pushing its configuration and taking the first configuration backup.
activeRegistered and in service. Most device actions require this status.
registration_failedBring-up did not complete. The device keeps its identity and you can retry.
defectiveThe device has been marked as defective, for example before it is replaced.
deletingRemoval is in progress. The device then moves to decommissioned, or its record is removed if you deleted it.
decommissionedThe device is retired. Its record and identity are kept so it can be brought back.

How you add a switch depends on its state and on its driver.

Your switchCreate it with statusWhat happens next
New from the factory, or reset, and not yet rackedplannedNothing until you mark it ready for installation.
New from the factory, or reset, and ready to power on nowinstall_readyZero-touch bring-up starts when it powers on.
Already installed and configured by handregister_readyMetalSoft connects to it and registers it straight away.

Zero-touch bring-up is available only for some drivers. Every other supported driver can register a switch that is already installed.

DriverZero-touch bring-upRegister 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.

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

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.

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.

When the switch is racked and cabled, call:

POST /api/v2/network-devices/{id}/actions/mark-installation-ready

The 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).

Bring-up continues on its own:

TransitionWhat triggers it
install_ready → installing_firmwareThe switch powers on and requests its NOS. MetalSoft assigns its management IP address and serves the image.
installing_firmware → ztpThe switch finishes installing the NOS, reboots and requests its configuration.
ztp → registeringMetalSoft confirms that the initial configuration was applied and that it can connect to the switch.
registering → activeDiscovery, 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).

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.

You have two options when you take a switch out of service:

  • Archive (POST /api/v2/network-devices/{id}/actions/archive) moves the device to decommissioned and 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:

FieldWhen to use it
managementMACRequired only if the archived record has no MAC address.
serialNumberTo identify the device by serial number instead of MAC address.
osTemplateIdTo 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.

These actions control the lifecycle:

ActionEndpointAllowed fromResult
Mark installation readyPOST /api/v2/network-devices/{id}/actions/mark-installation-readyplanned, registration_failedinstall_ready; zero-touch bring-up starts the next time the switch powers on
Start registrationPOST /api/v2/network-devices/{id}/actions/start-registrationplanned, register_ready, registration_failedregister_ready, then registration runs until the device is active
Return to plannedPOST /api/v2/network-devices/{id}/actions/return-to-plannedinstall_ready, decommissionedplanned

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.

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.

TaskEndpoint
List the names of a device’s secretsGET /api/v2/network-devices/{id}/secrets
Read the value of one secretGET /api/v2/network-devices/{id}/secrets/{name}/credentials
Create or replace a secretPATCH /api/v2/network-devices/{id}/secrets
Delete one secretDELETE /api/v2/network-devices/{id}/secrets/{name}
Delete all secretsDELETE /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.

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 DefaultsNow
Create a defaults entry keyed by MAC address or serial numberCreate a network device with status planned, identified by MAC address or serial number
Set the hostname, OS template and custom variables on the defaults entrySet the same fields on the device record
Store default secrets against the MAC address or serial numberSet secrets on the device itself
Wait for an unknown switch to appear and be matchedCall 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.