Upgrading to New Version

If you already have an installation of Cisco Modeling Labs 2.x, you may be able to upgrade your existing installation to the latest release using the upgrade package for the new release. Be sure to check the Release Notes for Cisco Modeling Labs to ensure that an in-place upgrade to this release is supported from your existing, installed release.

In particular, your existing CML instance must be CML 2.3.0 or higher to upgrade to the CML 2.7.2 release. In-place upgrades to CML 2.8.0 or later are only supported from the 2.7.2 or later release. If an in-place upgrade is not supported from your current release, you cannot use these upgrade instructions. See the Release Notes for Cisco Modeling Labs for your options to migrate your existing CML server to the given release.

Note

CML-Enterprise Cluster upgrade is generally supported whenever in-place upgrade is supported. When upgrading from release 2.4.0, which introduced cluster support, each compute host’s upgrade must be run separately, starting with the controller. Since the 2.5.0 release, compute host CML software upgrades are automatically initiated by the controller’s upgrade. Instructions below have additional notes regarding cluster-specific steps, which may be skipped for standalone All-in-One installations.

Attention

If you have made modifications to the system (copying images to different places, manually changing configuration files, etc.), back up those changes prior to starting the upgrade. You may need to re-apply those changes after the upgrade has finished.

Additional Ubuntu OS packages you have installed may interfere with the upgrade process, especially if their updated versions change their respective names, are split or rearranged into different packages, require new or change configuration options, or become unavailable. Please check if packages you have installed are still available in Ubuntu, and consider uninstalling them temporarily before major OS upgrades.

Before you start, download a copy of the pkg.zip file for the CML controller to your local machine. See Downloading Files for CML Installation for details on how to download the files for this release. If no pkg.zip file is available, then in-place upgrades to that release are not supported.

The .pkg file does not contain any Ubuntu OS packages which are required in that release. When performing the upgrade, any new dependencies must be accessible to the CML instance, either for download from official OS repositories, or an alternative source you can configure while running an offline or air-gapped CML-Enterprise installation. Even if no new packages are required by the upgrade, applicable OS updates are still fetched and performed, and the package sources must be (de-)configured appropriately for your environment.

Please review and apply any steps matching your deployment environment, as discussed in Proxied, Air-gapped and Offline Environments. If your deployment is offline or air-gapped, also download the .iso file so the Ubuntu OS upgrades can also be applied during the upgrade. Make the .iso available to each host prior to initiating upgrade.

Attention

Upgrades from the 2.7.2 release to 2.8.0 or later perform an upgrade of the underlying OS from Ubuntu 20.04 LTS to 24.04 LTS (code name noble). These will replace the majority of software installed from the Ubuntu OS. However, it is still strongly recommended that deployments which can download software updates of Ubuntu 20.04 LTS do perform these updates. Use the steps described in Applying OS Updates before following this upgrade procedure.

Attention

Prior to initiating the upgrade, all labs must be stopped. Upgrades will be rejected otherwise. Coordinate with all lab users to ensure their work is saved. The lab nodes will not be wiped, but they may contain runtime-only configuration which is not written to disk and may be lost. For example, for all nodes running IOS XE, enter the command copy running-config startup-config or write to save what can be saved.

Attention

Consider downloading and archiving all lab topology files and their custom node configurations. In VM-based CML deployments, you may also back-up or take a snapshot of the host itself in case the upgrade fails.

To perform an in-place upgrade, use the following procedure. We also recommend updating the base OS packages whenever updates are available to your installation. Read all the instructions prior to performing the procedure, and contact support if you have concerns or additional questions.

Log into the System Administration Cockpit as the system administrator account. See Logging into the System Administration Cockpit.

If the upgrade file is a .zip file, first unzip the file and extract its contents.

  • On Windows, use the File Explorer, 7-Zip, WinZip, or a similar program.

  • On macOS, use the Archive Utility app or the unzip CLI command.

Optional: Cisco signs all CML software before release. If you downloaded the pkg.zip file and extracted its contents, find the .pkg and pkg.README files from the zip file. Open the pkg.README in a text editor and follow the instructions in that file to verify the .pkg file’s signature.

Log into the CML server UI.

In the top-most menu panel, click Tools ‣ System Upgrade.

Click the Browse button, and select the upgrade package from your local system, such as cml2_2.9.0-3_amd64-3.pkg. Note that if you downloaded a pkg.zip file, you must extract and upload the .pkg file from the zip file.

Click the Upload Image button and wait for the file to finish uploading.

Click on the using Cockpit link to open the System Administration Cockpit in a new tab.

CML Controller Upgrade - System Administration Cockpit login verification

Log into the System Administration Cockpit as the system administrator account. See Logging into the System Administration Cockpit. Verify that you can see the CML2 System Maintenance Controls page, which is also accessible through the left-side menu as CML2.

Attention

In CML-Enterprise Cluster installations, make sure you can log into each host prior to starting the upgrades. Make sure you have logged in as the system administrator username which was setup during initial setup, and that the same username was used for each compute host. The passwords need not match.

When upgrading from release 2.4.0, open the System Administration Cockpit for each compute host in a separate tab.

In clusters since release 2.5.0, the compute hosts rely on the controller’s System Administration Cockpit to initiate upgrades. If the compute hosts were set up correctly, then you should be able to switch between all hosts in the controller System Administration Cockpit. At the top of the left-side menu, the currently-controlled hostname should be visible as a drop-down menu. Clicking it reveals all compute hosts visible to System Administration Cockpit. Select each compute host in turn to switch between them. If you are unable to see or switch to all hosts without errors, contact support.

Verifying state for CML Controller Upgrade - CML UI steps

Switch back into the CML server UI browser tab. In the bottom-right corner, verify system state. If the button is red, click it and examine reasons for it. If either licensing or any compute host report as red, contact support to resolve such issues prior to upgrading.

In the top-most menu panel, click Tools ‣ System Administration.

On the System Administration page, click Node Administration.

Verify there are no running lab nodes.

You will see the table of all lab nodes in the system. All listed nodes must have their State reported as CREATED or STOPPED prior to continuing with the upgrade. If all nodes are in these states, continue with the next step.

If you have many nodes, you can click the filter icon in the State column to show only nodes which are in selected states. Click on the drop-down menu that appears. Only states where at least one node has that state will be listed as options. Select all states other than CREATED or STOPPED. Then click into empty space away from the popup.

Click the checkbox in the top-left corner of the table. Then click the Stop button to stop all selected nodes. Continue with the next step once all nodes report to be in the desired states.

Enabling CML Controller Maintenance Mode - CML UI steps

Note

Skip these steps when upgrading from releases prior to 2.6.0 (to release 2.7.2). The upgrade process itself will initialize maintenance mode into enabled state during upgrades from such older releases. You will take these steps from then on to control access to the system during any maintenance.

On the System Administration page, click System Maintenance.

On the System Maintenance page, click the Maintenance Mode toggle to enable it. Click Save to apply the change.

A banner message informing users of ongoing maintenance will appear. All non-admin users of a multi- user CML-Enterprise system will be logged out, and not allowed to log back in.

On the System Administration page, click Compute Hosts.

In the table of compute hosts, click the checkbox in the top-right corner to select all items.

Click the Change Admission State drop-down, and click the REGISTERED option.

The compute hosts will be all reported as disconnected. A System Health Issue may be shown in the bottom-right corner of the UI, but this is normal at this point.

CML Controller Upgrade - System Administration Cockpit UI steps

Switch into the System Administration Cockpit, click CML2 in the navigation bar on the left side of the page and expand the Controller Software Upgrade item in the Maintenance section.

Note

In Cluster installations, log into or switch to the Controller host’s System Administration Cockpit UI.

In the System Administration Cockpit, click the Upgrade button.

This step takes several minutes, depending on the speed of your network connection. The upgrade process attempts to refresh the OS database of available software packages, and may try to download any OS package dependencies which are missing from the system.

During the upgrade from CML release 2.7.2 to 2.8.0 or later, the System Administration Cockpit will be upgraded to a new version, and disconnect at that time. Use the browser Reload button to fully refresh the System Administration Cockpit. The login page should then no longer indicate the old release version, but rather the new release, or temporarily just Ubuntu 24.04 LTS. Log into the System Administration Cockpit again. The UI will resume showing latest output from the upgrade, which is likely still in progress at this time. If the upgrade has completed already when you log back in, the complete upgrade logs are shown.

If during upgrades from CML releases prior to 2.7.2, the System Administration Cockpit disconnects, then click the Reconnect button and check the log output by clicking the Show Log Output button in the Controller Software Upgrade area. The upgrade process might still be running in the background, but after the first disconnection, the page will no longer refresh the output area automatically to show the latest output from the upgrade process. You may need to click the button or refresh the page multiple times to see all of the output from the upgrade process.

The Show Log Output can be used to retrieve the logs at any time after an upgrade.

If everything goes well, the log output at the very end should indicate that the upgrade process is done:

Upgrade Log Output

Upgrade Log Output

Once the upgrade is complete, check the output in the Output area at the bottom of the CML2 page in the System Administration Cockpit. Ensure that the upgrade did not generate any final error or failure messages. Some upgrade steps may generate such messages, which may be ignored as long as the upgrade continued past them; they may only become relevant in case the upgrade as a whole is declared as failed.

Attention

In Cluster installations when upgrading from release 2.5.0 or later, the upgrade for each compute host will take place in turn after the controller is upgraded. There is a separate success or failure result logged for each host of the cluster. A '<<< Finished executing on all compute hosts >>> message will appear once that is done.

If upgrading from release 2.4.0, repeat the previous steps using System Administration Cockpit of each individual compute host in turn. You do not need to upload the image file again.

If performing the upgrade from CML 2.7.2 release to 2.8.0 or later, a reboot is required at this point. A reboot is recommended in other cases to run the host using the latest installed Linux kernel release.

In Cluster installations, reboot each host only after the upgrade has completed on all cluster hosts.

In some deployments where DHCP is used to configure IP on the CML server, the host may receive a new IP address after the upgrade. In such cases, use the new assigned address shown in the CML server console.

Attention

After the upgrade is complete, ensure that all users of the CML server clear their web browser caches before navigating to the CML server again and logging into the CML UI. Failure to do so may cause them to experience errors or other problems with the updated UI.

Disabling CML Controller Maintenance Mode - CML UI steps

Log in back into the CML server UI browser tab.

Note

These steps apply even when upgrading from versions prior to release 2.6.0.

In the top-most menu panel, click Tools ‣ System Administration.

On the System Administration page, click Compute Hosts.

In the table of compute hosts, click the checkbox in the top-right corner to select all items.

Click the Change Admission State drop-down, and click the READY option.

Tip

You can first put the compute hosts into the ONLINE state. In this state, node starts will be prohibited on the compute hosts, and you can still examine overall system health.

The compute hosts will connect back a short while after being re-enabled. Any issues reported in the bottom-right corner of the UI should be cleared shortly afterwards.

On the System Administration page, click System Maintenance.

On the System Maintenance page, click the Maintenance Mode toggle to disable it. Click Save to apply the change.

A banner message informing users of ongoing maintenance will disappear. All non-admin users of a multi- user CML-Enterprise system will now be allowed to log back in.

The upgrade is complete. Your CML server is now running the new release and is ready for use.

Attention

After the upgrade, we recommend that you and any other users of your CML server also upgrade client applications or tools that complement CML. An application or tool that is not included as part of the CML release or that you have installed locally on your own machine is not updated as part of the in-place upgrade procedure. Existing versions may not be compatible with your newly-upgraded CML server. Follow the links below for more information on each application or tool that you use and verify its compatibility with the new CML release before proceeding:

By keeping these tools up to date, you can take full advantage of the improvements and ensure compatibility with features of your newly-upgrade CML server.