Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Upgrade Device NOS

SUMMARY Upgrade the network operating systems (NOS) of your Apstra-managed network devices from within the Apstra environment.

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

NOS Upgrade Overview

You can upgrade a device NOS within the Apstra environment with a few steps. If you've defined your own device profiles, you may need to update them first. You'll register the new OS image that you obtained from the vendor, then click a button to start the upgrade. Apstra takes care of upgrade tasks and other requirements and ensures that pristine config is updated.

Note: Though we don't recommend it, you can upgrade a device NOS outside of the Apstra environment. This requires that you perform manual steps as follows: unassign and undeploy the device from the blueprint, commit the changes, uninstall the agent, upgrade the device NOS outside of the Apstra environment, install the agent, assign and deploy the device in the blueprint, then finally commit the changes.

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

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

However, device profiles that you've created (cloned) yourself, are not managed in the Apstra environment, so when you upgrade the Apstra server those device profiles aren't automatically updated with newly supported versions. You'll need to follow a few extra steps to add them 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 Apstra software is managing the device you're upgrading. Navigate to Devices > Managed Devices and confirm that your device is in the table 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 Management IP 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 the deploy mode of the device is set to Drain.

  • Make sure that the Apstra version specified is the same on both the Apstra server and the device. If they are different, you can't 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.

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 predefined device profiles, then proceed to the next section to register the new OS image.)

  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 apstra-cli to update the device profile.

    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.

    apstra-cli command format:

    Example:

  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.

Register / Upload OS Image

  1. Obtain the OS image from the device vendor.

    CAUTION:

    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 is not 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 > System Agents > OS Images and click Register OS Image (top-right).

    You can see how much space is left for uploading new NOS images; if the partition has under 5GB of free space a warning appears in the dialog that opens.

  3. Select the platform from the drop-down list (EOS, NXOS, SONIC, JUNOS) and enter a description.

  4. Either upload the image directly to the Apstra server or provide a URL download link pointing to an image file on an accessible HTTP server (described in sections below).

Method One: Upload Image

  1. Select Upload Image, then either click Choose File and navigate to the image on your computer, or drag and drop the image from your computer into the dialog window and click Open

    .

  2. Add a checksum (optional) (described in section below).

  3. Click Upload.

    Apstra validates that the software package is supported by the switch OS. If it isn't supported (because the file extension is wrong, for example), then the upload fails immediately, before uploading begins.

    Apstra validates the (optional) checksum. If it can't be verified, the upload process fails immediately, before uploading begins.

    If all validation passes, the image is uploaded and appears in the table view.

Method Two: Provide Image URL

If another HTTP server is accessible to the devices being upgraded via their network management port, you can register the OS Image instead of uploading it. HTTP and HTTPS URLs are supported. (FTP, SFTP, SCP and others are not supported.)

  1. Select Provide Image URL.

  2. Enter the URL that points to the image on the other server.

  3. Add a checksum (optional) (described in the section below).

  4. Click Register.

    Apstra validates the (optional) checksum. If it can't be verified, the process stops.

    If validation passes, the image appears in the table view.

Add Checksum (Optional)

The platform determines the type of checksum that's used:

  • Juniper Junos - MD5 (32 characters) or SHA256 (64 characters)
  • Enterprise SONiC - MD5 (32 characters)
  • Cisco NX-OS - SHA512 (128 characters)
  • Arista EOS - SHA512 (128 characters)

If the device vendor provides a checksum file, we recommend that you download the file and copy it to the Checksum field. If a checksum file is not available, you can generate a checksum with the Linux md5sum or shasum commands, as applicable, or with equivalent programs.

Upgrade OS Image

Make sure that your devices are in the appropriate states for upgrading as described in the overview above, and that if your device profiles are user-defined that you've updated them accordingly.

Before upgrading the device NOS, Apstra rolls back device configuration to its pristine state. It then performs the upgrade and reboots the device, pushing the intended blueprint configuration to devices. Before Apstra pushes this configuration, the device goes live while configured with its pristine configuration, which usually includes interfaces that are up. This means traffic could be blackholed before the intended blueprint configuration is pushed. As of Apstra version 5.0.0, Apstra will automatically shut down interfaces during upgrade. If you want interfaces to remain up during upgrade, then navigate to Devices > Managed Devices, click Advanced Settings, select the Skip Shutting Down Interfaces During Upgrade check box, then click Update.

  1. From the left navigation menu, navigate to Devices > Managed Devices, and select the check box(es) for the device(s) to upgrade. (If you have many devices, use the query function to filter selections.) All selected devices must be of the same type, and they must be upgraded to the same image and version. To search for specific devices (such as for all EOS devices) click the Search button (magnifying glass) and enter a query.
  2. Click the Upgrade OS Image button (above table in Agent section). The dialog lists the available OS images that match the selected devices.
  3. Select the appropriate image and click Upgrade OS Image. You can monitor the upgrade status from the Active Jobs section at the bottom of the page.
  4. 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, incorrect remote URL, or when the device NOS version is not changed post upgrade), the job state changes to FAIL and the device does not reboot.
    Note:

    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. You can then resolve the issue and restart the upgrade process.
  5. 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.
  6. If the checksum is correct and no other failures occur, the job state changes to SUCCESS and the device reboots.
  7. When the device has rebooted with the new image and has reestablished its agent connection with the controller, the upgrade is complete. The Managed Devices page displays the new OS version.