Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Upgrade Device NOS

We highly recommend that you become familiar with this procedure before performing a device NOS upgrade.

NOS Upgrade Overview

To upgrade a device NOS directly in the Apstra environment, you register the new OS image that you obtained from the vendor, then click a button to start the upgrade.


We highly recommend that you upgrade directly from the Apstra environment to ensure that requirements are automatically taken care of for you. If you manually upgrade the NOS outside of the Apstra environment (which is not recommended), you must manually update pristine configuration afterward. Unassign the system ID and set the deploy mode to Undeploy. From the Actions panel at Devices > Managed Devices, click Collect Pristine Config. Then re-assign the system ID and set the deploy mode to Deploy.

For information about supported upgrade paths, see NOS Upgrade Paths in the Reference section.

Apstra software ships with built-in device profiles that support specific OS versions. When you upgrade the Apstra server, you're also updating these device profiles with the OS versions that are supported in the new Apstra version. You can then upgrade the NOS to one of the newly supported versions.

For example, Apstra version 4.0.0 supports Arista EOS versions as shown in the OS version selector (4.(18|20|21|22|23|24)) in the device profile. That is, it supports versions 4.18, 4.20, 4.21, 4.22, 4.23, and 4.24. Whereas, Apstra version 4.02 supports EOS versions 4.18, 4.20, 4.21, 4.22, 4.23, 4.24, and 4.25 (4.(18|20|21|22|23|24|25)). 4.25 is a newly supported version. If you upgrade the Apstra server to version 4.0.2, you can upgrade Arista devices to EOS version 4.25.

However, device profiles that you've created (cloned) yourself, are not managed in the Apstra environment, so they aren't automatically updated with newly supported versions when you upgrade the Apstra version. You'll need to follow a few extra steps as described in the next section.

Before beginning the process, make sure of the following:

  • Make sure that you understand the device configuration lifecycle and that you're comfortable with managing deploy modes.
  • Make sure that the device you're upgrading is being managed by the Apstra software. Navigate to Devices > Managed Devices and confirm that your device is on the list and that it is acknowledged (with a green check mark).
  • Before upgrading NOS, delete any device AAA/TACACS+ configlets from the blueprint. After the upgrade is complete you can reapply them.
  • Make sure that the Admin state of the device is set to NORMAL. Navigate to Devices > Managed Devices, click on the device key of the device to confirm the admin state. (Do NOT set the Admin state to MAINT/DECOMM or the device could enter an unrecoverable state.)
  • Make sure that the Apstra version specified is the same on both the Apstra server and the device. If they are different, you cannot upgrade the device. If you attempt to upgrade with different versions, you will not receive a warning; the task status remains in the "in progress" state indefinitely.
  • If you're upgrading a Cumulus Linux device, the DHCP server must be on the device management network that is configured with a static DHCP assignment for the Cumulus Linux device. The Cumulus Linux device must get the same IP from the DHCP server as before the upgrade. Astra software uses the Open Network Install Environment (ONIE) process to add a completely new Cumulus Linux to the device and return it to a factory default state. The eth0 management interface comes up configured for DHCP.

Update User-defined Device Profiles

Make sure that your devices are in the appropriate states for upgrading as described in the overview above.

If you've created (cloned) your own device profiles, you'll need to manually specify OS versions in the device profile and the blueprint that uses that device profile. (If your devices use built-in device profiles, then proceed to the next section to upgrade the NOS.)

  1. From the left navigation menu in the Apstra GUI, navigate to Devices > Device Profiles, select your device and update the OS version in the Selector section.
  2. From the left navigation menu, navigate to Platform > Developers > Graph Explorer and find the ID for the device profile. You can find it with the query variables { device_profile_nodes { id label } }

    In this example, the "id" for the label "Clone DCS-7160-48YC6_abc" is "35a376ad-6ba1-42ec-bfe9-7810c56003d3".

  3. Use the aos-cli utility to update the device profile. For more information about using the aos-cli, see Juniper Support Knowledge Base article KB36747

    You can use your blueprint ID and the node ID from the previous step, then set the proper model ID ("DCS-7160-48YC6" for example), and execute.

    aos-cli command format:


  4. From the Apstra GUI, navigate to your blueprint, click Uncommitted and commit the changes.
  5. Proceed to the next section to upgrade the OS in the same manner as for devices using predefined device profiles.

Upgrade OS

Make sure that your devices are in the appropriate states for upgrading as described in the overview above.

This procedure is for devices that use built-in device profiles, as well as devices that use user-defined device profiles that have completed the previous section.

  1. Upload or register the necessary device OS images.

    Make sure to select a compatible device operating system image for the device that you're upgrading. If you use an incompatible image and the upgrade fails, the deployment lock will not be released automatically, even if you recover the device. To release the deployment lock and activate the device again, remove the device assignment from the blueprint, decommission and normalize the device (from Devices > Managed Devices), then reassign the device to the blueprint. For assistance, contact Juniper Support.

  2. From the left navigation menu, navigate to Devices > Agents and select the device(s) to upgrade. You can search for specific devices (such as for all EOS devices) by entering a query.

    All selected devices must be of the same type, and they must be upgraded to the same image and version.

  3. Click the OS Upgrade button (in the right Actions panel).
  4. The Upgrade OS Image dialog lists the available OS images that match the selected devices. Select the appropriate OS image and click Upgrade OS Image. The image uploads to the device.

    For Cumulus Linux:

    • The local device username and password that was used to install the agent is recreated.
    • The same Cumulus Linux license is reinstalled and Apstra configuration and deployment state is restored.
  5. You can monitor the upgrade status from the Active Jobs section at the bottom of the Agents page .
  6. After the image is uploaded, if a checksum is provided with the OS image, the image checksum is verified. If the MD5/SHA512 checksum is incorrect, or if any other failures occur (such as for insufficient disk space or incorrect remote URL), the job state changes to FAIL and the device does not reboot.

    If an issue arises with the OS image (such as interrupted download or invalid URL) during a NOS upgrade, you are informed before any device configuration is changed (new in Apstra version 4.0.1). You can then resolve the issue and restart the upgrade process.

  7. If the job fails, click the agent to view errors. You can also click the Show Log button to view the detailed Ansible job. If an upgrade fails, you must manually resolve the issue causing the failure. For example, with a checksum error, you must either correct the invalid checksum or register a new OS image with a correct checksum, then repeat the upgrade process.
  8. If the checksum is correct and no other failures occur, the job state changes to SUCCESS and the device reboots.
  9. When the device has rebooted with the new image and has reestablished its agent connection with the controller, the upgrade is complete. The Agents page displays the new OS version.