Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Juniper Apstra Device Replacement Guide

An essential operation in a working data center network is the need to replace a device that failed or needs to be re-allocated or reused for other purposes. This document describes how to replace a Juniper Apstra managed device using the Apstra GUI and Apstra Terraform Provider.

Replace a Managed Device Using the Apstra GUI

Replacing a managed device in the Apstra GUI is a straightforward set of tasks. The managed devices are abstracted from their role in the fabric using Logical Devices and Interface Maps and are assigned to a blueprint.

Note:

In these procedures, we are replacing the leaf2 device in the GUI. The replacement device (leaf2) is exactly the same physical device (make, model and port configuration) as the device we are replacing.

In this topic, we'll show you how to replace a device using the following methods:

Delete a Leaf with a Still Connected Device

  1. From the left navigation menu in the Apstra GUI, navigate to Blueprints > Blueprint ID > Staged > Physical > Build, then click the Devices icon.

    Physical network topology view with spine switches spine1 and spine2, leaf switches leaf1, leaf2, and leaf3, connected servers, and assigned system IDs.

  2. Click Assigned System IDs - Managed Nodes , then click the Change System IDs Assignments icon.

    Assigned System IDs section showing nodes spine1 spine2 leaf1 leaf2 leaf3 with unique IDs. Red arrow highlights icon to change system ID assignments.

  3. Click the trash icon, then click Update Assignments to unassign leaf2. User interface showing a table for assigning systems with rows for spine2, leaf1, and leaf2. Leaf2 is highlighted with an arrow pointing to a red trash bin icon for removing assignments. Radio buttons offer options: Deploy, Ready, Drain, Undeploy.

    Here we can see that leaf2 in no longer assigned.

  4. Table titled Assigned System IDs - Managed Nodes listing nodes spine1, spine2, leaf1, leaf2, and leaf3 with system IDs. Leaf2 is not assigned, indicated by a yellow warning icon and red box. Toolbar with action icons at the top.

  5. Navigate to the Uncommitted tab and click the Commit rocket icon.

    Uncommitted changes in network tool UI with tabs Dashboard, Analytics, Staged, Active, Time Voyager. Warnings, successful indicators, Commit rocket, Revert buttons. System Node leaf2 marked as CHANGED.

  6. Add a comment if desired, and click Commit.Dialog box to commit changes from Staged to Active with optional description field for new blueprint revision.

  7. When the commit is complete, navigate to the Devices > Managed Devices to return to the Managed Devices table view.

    User interface showing device management section with vertical navigation menu on the left. Highlighted "Managed Devices" with subcategories: System Agents and ZTP Status.

    Leaf2 is now unassigned from the blueprint.

    Screenshot of a network management interface showing device details. Highlighted row: IP 10.28.252.14, hostname leaf2, state OOS-READY, no blueprint assigned.

  8. Uninstall the agent from leaf2 by clicking the Uninstall icon. Network management interface showing device information and agent management options. Device table with highlighted row for IP 10.28.252.14, state OOS-READY, no blueprint assigned. Agent panel with uninstall option marked.

  9. From the pop-up dialog box, click Confirm to uninstall the system agent.

  10. After the uninstall completes, the leaf2 State shows as oos-nocomms with a red x in the Comms column.

    Network management interface showing a table of Juniper devices with details like IP address, device key, profile, hostname, OS, state, comms status, and job state. Highlighted row: IP 10.28.252.14, hostname leaf2, state OOS-NOCOMMS, blueprint not assigned, last job type UNINSTALL, job state SUCCESS.
  11. The final step is to delete the leaf2 device completely from Apstra. There are two steps:

    1. First, click the trash icon in the Device panel.

      User interface with columns labeled Device and Agent. Red arrow points to trash bin icon labeled Delete Device, indicating device deletion action.

      Then click Delete from the following dialog to remove the device.

      Confirmation dialog asking 'Delete this resource' with a red Delete button featuring a trash can icon.

    2. The click the Agent Uninstall icon in the Agent panel.

      User interface with columns labeled Device and Agent; icon in Agent column highlighted with red arrow and labeled Uninstall Agent.

      Then click Confirm from the dialog box to uninstall the agent.

When complete the leaf2 device is removed from the blueprint.

Delete a Failed Leaf Device

For this procedure, we'll delete a that has failed and is no longer communicating with Apstra.

  1. From the left navigation menu in the Apstra GUI, navigate to Blueprints> Staged > Physical > Build and click the Devices icon. If the device already exists in the table, you can skip this step and proceed to Step 2.

  2. Click Assigned System IDs - Managed Nodes > and click the Change System IDs Assignments icon.

  3. Click the trash icon to remove the leaf2 assignment, then click Update Assignments.

  4. Verify that leaf2 is no longer assigned.

  5. Navigate to the Uncommitted tab, then click the Commit rocket icon.

  6. Add a comment if desired, and click Commit.

    User interface for committing blueprint changes with header 'Commit changes from Staged to Active', info box on revisions, description field with 'Remove leaf2 from blueprint', and Commit button.

  7. When the commit is complete, navigate to the Devices > Managed Devices panel to return to the managed devices table view.

    The Leaf2 device is now unassigned from the blueprint.

  8. Click the trash icon in the Device panel.

    Network management interface showing a device table with details like Management IP, Device Key, and State. Device with IP 10.28.252.14 is highlighted, marked OOS-READY, not assigned to a blueprint. Action panel on right includes a trash bin icon to remove failed devices.

  9. Click Delete to remove the failed device (leaf2) from the Managed Devices table.

  10. Delete the agent from the device.

    Select the device from the Managed Devices table (10.28.252.14 in our example) and click the trash icon in the Agent panel to delete the agent.

    Agent panel with icons for actions; trash can icon labeled Delete Agent at bottom; column labeled Actions with three-dot menus.

  11. Click the Force delete check box, then click Delete to force the deletion.

    Apstra interface screenshot: Warning about communication failure with device. Checkbox labeled Force Delete and Delete button highlighted.

You successfully removed the failed device from the blueprint.

Add the Replacement Device to the Blueprint

Let's now take a look at what is required to replace the device back into the blueprint.

  1. From the left navigation menu in the Apstra GUI, navigate to Devices > Managed Devices.

    If the device already exists in the table, you can skip this step and proceed to Step 2.

  2. From the Managed Devices page, click Create Onbox Agents(s). Note that SONIC devices use Onbox Agents.

    Web interface for managing devices showing breadcrumb navigation Devices > Managed Devices, action buttons for creating agents, and a table listing device details like IP, hostname, OS, and status.

  3. Enter the device address, username and password, then click Create.

    Configuration interface for creating Onbox System Agent with fields for device addresses, operation mode, username, and password, plus a Create button.

  4. When the agent completes the installation, click Acknowledge selected systems from the Device panel located above the Managed Devices table.

    User interface for managing devices with toolbar icons. A red arrow highlights the Acknowledge selected systems icon, a checkmark in a circle.

  5. Click Confirm from the dialog box to acknowledge the device.

    Confirmation dialog box titled Acknowledge systems with Cancel and Confirm buttons; pink arrow points to Confirm.

  6. Navigate to Blueprints > Blueprint ID > Staged > Physical > Build, then click the Devices icon.

  7. Click Assigned System IDs - Managed Nodes , then click the Change System IDs Assignments icon.

  8. Select the leaf2 replacement device, click the Deploy radio button, then click Update Assignments.

    User interface for assigning systems in a network tool. Table with columns: Name, Role, Hostname, System ID, Deploy Mode. Each row details system info and deploy state options. Red trash bin icons for deletion. Dropdown for selecting System ID. "leaf2" row highlighted on System ID. Blue Update Assignments button for saving changes.

  9. Commit the change by navigating to the Uncommitted tab, then click the Commit rocket icon.

  10. Comment and click Commit to add the replacement device to your blueprint.

    Note:

    The deployment will take some time to stabilize and any anomalies should eventually converge and disappear.

    Commit changes from Staged to Active. Add a revision description, currently "Replace leaf2". Click the teal Commit button to finalize.

Replace a Device in Apstra Using Apstra Terraform Provider

You can easily replace a device in a blueprint using Apstra Terraform Provider. The below diagram shows the topology we are using in this procedure.

Network topology interface showing 2D spine-leaf architecture with uncommitted changes. Nodes: spine1, spine2, rack_a_001_leaf1. Validation checks passed.

In the following example Terraform configuration, we are replacing the leaf device (rack_a_001_leaf1).
Note:

We assume that the Terraform configuration is applied to the Apstra server and all of the resources for the blueprint are allocated and committed.

Example Terraform Configuration

To replace a device using Terraform:

  1. Remove the following resource block for the device from the Terraform configuration. Note that you cannot remove a device from Apstra without first removing it from your blueprint.
    In this example, we are removing the rack_a_001_leaf1 device.

    Run the terraform apply command to apply the changes.

  2. After the apply is complete, commit the changes.
  3. Update the Terraform configuration with the new information for the replacement device.
    Replace the device_key and the agent_id with the new values.
    You can derive these values in the Apstra GUI by navigating to the Devices > Managed Devices page and selecting the device IP address as follows:
  4. From the Device page, copy the encoded device key and agent ID from the URL string. Web-based device management interface showing device details for IP 10.28.24.235 with tabs for Device, Agent, Config, and Telemetry. Device is active, acknowledged, online, in full control mode, with hostname rack-a-001-leaf1. Red box highlights a long encoded string in the URL.
    To decode the URL string and obtain the new device_key (system-id) and agent ID values, run the pbpaste | base64 --decode command. For example:
    Note:

    You can also derive the agent-id from a data source, from Swagger, or from the Terraform resource that created it.

  5. Once you have replaced the information into Terraform, apply the new configuration:
  6. Commit your changes in the Apstra GUI or in Terraform to finish replacing the device.
Good job! You successfully replaced a device in Apstra.
Note:

In our examples, we removed any existing configuration from the new device and performed a device reboot. However, in some use cases, such as SONiC devices, you might be required to remove any existing configuration from the device.

For example:

See the Juniper Apstra User Guide for information about configuring a SONiC device.