CML 2.4 Release Notes

Cisco Modeling Labs (CML) is a network simulation platform. CML 2.4 is the latest feature release of CML and introduces support for deploying CML as a cluster.

New and Changed Information

This table shows any published changes to this CML 2.4 release notes document.

Installing or Migrating to CML 2.4

Upgrading to CML 2.4

If you already have a CML 2.3.x installation, you can upgrade it to CML 2.4.0. See the In-Place Upgrade page for upgrade instructions. In-place upgrades from CML version 2.2.3 or earlier are not supported.

Migrating from an Existing CML 2.2 Installation

It is not possible to upgrade a CML 2.2.x installation to CML 2.4. You must migrate to a new CML 2.4 installation. If you have an existing CML 2.2.x installation, the migration tool will help you migrate your data from your existing CML installation to the new CML 2.4 installation. If your existing CML installation is CML 2.0.x or 2.1.x, we recommend first following the CML 2.2.x documentation to perform an in-place upgrade to CML 2.2.3 before migrating to a new CML 2.4 installation. The following video demonstrates the migration process with CML 2.3, and you can use the same steps to migrate from CML 2.2.3 to CML 2.4.

1. Deregister your existing CML 2.2.x instance.
   • If you choose to migrate an existing, licensed CML 2.2.x installation to a new installation of CML 2.4, you must deregister the old CML instance before decommissioning it. See Licensing - Deregistration for instructions on deregistering a CML instance.
   • Warning for CML instances that use the On-Prem licensing option. There is a known issue with CML 2.2.x that causes license deregistration to fail with some versions of the CSSM On-Prem software. If you are unable to deregister the CML 2.2.x instance from your CSSM On-Prem server, open a support case for CML.
2. Install CML 2.4 (see below).
   • Since you are migrating from an existing CML 2.2.x installation, mounting the refplat ISO before running the CML 2.4 installation is optional.
   • If the reference platform ISO is mounted before starting the CML 2.4 installation, the setup script will copy reference platform images from a mounted refplat ISO to the local disk.
   • You can skip the copying of reference platform images during installation because the migration tool will copy all of the reference platform images from your CML 2.2.x installation to the new CML 2.4 installation.
   • Only mount the new refplat ISO if you want to add the new versions of the reference platforms in addition to the existing versions from your CML 2.2.x installation.
3. Follow the instructions in the migration tool's README.md to migrate data from your existing CML 2.2 installation to your new CML 2.4 installation.
4. License your new CML 2.4 installation.

The migration tool can be found on your CML 2.4 installation at /usr/local/bin/virl2-migrate-data.sh. You can also download the latest version of the migration tool from https://github.com/CiscoDevNet/cml-community/tree/master/scripts/migration-tool.

The migration tool also supports offline migration. If you want to install CML 2.4 on the same server that's currently running CML 2.2.x, you can use the Offline Version Migration instructions to back up the data to a .tar file. That way, you can transfer the .tar file to a separate datastore temporarily while you reinstall with CML 2.4. As always, make sure that you deregister your old CML 2.2.x instance before decommissioning it and starting the CML 2.4 installation.

Installing CML 2.4

The CML Installation Guide provides detailed steps for installing your new CML 2.4 instance.

• In CML 2.4, all of the reference platform VM images must be copied to the local disk of the CML instance. Be sure to provision enough disk space for your new CML instance to accommodate the reference platforms.
• Downloading the refplat ISO file is optional if you are migrating from an existing CML 2.2.x instance. The migration tool will migrate all of your existing image definitions and VM images from your old CML 2.2.x instance.
• Be sure to check the System Requirements for updated system requirements.
• Important: After the reference platforms are copied to disk during the Initial Set-Up, wait a couple of minutes for the CML services to finish restarting before clicking OK to continue. If you click OK too soon, the initial set-up can fail. (See the Known Issues below.)

Demonstration of CML 2.4 Features

You can see a brief demo of the new CML 2.4 features in the following video:

Clustering

The primary new feature in CML 2.4 is the introduction of clustering (phase 1). Prior to the 2.4 release, CML 2.x scaled vertically. Vertical scaling means that to run large topologies or a larger number of small topologies, you had to deploy CML on a very large server. Clustering allows for horizontal scaling across multiple servers while still providing a single user interface to manage labs. To permit regular CML feature releases, we chose to split the CML clustering functionality into multiple phases. Future CML releases will add additional clustering functionality.

Note: Clustering is only available in the non-personal CML products, such as CML-Enterprise and CML-Education.

This first phase of clustering support adds the ability to join one or more computes to a CML controller, forming a CML cluster. Within such a cluster, you can start large topologies, which would not fit into a single all-in-one CML instance, and the CML controller will dynamically assign nodes to the compute members of the cluster. The cluster controller can place VMs for nodes from a single topology on different computes. During the initial setup of a CML instance, the administrator chooses whether it will be a cluster controller, a cluster compute, or a standalone (non-cluster) instance.

Clustering phase 1 includes the following high-level features:

• Dynamic registration of compute members to the cluster controller
• Sharing of reference platform images from the cluster controller to each compute member
• Automatic distribution of large labs across available compute members
• In-place upgrade from CML 2.3.x

Nomenclature

• node / VM: a virtual machine, which is part of a lab topology
• fabric: the software component connecting VM NICs with each other, also providing external connectivity
• controller: the CML instance that hosts the CML controller services, the CML UI, and the CML APIs
• compute or compute member: a member of a cluster where CML runs the VMs for running nodes
  • The admin can configure the controller so that it runs VMs just like the compute members or so that it does not run any VMs.
  • We generally recommend disallowing VMs from running on the controller, if possible.
• cluster: a set of CML instances with one controller and one or more compute members

Clustering Constraints

Before deploying a CML cluster, you should be aware of the current constraints. Since CML 2.4 is just the first phase of CML clustering, more clustering functionality will be added in future CML releases. Phase 1 clustering in CML 2.4 has the following constraints:

• Clustering is only available on non-personal CML products. Personal products, i.e., CML-Personal and CML-Personal Plus, cannot run a CML cluster.
• No influence on placement. Nodes are placed in no particular order on computes. CML starts the node VM on an arbitrary compute that can run it.
• No migration of nodes. Once a node has been allocated to a specific compute, it will stay on that compute every time you start the lab unless you wipe the node (or lab) first. The next time you start a node after wiping it, it will be assigned to a compute again. It may be allocated to the same compute as before.
• No re-balancing. For example, if all running nodes were allocated to one compute, and other computes of the cluster are idle, there is no automatic re-balancing of the nodes to the available computes. As above, stopping and wiping the lab will cause the nodes to be reallocated the next time you start the lab, and that reallocation may rebalance the nodes across the compute members.
• No external connectivity via computes. All external traffic goes through the controller.
• Software upgrade for a cluster. To upgrade a cluster, you must manually trigger the upgrade of the controller and all of the computes.
• No integrated cluster management. The controller and each of the computes run Cockpit, but there is no aggregated management functionality at this time.
• No compute management after adding a compute. Compute registration is automatic, but there is currently no way for the admin to either put a compute in maintenance mode or remove a compute from service. Some of this functionality will be added in phase 2 clustering.
• Compute state handling. When a node's VM has been allocated to a compute, and the compute is not available, the state of that VM cannot be determined and may be incorrect. Starting, stopping, or wiping a node that has already been allocated to a particular compute while that compute is offline is likely to cause undesirable side effects. Controller re-syncing of computes has only been partially implemented. The state of nodes that were running on the compute when it was disconnected will not recover automatically, and manual intervention may be required to bring affected labs into a consistent state.
• No ability to limit resource usage. Just like on a standalone CML instance, a single lab or a single user can use all of the resources of a CML cluster. The CML admin has no way to restrict or limit this resource usage.
• A CML cluster may be licensed for up to 300 nodes.
• Cluster size is currently limited to 8 computes.

Summary of Other Changes

The main focus of the CML 2.4 release is the clustering phase 1 functionality, but there are other updates and bug fixes in this release. This section summarizes the other changes since CML 2.3.x.

UI Changes

Tables in the CML UI

CML 2.4 adds new functionality to some of the tables shown in the UI.

You can now filter the data in the tables based on the values in a specific column. Columns that support filtering are decorated with the filter icon. Click the filter icon itself to set the filter for the column.

The search box at the top of a table performs a full text search across all columns that are both displayed and filterable. Only rows that match both the search and the active filters are shown in the table.

To help you focus on the data that's important to you, some of the tables in the UI now support customization of the columns to display. These tables offer new columns that display additional properties of the elements shown in the table. Click the gear icon at the top-right of the table to choose the table columns to display.

Lab Preview on the Dashboard Page

In the Dashboard page, the Show Preview toggle is no longer available in list layout of the labs. To achieve the same effect in CML 2.4, you can simply select or unselect the Preview column when choosing which columns to display.

Visual Link and Interface State on the Workbench Canvas

CML now provides a graphical representation of the interface and link state directly on the canvas in the Workbench.

• Interface state is represented by icons at the ends of the link:
  • Grey Square - Interface down
  • Green Circle - Interface up
• Link state is represented by the line style of the link:
  • Dashed Line - Link down
  • Solid Line - Link up

Simulate Disconnecting a Link

CML 2.4 adds new functionality on the Simulate pane for links. If you want to simulate disconnecting a link in a CML lab, it is generally not sufficient to Stop the link. Because of the implementation of the reference platform VMs and the simulated network, even when the link is stopped, the interfaces at the ends of the link will generally still report that they are connected. To simulate a disconnecting a link, you generally need to stop the link and stop the interfaces at each end of the link.

In CML 2.4, the link's Simulate pane now includes a Connect/Disconnect toggle button to make this action easier.

• Connect - start both interfaces on each side of the link to simulate a cable being connected
• Disconnect - stops both interfaces on each side of the link to simulate a cable being disconnected

To make it easier to see the state of interfaces associated with a link, the Simulate pane for the link now shows the state of the interfaces. You can also toggle the interface state (Start/Stop the interface) directly in the link's Simulate pane.

API Changes

CML 2.4 introduces several changes to the REST-based web service APIs. For details about a specific API, log into the CML UI and click Tools > API Documentation to view the CML API documentation page.

When a CML API endpoint completes successfully but returns no response object, it uses the return code HTTP/204 instead of HTTP/200 to indicate success. Not all API endpoints followed that pattern in previous releases. In this release, the following API endpoints will return an HTTP/204 code and no response body on success:

• DELETE /image_definitions/{def_id}
• DELETE /labs/{lab_id}
• DELETE /labs/{lab_id}/nodes/{node_id}
• DELETE /labs/{lab_id}/nodes/{node_id}/tags/{tag}
• DELETE /node_definitions/{def_id}
• GET /build_configurations
• PUT /labs/{lab_id}/start
• PUT /labs/{lab_id}/stop
• PUT /labs/{lab_id}/undo
• PUT /labs/{lab_id}/wipe
• PUT /labs/{lab_id}/interfaces/{interface_id}/state/start
• PUT /labs/{lab_id}/interfaces/{interface_id}/state/stop
• PUT /labs/{lab_id}/links/{link_id}/state/start
• PUT /labs/{lab_id}/links/{link_id}/state/stop
• PUT /labs/{lab_id}/nodes/{node_id}/wipe_disks
• PUT /labs/{lab_id}/nodes/{node_id}/state/start
• PUT /labs/{lab_id}/nodes/{node_id}/state/stop
• PUT /labs/{lab_id}/nodes/{node_id}/wipe_disks

APIs Removed in CML 2.4

The following formerly-deprecated APIs have been removed:

New APIs in CML 2.4

This table summarizes the API endpoints that are new in CML 2.4.

APIs Changed

This table summarizes the APIs changed in CML 2.4.

Other Changes

Bug Fixes

Known Issues and Caveats for CML 2.4

nmcli con

check con del bridge0-p1 
nmcli con add type bridge-slave \
    con-name bridge0-p1 \
    ifname enp9s0 master bridge0 
nmcli con down enp10s0 
# verify that the set up is now correct 
nmcli con