Data Center / Cloud

Simplifying Cumulus Linux Migrations

Decorative image of a web of green light on a dark background.

Migrating between major versions of software can present several challenges to the infrastructure management teams:

  • Data format changes
  • Feature deprecations
  • Downtime planning
  • Configuration translation between the platforms
  • Lack of familiarity
  • User training

These challenges can prevent users from adopting the newer versions, so they miss out on newer, more powerful features. Effective planning and thorough testing are essential to overcoming these challenges and ensuring a smooth transition.

Cumulus Linux 3.7.x and 4.x.y versions for Spectrum-based hardware are at the end of their support lifecycle and data center switches are expected to be migrated to the NVIDIA Cumulus Linux 5.x. The newer versions of Cumulus Linux also use the NVIDIA User Experience (NVUE) to interact with the switches. This makes the need for a seamless migration plan even more important. 


NVDIA User Experience (NVUE) is an object-oriented, schema-driven model of a complete hardware and software system. It provides a robust API that enables multiple interfaces to both view (show) and configure (set and unset) any element within a system running the NVUE software. NVIDIA Cumulus Linux 5.x includes the NVUE model. 

NVUE is an API-first structured object model that simplifies operations. It provides a declarative command line interface (CLI) and a single configuration file. The CLI and the REST API are equivalent in functionality. You can run all management operations from either the REST API or the CLI. 

Before NVUE, Cumulus Linux used a different CLI for the networking configuration process, the Network Command Line Utility (NCLU). NCLU resides in the Linux user space and provides consistent access to networking commands directly through bash. 

In contrast, NVUE simplifies operations by providing a declarative CLI and RESTful API, along with providing a single configuration file. This simplifies your automation process.

NVUE migration tool

The NVUE migration tool intends to provide a headstart in creating the new configuration for Cumulus Linux and making the migration process easier. 

The generated configuration must be verified. To validate the network environment, use the NVIDIA Air platform to fully simulate the data center and enable testing and verification in a risk-free environment. The migration process impacts production usability and requires a maintenance window.

It supports migration from the following platforms:

  • Cumulus Linux 3.7 and higher (uses NCLU) to the latest version of Cumulus Linux (uses NVUE). 
  • NVIDIA Onyx (a legacy NOS choice) to the latest version of Cumulus Linux (uses NVUE).
Screenshot shows the two options available on the tool: NCLU conversions or Onyx conversions.
Figure 1. NVUE migration tool

Please work with your NVIDIA solution architect for any additional migration concerns.

Running the NVUE migration tool for NCLU conversions

Back up the CL configuration by collecting the CL support file from the switch: 

cumulus@switch:~$ sudo cl-support

Drag and drop the support file on the Cumulus Linux tab.

Running the NVUE migration tool for Onyx conversions

Back up the Onyx configuration with the following command:

switch # show running-configuration

Copy the output and paste it to a text editor, saving it with a .txt extension.

Drag and drop the Onyx switch running-configuration text file under the Onyx tab.

Analyzing the output

Examine the output of the NVUE Bash Script File and look for SCRIPT UNSUPPORTED and FUTURE SUPPORT. For each feature, assess the impact.

## VLAN configuration
nv set bridge domain br_default vlan 1299
nv set bridge domain br_default vlan 3036
nv set interface swp1-4 bridge domain br_default untagged 1
# FUTURE SUPPORT vlan 1299 name "IPL"
# FUTURE SUPPORT vlan 3036 name "V3036-MSA-Access"

## STP configuration
nv set bridge domain br_default stp priority 24576
# Cumulus Linux enables PortAutoEdge by default
nv set interface swp1-4 bridge domain br_default stp bpdu-guard on
## WJH configuration
# SCRIPT UNSUPPORTED no what-just-happened acl enable
# SCRIPT UNSUPPORTED no what-just-happened buffer enable
# SCRIPT UNSUPPORTED no what-just-happened forwarding enable
# SCRIPT UNSUPPORTED no what-just-happened layer-1 enable
# SCRIPT UNSUPPORTED no what-just-happened auto-export acl enable
# SCRIPT UNSUPPORTED no what-just-happened auto-export buffer enable
# SCRIPT UNSUPPORTED no what-just-happened auto-export forwarding enable

## Interface Ethernet configuration
# MLAG CONVERSION interface port-channel 1299
# MLAG CONVERSION interface ethernet swp55-56 channel-group 1299 mode active
nv set interface swp53 description "Core: eidf-spine-s01-2f23 Eth1s10 [100Gb]"

Using the output

Choose from the following methods how to copy the CL configuration to the CL switch:

  • NVUE Bash Script File
  • NVUE Script Output File
  • NVUE Apply File
  • NVUE Startup Yaml File

Input files with breakout configuration don’t validate successfully, due to a limitation with NVUE breakout ports on NVIDIA Air. This leads to an error in the NVUE startup YAML file not being generated. In breakout port configurations, where the only errors in the NVUE Apply File point to breakout port config, use the NVUE bash script method mentioned here.

Either download the NVUE bash script and copy and paste the content into the CL switch CLI, or download the NVUE startup YAML file, change the extension to .yaml, and load the new file into the CL switch in the following directory: 

- /etc/nvue.d/startup.yaml

Get started

If you are ready to start using the robust NVUE but are unsure where to start, use the NVUE migration tool to accelerate the configuration conversion process, and get started. For more information about output commands, see the NVUE Command Reference.

For more information, see the following resources:

Discuss (0)