Upgrade Cisco Crosswork Planning

This section contains the following topics:

Upgrade methods

Upgrading Cisco Crosswork Planning to the latest version includes upgrading Cisco Crosswork Platform and Cisco Crosswork Planning Applications within a single maintenance window.

Supported upgrade scenarios

The supported upgrade scenario for Cisco Crosswork Planning 7.1 is from Cisco Crosswork Planning 7.0 (IPv4 stack) to Cisco Crosswork Planning 7.1 (IPv4 stack).

Available upgrade methods

You can upgrade Cisco Crosswork Planning using these methods:

You can also update the Cisco Crosswork Planning applications from the Cisco Crosswork Planning UI in case of minor updates or patch releases. For details, see Upgrade Cisco Crosswork Planning applications (standalone activity).

Upgrade limitations and required post-upgrade actions

After upgrading from an earlier version, perform these actions to avoid data loss or system errors:

  • Manually register all license tags, as they are not auto-registered as part of the upgrade operation.

  • Manually update any custom user roles (Read-Write/Read) created in the earlier version, since these are not migrated.

  • Assign new permissions to any user roles with administrative privileges to re-enable their administrative access.

  • Always perform a hard refresh or clear your browser cache before proceeding to use the system. Failing to do this step can result in data discrepancies.

Upgrading using existing hardware

Summary

Upgrading to the latest version of Cisco Crosswork Planning using existing hardware is a multi-step process. This process enables you to upgrade Cisco Crosswork Planning on current physical infrastructure without replacing any hardware.

Workflow

These are the stages of upgrading using existing hardware. Execute each stage in sequence to ensure a successful upgrade.

  1. Back up your data on the existing hardware. For details, see Create a backup of your system configuration.
  2. Shut down the system to prepare for upgrade. For details, see Shut down Cisco Crosswork Planning.
  3. Install the latest version of Cisco Crosswork Planning onto the existing hardware. For details, see Install the latest version of Cisco Crosswork Planning.
  4. Restore your backed up configuration data to the upgraded system. For details, see Migrate Cisco Crosswork Planning backup.

Create a backup of your system configuration

This topic describes how to create a backup of your system configuration, so you can restore it later.

This task is the first stage of the upgrade process. Before upgrading to a new version, you must back up your current system configuration.


Note

We recommend that you create a backup only during a scheduled upgrade window. Do not access Cisco Crosswork Planning while the backup operation is running.

Before you begin

  • Configure a destination SCP server to store the backup files. This is a one-time activity. Before you begin, have this information ready:

    • The host name or IP address and the port number of a secure SCP server

    • A preconfigured path on the SCP server where the backup will be stored

    • User credentials with file read and write permissions to the directory

    • At least 25 GB of storage on the SCP server

  • Ensure both Cisco Crosswork Planning and the SCP server use the same IP environment. For example, if Cisco Crosswork Planning is communicating over IPv4, so must the backup server.

Procedure

Step 1

Log in to the Cisco Crosswork Planning UI.

Step 2

Verify that the Cisco Crosswork Planning VM and applications are healthy.

Step 3

Configure an SCP backup server.

  1. From the main menu, choose Administration > Backup and Restore.

  2. Click Destination to display the Edit Destination drawer panel.

  3. Enter the required information in the provided fields.

  4. Save the details of the backup server.

Step 4

Create a backup.

  1. Click Actions > Data backup.

    The Data Backup drawer panel opens with the destination server details pre-filled.

  2. In Job name, enter a relevant name for the backup.

  3. If the VM or any application is not healthy and you still want to create the backup, check the Force check box.

    Note

     

    You must use the Force option only after consultation with the Cisco Customer Experience team.

  4. Complete the remaining fields as needed.

    To specify a different remote server upload destination, edit the pre-filled Host name, Port, Username, Password, and Server path/Location to specify a different destination.

  5. (Optional) Click Verify backup readiness to verify that Cisco Crosswork Planning has enough free resources to complete the backup.

    If the check is successful, Cisco Crosswork Planning displays a warning about the time-consuming nature of the operation. Click OK to continue.

    If the verification fails, contact the Cisco Customer Experience team for assistance.

  6. Click Backup to start the backup operation.

    Cisco Crosswork Planning creates the corresponding backup job set and adds it to the Backup and Restore Job Sets table. The Job Details panel reports the status of each backup step as it is completed.

    Note

     

    If you do not see your backup job in the list, refresh the Backup and Restore Job Sets table.

Step 5

Monitor the progress of the backup job.

  1. To view the progress of a backup job, enter the job details, such as Status or Job Type, in the search fields in the Backup and Restore Job Sets table. Then, click the job set you want.

    The Job Details panel displays information about the selected job set, including job status, job type, and start time. If there is a failed job, hover the mouse pointer over the icon near the Status column to view the error details.

  2. If the backup fails during upload to the remote server, under the Status icon, click the Upload backup button to retry the upload.

    Note

     

    Upload can fail due to connectivity problems with the SCP backup server (for example, incorrect credentials, missing directory or directory permissions, missing path, and so on). This is indicated by failure of the task uploadBackupToRemote). If this happens, check the SCP server details, correct any mistakes and try again. Alternatively, you can use the Destination button to specify a different SCP server and path before clicking Upload backup.

Step 6

Navigate to the destination SCP server directory and ensure that the backup file is created. You will require this backup file in the later stages of the upgrade process.

The system configuration backup is created and available on the specified SCP server.

Shut down Cisco Crosswork Planning

After a successful backup, shut down Cisco Crosswork Planning by powering down the VM.

Procedure

Step 1

Log in to the VMware vSphere Web Client.

Step 2

In the Navigator pane, right-click the VM that you want to shut down.

Step 3

Choose Power > Power Off.

Step 4

Wait for the VM status to change to Off.

Install the latest version of Cisco Crosswork Planning

After you successfully back up the old version of Cisco Crosswork Planning, install the latest version of Cisco Crosswork Planning.

Procedure

Step 1

Install the latest version of Cisco Crosswork Planning using the instructions in Install Cisco Crosswork Planning using the vCenter vSphere UI.

During installation, a special administrative ID (virtual machine (VM) administrator, with the username "cw-admin" and the default password "cw-admin") is created. The administrative username is reserved and cannot be changed.

The first time you log in using this administrative ID, you are prompted to change the password. Data center administrators use this ID to log in to and troubleshoot the Cisco Crosswork Planning VM. Use this ID to verify that the VM has been properly set up.

Step 2

After the installation is complete, verify that all applications display a Healthy status.

  1. Log in to the Cisco Crosswork Planning UI.

  2. From the main menu, choose Administration > Crosswork Manager > Crosswork summary.

  3. Ensure all applications display Healthy.

Migrate Cisco Crosswork Planning backup

After successfully installing the new version of Cisco Crosswork Planning, proceed to migrate the Cisco Crosswork Planning backup taken earlier.

Before you begin

Ensure that you have

Procedure

Step 1

Verify that the Cisco Crosswork Planning VM is healthy.

Step 2

Configure an SCP backup server.

  1. From the main menu, choose Administration > Backup and Restore.

  2. Click Destination to display the Edit Destination drawer panel.

  3. Enter the required information in the provided fields. In Server path/Location, provide the location of the backup created in Create a backup of your system configuration.

  4. Save the details of the backup server.

Step 3

Migrate the old Cisco Crosswork Planning backup.

  1. Click Actions > Data migration.

    The Data Migration drawer panel opens with the destination server details prefilled.

  2. In Backup file name, provide the name of the data migration backup (created in Create a backup of your system configuration).

  3. To perform the data migration backup despite any Cisco Crosswork Planning application or microservice issues, check the Force check box.

  4. Click Start migration to start the data migration operation.

    Cisco Crosswork Planning creates the corresponding data migration job set and adds it to the Backup and Restore Job Sets table. The Job Details panel reports the status of each migration step as it is completed.

    Note

     

    If you do not see your job in the list, refresh the Backup and Restore Job Sets table.

Step 4

Monitor the progress of the migration job.

  1. To view the progress of a data migration job, enter the job details, such as Status or Job Type, in the search fields in the Backup and Restore Job Sets table. Then, click the job set you want.

    The Job Details panel displays information about the selected job set, including job status, job type, and start time. If there is a failed job, hover the mouse pointer over the icon near the Status column to view the error details.

    Note

     

    Cisco Crosswork Planning UI might become temporarily unavailable during the data migration operation. When the Cisco Crosswork Planning UI is down, you can view the job status in the Grafana dashboard. The Grafana link is available as View Data Migration Process Dashboard option on the right side of the Job Details panel.

  2. If the data migration fails at any point during the process, restart the procedure.

Step 5

After the data migration is successfully completed, ensure that all applications are healthy.

  1. From the main menu, choose Administration > Crosswork Manager > Crosswork summary.

  2. Ensure that all the applications display Healthy.

Upgrading using parallel hardware

Summary

Upgrading to the latest version of Cisco Crosswork Planning using new hardware relies on installing the new Cisco Crosswork Planning on new hardware in parallel while the data from the old Cisco Crosswork Planning is being backed up. This method is faster but requires twice the resources for creating the new VM in parallel.

Workflow

The stages of the parallel upgrade workflow are:

  1. Install the latest version of Cisco Crosswork Planning on a new VM. For details, see Deploy Cisco Crosswork Planning on a different VM.
  2. Back up your data on the existing hardware. For details, see Back up your Cisco Crosswork Planning data.
  3. Update DNS server and migrate your backed up configuration data. For details, see Update DNS server and migrate backup data.
  4. Shut down the old Cisco Crosswork Planning VM. For details, see Shut down the old Cisco Crosswork Planning.

Deploy Cisco Crosswork Planning on a different VM

This topic describes how to install the latest version of Cisco Crosswork Planning on a new VM in parallel.


Note

You must install the new Cisco Crosswork Planning with the same FQDN as the old version of Cisco Crosswork Planning.

Procedure

Step 1

Install the latest of Cisco Crosswork Planning on the new VM using the instructions in Install Cisco Crosswork Planning using the vCenter vSphere UI .

During installation, a special administrative ID (virtual machine (VM) administrator, with the username "cw-admin" and the default password "cw-admin") is created. The administrative username is reserved and cannot be changed.

The first time you log in using this administrative ID, you are prompted to change the password. Data center administrators use this ID to log in to and troubleshoot the Cisco Crosswork Planning VM. Use this ID to verify that the VM has been properly set up.

Step 2

After the installation is complete, verify that all applications display a Healthy status.

  1. Log in to the Cisco Crosswork Planning UI.

  2. From the main menu, choose Administration > Crosswork Manager > Crosswork summary.

  3. Ensure all applications display Healthy.

Update DNS server and migrate backup data

This topic describes how to migrate the Cisco Crosswork Planning backup taken earlier.

Before you begin

Ensure that you have

  • the host name or IP address and the port number of a secure SCP server

  • the name and path of the backup file created in Back up your Cisco Crosswork Planning data, and

  • user credentials with file read and write permissions to the directory.

Procedure

Step 1

Update the DNS server to point the FQDN of the previous version of Cisco Crosswork Planning to the <VIP> of the new Cisco Crosswork Planning VM.

Step 2

Log in to the upgraded Cisco Crosswork Planning UI using https://<new_VIP>:30603.

Step 3

Configure an SCP backup server.

  1. From the main menu, choose Administration > Backup and Restore.

  2. Click Destination to display the Edit Destination drawer panel.

  3. Enter the required information in the provided fields. In Server path/Location, provide the location of the backup created in Create a backup of your system configuration.

  4. Save the details of the backup server.

Step 4

Migrate the old Cisco Crosswork Planning backup.

  1. Click Actions > Data migration.

    The Data Migration drawer panel opens with the destination server details prefilled.

  2. In Backup file name, provide the name of the data migration backup (created in Create a backup of your system configuration).

  3. To perform the data migration backup despite any Cisco Crosswork Planning application or microservice issues, check the Force check box.

  4. Click Start migration to start the data migration operation.

    Cisco Crosswork Planning creates the corresponding data migration job set and adds it to the Backup and Restore Job Sets table. The Job Details panel reports the status of each migration step as it is completed.

    Note

     

    If you do not see your job in the list, refresh the Backup and Restore Job Sets table.

Step 5

Monitor the progress of the migration job.

  1. To view the progress of a data migration job, enter the job details, such as Status or Job Type, in the search fields in the Backup and Restore Job Sets table. Then, click the job set you want.

    The Job Details panel displays information about the selected job set, including job status, job type, and start time. If there is a failed job, hover the mouse pointer over the icon near the Status column to view the error details.

    Note

     

    Cisco Crosswork Planning UI might become temporarily unavailable during the data migration operation. When the Cisco Crosswork Planning UI is down, you can view the job status in the Grafana dashboard. The Grafana link is available as View Data Migration Process Dashboard option on the right side of the Job Details panel.

  2. If the data migration fails at any point during the process, restart the procedure.

Step 6

After the data migration is successfully completed, ensure that all applications are healthy.

  1. From the main menu, choose Administration > Crosswork Manager > Crosswork summary.

  2. Ensure that all the applications display Healthy.

Shut down the old Cisco Crosswork Planning

After a successful backup, shut down the old Cisco Crosswork Planning. For details on shutdown instructions, see Shut down Cisco Crosswork Planning.

Upgrade Cisco Crosswork Planning applications (standalone activity)

This section explains how to upgrade Cisco Crosswork Planning applications independently for minor updates or patch releases. This procedure is not part of the upgrade workflow described in previous sections.


Note

Cisco Crosswork Planning does not support the downgrade operation of an application file (CAPP). However, to revert to an older application version, you can uninstall the application and install the older version of the application. We recommend taking a backup of your data before starting the operation.

Before you begin

Ensure that you

  • take a backup of your data (using the backup and restore functionality) before any critical upgrade

  • download the latest version of the Cisco Crosswork Planning application to your local machine, and

  • perform upgrade operations in a maintenance window to minimize disruptions.

Procedure

Step 1

Download and validate the CAPP files.

  1. Navigate to cisco.com and locate the CAPP files (.tar.gz) that you require.

  2. Hover over the file and copy the MD5 or SHA512 checksum to your clipboard.

  3. Download the files to a server that can be reached from the Crosswork server.

  4. Run a tool of your choice to calculate the checksum, and compare the checksum value in your downloaded file with the value you copied in the clip board.

    For example, on a MAC you can use the md5 command to calculate the MD5 sum on a file: 

    md5 signed-cw-na-design-patch-7.0.1-2-release-241112.tar.gz

3e3becf10a509c8e3787eec8e362fd4f

    Verify that the result value matches with the posted value on cisco.com.

Step 2

Log in to Cisco Crosswork Planning UI.

Step 3

From the main menu, choose Administration > Crosswork Manager, and click the Application management tab.

The Crosswork Platform Infrastructure and any applications that are added are displayed here as tiles.

Step 4

Click Add new file > Upload application bundle file (.tar.gz). The Add Application Bundle (.tar.gz) dialog box is displayed.

Step 5

Select either URL or SCP as your preferred protocol. Based on your selection, fill in the additional fields with the required information. Click Add to proceed.

Step 6

To upgrade, click the Upgrade prompt and the new version of the application is installed. Alternatively, click on the tile, and select the Upgrade option from the drop-down list.

Step 7

In the Upgrade screen, select the new version that you want to upgrade to, and click Upgrade.

Step 8

(Optional) Click Job History to see the progress of the upgrade operation.

Note

 

During an upgrade, only the changed components are installed, with the new version reusing most resources from the older version to ensure a fast and non-disruptive process. However, the application being updated will be degraded until the upgrade is complete, and users will be notified of the upgrade through an alarm.

The application is upgraded to the selected version.

Collector configuration migration

A collector configuration migration is a process that enables you to migrate collector configurations from Cisco WAE 7.5.x/7.6.x or between different Cisco Crosswork Planning instances.


Note

When using collectors that have file upload options, ensure to upload the correct files after importing the collector configuration. This is necessary because, after you import the configuration, the server restores only the file name and not the actual file. If you do not use the correct file, the collection will fail.

Migrate collector configurations from Cisco WAE

This section explains how to migrate collector configurations from Cisco WAE 7.5.x/7.6.x to Cisco Crosswork Planning.

Before you begin

Procedure

Step 1

If you have not backed up the configuration, use these steps to back up and migrate it to a configuration compatible with Cisco Crosswork Planning:

  1. Log in to the machine where Cisco WAE 7.x is installed.

  2. Enter this command:

    # ./wae_upgrade --export --install-dir <WAE_7.x_INSTALL_DIR> --cfg-dir 
<dir_to_save_exported_config>
Where:
     --install-dir   indicates the directory where 7.x WAE is installed.
     --cfg-dir       indicates the folder where the backup of 7.x configuration 
                     must reside. The migrated configurations are saved as 
                     wae_networks.cfg in the provided directory.

Step 2

If you already have the backed-up configuration, use these steps to convert the file into a format compatible with Cisco Crosswork Planning:

  1. Log in to the machine where the Cisco WAE 7.x configuration is backed up.

  2. Enter this command:

    # ./wae_upgrade --migrate --cfg-dir <dir_containing_7.x_config>

Where:
      --cfg-dir   indicates the folder where the 7.x configuation is backed up.  
                  This configuration will be migrated to Cisco Crosswork Planning 
                  compatible configuration. The migrated configurations are saved as 
                  wae_networks.cfg in the provided directory.

Step 3

Import the migrated configurations (wae_networks.cfg) to Cisco Crosswork Planning using these steps:

Note

 

Before migration, ensure that configurations are backed up using the upgrade scripts. Otherwise, the migration will fail.

  1. Log in to the Cisco Crosswork Planning UI.

  2. From the main menu, choose Collector > Migration.

  3. Click Actions and select Configuration migration.

    The Import Configuration File page appears.

    Figure 1. Import Configuration File page

  4. Select WAN Automation Engine from the Import type drop-down list.

  5. Click Browse and select the wae_networks.cfg file.

  6. (Optional) To overwrite the existing collector configuration, check the Overwrite the existing data check box.

  7. Click Import.

The system proceeds with the import using your configuration. You can monitor the progress on the Migration page (Collector > Migration). Once the import is successful, the Import status column displays Success.

What to do next


Note

After migrating from Cisco WAE to Cisco Crosswork Planning, the Telnet and SSH settings are not preserved. You need to manually verify and update these settings, if required.

Migrate collector configurations between Cisco Crosswork Planning instances

This section explains how to migrate collector configurations from one Cisco Crosswork Planning instance (source) to the other (target).


Note

If using the SR-PCE collector in your configurations, ensure to update the SR-PCE host and Backup SR-PCE host fields manually after migration. This is necessary because, these fields are not updated while migrating the collector configurations between Cisco Crosswork Planning instances.

Procedure

Step 1

Download the collector configuration file from the source machine.

  1. Log in to the Cisco Crosswork Planning instance from which you want to migrate the configuration.

  2. From the main menu, choose Collector > Migration.

  3. Click Actions and select Configuration backup.

    The collector configuration file is downloaded to your local machine.

Step 2

Import the collector configuration file to the target machine.

  1. Log in to the Cisco Crosswork Planning instance to which you want to migrate the configuration.

  2. From the main menu, choose Collector > Migration.

  3. Click Actions and select Configuration migration.

    The Import Configuration File page appears.

    Figure 2. Import Configuration File page

  4. Select Crosswork planning from the Import type drop-down list.

  5. Click Browse and select the collector configuration file downloaded earlier in the Step 1 (c).

  6. (Optional) If you want to overwrite the existing collector configuration, check the Overwrite the existing data check box.

  7. Click Import to import the collector configuration file.

The system proceeds with the import using your configuration. You can monitor the progress on the Migration page (Collector > Migration). Once the import is successful, the Import status column displays Success.

What to do next


Note

In case of traffic collection, if the traffic poller agent status is displayed as down on the Agent page after migration, even though traffic collection has run successfully, follow these steps:

  1. On the Collections page, click Edit collection for the collection corresponding to the agent.

  2. On the Traffic collection configuration page, uncheck the Traffic collection check box and save the configuration.

  3. Re-enable the Traffic collection check box and save the configuration again.