Upgrade to Cisco Secure Workload Release 4.0

Upgrading Cisco Secure Workload clusters to the latest release is a critical maintenance activity that ensures continued access to new capabilities, security enhancements, and defect fixes. Before starting the upgrade, review the current deployment, verify cluster health, and confirm that backups and maintenance windows are in place to minimize operational impact.

This upgrade guide provides step-by-step instructions for moving Cisco Secure Workload deployments to the latest supported release. This guide is intended for Site reliability engineers (SRE) and platform teams responsible for planning, executing, and validating cluster upgrades in production and non‑production environments.


Note


Raise a ticket with Cisco Technical Assistance Center, to support you with the upgrade process.

You must perform the upgrade procedures with Site Administrator or Customer Support privileges. Ensure that a Customer Support level account has an SSH key that is uploaded for troubleshooting purposes.


Supported Upgrade Paths for Cisco Secure Workload4.0

The following table provides the supported upgrade paths from the earlier version of Cisco Secure Workload, 3.10.6.3 to the latest Cisco Secure Workload, 4.0.1.1.


Note


We recommend upgrading in the specified order without skipping any releases, unless otherwise specified.


Table 1. Supported upgrade paths for Secure Workload 4.0

From

To

Upgrade Type

4.0.2.5

4.0.3.13

Patch release upgrade

4.0.1.1

4.0.2.5

Patch release upgrade

3.10.6.3

4.0.1.1

Major release upgrade

For supported upgrade paths earlier than Cisco Secure Workload, 4.0.1.1, refer to Supported Upgrade Paths for Secure Workload.


Note


Due to some critical issues in the Secure Workload, Release 4.0.1.1, we recommend that you upgrade to 4.0.2.5 immediately after upgrading to 4.0.1.1. For more information about these issues, refer to the Open Issues section in Cisco Secure Workload Release Notes, Release 4.0.1.1.


IPv6 Support for Dual-Stack Mode in Secure Workload

Secure Workload clusters that run on physical hardware can be configured to use IPv6 in addition to IPv4 for certain communications to and from the clusters.

Guidelines

  • Configure both A and AAAA DNS records for FQDN before enabling dual-stack mode for your cluster.

  • External services such as NTP, SMTP, and DNS must be available over both IPv4 and IPv6, for redundancy purposes.

  • To configure dual-stack mode for a cluster, ensure the following:

    • Each of the two cluster-leaf switches must have routable IPv6 addresses on two different networks for redundancy. Provide a default gateway for each network.

    • For 39RU clusters, a site-routable IPv6 network with space for at least 29 host addresses is required.

    • For 8RU clusters, a site-routable IPv6 network with space for at least 20 host addresses is required.

    • The first three host addresses of the site-routable IPv6 network are reserved for the Cisco Secure Workload cluster HSRP configuration and must not be used by any other devices.


Note


  • You can enable the Dual-Stack Mode (IPv6 support) feature when installing or upgrading to 4.0.1.1, 3.10.1.1, or 3.9.1.1 releases. However, the option to enable this feature is not available when you are installing or upgrading to patch releases.

  • Agents communicate with clusters using IPv4 unless you configure them to use IPv6. For more information, refer to Cisco Secure Workload User Guide.


Limitations

If you are considering enabling dual-stack mode, note these limitations:

  • You can enable IPv6 connectivity only during initial deployment or upgrade to a major release. You cannot enable this feature during patch upgrades.

  • Dual-stack mode is supported only on physical hardware or bare metal clusters.

  • IPv6-only mode is not supported if you enable dual-stack mode.

  • After you enable dual-stack mode for the cluster, the configuration remains dual stack.

  • Enable dual-stack mode only for clusters that are not configured with Federation.

  • The enforcement on AIX agents use only IPv4. Note that IPv4 is always enabled even if IPv6 is enabled.

If you have enabled IPv6:

  • You can access the Secure Workload web interface using either IPv6 or IPv4.

  • By default, software agents use IPv4 to connect to the cluster. To enable IPv6 communication with the cluster over IPv6, do this:

    1. On the Secure Workload web interface, from the navigation pane, choose Platform > Cluster Configuration.

    2. Configure the Sensor VIP FQDN setting. For more information, refer to the page-level help on the UI or the Cisco Secure Workload User Guide.

Licensing


Note


  • If your Secure Workload deployment does not currently have a valid Cisco Smart License (or is outside the evaluation period), you must register valid licenses before you upgrade.

  • Site administration privileges are required to manage licenses.

  • To view the status of your licenses, do this:

    In the Cisco Secure Workload web portal, choose Manage > Service Settings > Licenses. If your cluster license registration is out of compliance, a banner with the expiration date information is displayed on the UI.

    For information about obtaining and registering licenses, in the Secure Workload help menu, select Help > Page-Level Help and search for Smart Licensing.


Upgrade to Cisco Secure Workload Release 4.0.x.x.

Upgrade to Cisco Secure Workload Release 4.0.3.13

Before you begin


Note


Limitations

  • Note that Google Chrome and Microsoft Edge are the supported browsers for upgrade.

  • Do not upgrade if any nodes are currently in a decommissioned state or services are unhealthy. Contact Cisco Technical Assistance Center to remediate any issues before proceeding for the upgrade.


Procedure


Step 1

Check the system's health. You cannot perform the upgrade if a service is unhealthy.

  1. On the Secure Workload UI, from the navigation pane, choose Troubleshoot > Service Status.

  2. Look for red circles in the graph, which indicate unhealthy services.

    Alternatively, for a table view of service health, click the list button at the top of the graph, click Expand All, and scroll down the page to view the status of all the services.

  3. If a service is unhealthy, perform the necessary fix to render the service healthy before you proceed with the upgrade.

Step 2

From the navigation pane, choose Platform > Upgrade/Reboot/Shutdown. Follow the on-screen instructions to troubleshoot issues, if any, identified by the prechecks before continuing.

Step 3

For a patch upgrade, ensure that you select Patch Upgrade.

Step 4

Click Send Upgrade Link.

Step 5

Look for an email message with the following subject:

[Tetration][<cluster_name>] Patch Upgrade Initiation Link

The message includes a hyperlink that you must use to perform the upgrade.

Step 6

In the email message, click the Patch Upgrade > Cluster link to open the Secure Workload setup UI.

Step 7

Click Choose File.

Step 8

Select the downloaded patch RPM and click Open.

Step 9

To initiate the upgrade, click Upload to upload the RPM.

Caution

 

During this process, you will temporarily lose connectivity to the Secure Workload setup UI. You may have to wait for a few minutes to regain access to the Secure Workload UI to view the upgrade results. If there is a problem with the upgrade, a red banner is displayed.

Step 10

Click the Book icon to view the logs.

Step 11

Verify the upgrade:

  1. Open the Secure Workload UI in your browser.

  2. From the navigation pane, choose Platform > Upgrade/Reboot/Shutdown.

  3. Click History and verify that the Status column displays Succeeded.

Step 12

After confirming that the upgrade is successful, click Disable Patch Upgrade Link.



Note


When Secure Workload clusters are upgraded, the Edge and Ingest appliance controllers, along with the containerized services running on these appliances, are automatically upgraded to the corresponding cluster version. However, the underlying operating system (OS) on the appliances is not updated as part of this process.

To ensure that the underlying OS includes the latest security updates and package enhancements, customers are advised to redeploy both the Edge and Ingest appliances using the latest Ingest OVA. Each major release provides updated OVA files that incorporate a newer operating system and the most recent software packages, delivering improved hardening and a strengthened security posture.

The redeployment procedure requires decommissioning and removing the existing appliances, deploying new appliances using the latest OVA image while retaining the same IP addresses and configurations, and subsequently re-adding the connectors.

Be advised that this activity results in a brief, planned interruption to telemetry ingestion.


Upgrade to Cisco Secure Workload Release 4.0.2.5

Before you begin


Note


Limitations

  • Note that Google Chrome and Microsoft Edge are the supported browsers for upgrade.

  • Do not upgrade if any nodes are currently in a decommissioned state or services are unhealthy. Contact Cisco Technical Assistance Center to remediate any issues before proceeding for the upgrade.


Procedure


Step 1

Check the system's health. You cannot perform the upgrade if a service is unhealthy.

  1. On the Secure Workload UI, from the navigation pane, choose Troubleshoot > Service Status.

  2. Look for red circles in the graph, which indicate unhealthy services.

    Alternatively, for a table view of service health, click the list button at the top of the graph, click Expand All, and scroll down the page to view the status of all the services.

  3. If a service is unhealthy, perform the necessary fix to render the service healthy before you proceed with the upgrade.

Step 2

From the navigation pane, choose Platform > Upgrade/Reboot/Shutdown. Follow the on-screen instructions to troubleshoot issues, if any, identified by the prechecks before continuing.

Step 3

For a patch upgrade, ensure that you select Patch Upgrade.

Step 4

Click Send Upgrade Link.

Step 5

Look for an email message with the following subject:

[Tetration][<cluster_name>] Patch Upgrade Initiation Link

The message includes a hyperlink that you must use to perform the upgrade.

Step 6

In the email message, click the Patch Upgrade > Cluster link to open the Secure Workload setup UI.

Step 7

Click Choose File.

Step 8

Select the downloaded patch RPM and click Open.

Step 9

To initiate the upgrade, click Upload to upload the RPM.

Caution

 

During this process, you will temporarily lose connectivity to the Secure Workload setup UI. You may have to wait for a few minutes to regain access to the Secure Workload UI to view the upgrade results. If there is a problem with the upgrade, a red banner is displayed.

Step 10

Click the Book icon to view the logs.

Step 11

Verify the upgrade:

  1. Open the Secure Workload UI in your browser.

  2. From the navigation pane, choose Platform > Upgrade/Reboot/Shutdown.

  3. Click History and verify that the Status column displays Succeeded.

Step 12

After confirming that the upgrade is successful, click Disable Patch Upgrade Link.


Upgrade to Cisco Secure Workload Release 4.0.1.1

You can upgrade from Secure Workload, Release 3.10.5.6 to Secure Workload, Release 4.0.1.1.

Procedure


Step 1

Go to https://software.cisco.com/download/home/286309796/type/286309874/release/ and download the applicable RPM files for your deployment.

For an 8RU or 39RU system, download the following RPMs:

  • tetration_os_UcsFirmware_k9-4.0.1.1-1.x86_64.rpm

  • tetration_os_base_rpm_k9-4.0.1.1-1.el9.x86_64.rpm

  • tetration_os_adhoc_k9-4.0.1.1-1.el7.x86_64.rpm

  • tetration_os_mother_rpm_k9-4.0.1.1-1.el7.x86_64.rpm

  • tetration_os_rpminstall_k9-4.0.1.1-1.noarch.rpm

  • tetration_os_enforcement_k9-4.0.1.1-1.el6.x86_64.rpm

  • tetration_os_nxos_k9-4.0.1.1-1.x86_64.rpm

  • tetration_os_supplement_k9-4.0.1.1-202510280718.noarch.rpm

    Note

     

    This timestamp within the filename is an instance, we recommend that you always use the latest timestamp.

For virtual system, refer to Appendix 2: For a Virtual System to download the RPMs.

Step 2

Verify that the MD5 checksum of the downloaded RPMs matches the MD5 checksum on Cisco.com.

Step 3

Check the system's health. You cannot perform the upgrade if a service is unhealthy.

  1. On the Secure Workload UI, from the navigation pane, choose Troubleshoot > Service Status.

  2. Look for red circles in the graph, which indicate unhealthy services.

    Alternatively, to see a table view of service health, click the list button at the top of the graph, click Expand All, and scroll down the page to view the status of all the services.

  3. If a service is unhealthy, perform the necessary fix to render the service healthy before you proceed with the upgrade.

Step 4

Create a snapshot of the cluster to help troubleshoot any issues during the upgrade. To do this, from the navigation pane, choose Troubleshoot > Snapshots > Create Snapshot > Classic Snapshot.

  • In the Comments field, enter a comment for the snapshot.

  • Click Create Snapshot.

Note

 

Do not change the default settings.

Step 5

Proceed for the upgrade after taking a Snapshot of the cluster. From the navigation pane, choose Platform > Upgrade/Reboot/Shutdown.

Step 6

Under the Upgrade tab, ensure that you follow the on-screen instructions, do not skip any steps.

Step 7

Troubleshoot issues, if any, identified during the prechecks before proceeding to the next step. Click Generate Upgrade link.

The logged in site administrator or customer support receives an email with the subject:

[Tetration Analytics] Upgrade Initiation Link

Note

 

The link and token is also displayed on the UI.

Step 8

In the Secure Workload setup portal:

  • Click Choose File to upload the RPM files.

  • Navigate to the location and select tetration_os_rpminstall_k9-4.0.1.1-1.noarch.rpm, and click Open.

  • Click Upload to upload the file.

  • Click Install to upload software (_rpminstall_k9).

    After the upload and install of uploaded software is complete, load the dependencies and push these onto staging for deployment. You can view the versions of the currently deployed RPM file and the staged RPM file.

  • To select the appropriate RPM file, click Choose File, select the file and click Upload to stage the RPM file.

    Repeat this step for all the dependent RPMs based on your cluster deployment. Refer to Step 1. for the list of RPM files.

Note

 

The rows that are highlighted in amber indicate the RPMs that were loaded successfully. If there are any issues, click Status to view the log.

Step 9

Click Install to deploy the RPM files.

The operation typically takes a few minutes. If the uploaded files do not display after 10–15 minutes, refresh the page.

Note

 

While tetration_os_mother_rpm_k9 is processing, it is normal that manual refresh may not reload the page. Wait for 10 minutes and refresh the page.

Some browsers cache web packages can cause distorted rendering during tetration_os_mother_rpm_k9 processing. In such cases, close the browser and open the Upgrade the URL again on a new browser instance or in a private browsing session.

Note that these issues are common in older Chrome versions, such as v130.0.x with JavaScript V8 13.0.y. Use the latest Chrome version for the best performance.

Step 10

After the RPM files installation is complete, click Continue, the Site Config portal is displayed. For information on how to configure the cluster set up, refer to Appendix1: Site Configuration in Secure Workload Setup.

During the upgrade process, perform the following checks to ensure:

  • the RPM versions are correct.

  • the cluster is healthy.

  • the site information you provided is valid.

  • the physical clusters are configured correctly and may be upgraded to a newer version of NX-OS software.

  • information fields are validated.

  • NTP is synchronized before deployment starts.

  • name node and secondary name node are not in a failed-over state.

Note

 

On physical clusters, if switches need to be upgraded, the checks can take from several minutes to an hour.

After the checks are complete, an email with the subject is sent to the user: TETRATION CLUSTER MyCluster: Verify Token.

Step 11

Copy the token from the email subject: TETRATION CLUSTER MyCluster: Verify Token to continue with the upgrade process. In the Secure Workload Setup portal, paste the token into the Validation Token field and click Continue.

Important

 

Do not select the Ignore instance stop failures check box unless specifically instructed to do so by a Cisco employee or by Cisco Technical Assistant Center.

The validation checks or the upgrade would take several hours depending on the load and other factors.

Note

 

In Cisco Secure Workload, release 4.0, the maintenance page (deploy / upgrade / patch) is migrated to HTTPs schema. If the UI does not refresh automatically, refresh the UI. You will be prompted to accept a self-signed certificate so the browser can load the page again. Only when the green progress bar reaches 100%, the upgrade is complete and all the instances will display the Deployed status.

After the orchestrator upgrade completes, manually refresh the page to display the upgrade progress.

Step 12

Verify the upgrade:

  1. Open the Secure Workload UI in your browser.

  2. From the navigation pane, click Platform > Upgrade/Reboot/Shutdown.

  3. Click History and verify that the Status column displays Succeeded.

  4. After upgrading to Secure Workload, Release 4.0.1.1, make the required changes to benefit from enhancements in this release.

    • If you have enabled IPv6, you can access the Secure Workload web interface by using either IPv4 or IPv6 address. By default, agents continue to connect to the cluster using IPv4. If you want software agents to be able to communicate with the cluster using IPv6, from the navigation pane, choose Platform > Cluster Configuration.

    • Configure the Sensor VIP FQDN setting. For more information, see the Set up System Configurations in the Secure Workload user guide.

In Cisco Secure Workload, releases 4.0 and earlier, the orchestrator VMs upgrade before other components. This process takes between 30 to 60 minutes as the progress bar moves from 0 to 95%. After the orchestrator upgrade is complete, the remaining components are upgraded. At this point, the progress bar resets to 0%.

After the upgrade is complete, the site administrator loads a certificate in the UI Manage > Platform > SSL Certificate). For more information on how to upload the SSL certificate, see Maintenance UI.


Appendix 1: Site Configuration in Secure Workload Setup

Starting with Cisco Secure Workload, Release 3.10 and later, SMTP configuration settings are now available under the Email and Authentication tab. During the cluster setup, Site Admins use the SMTP Configuration switch to enable or disable the SMTP settings. However, note that you cannot modify these settings while the upgrade is in progress.

Secure Workload now supports configuration of SMTP using Microsoft Modern Authentication (OAuth) in addition to the basic SMTP authentication. This enhancement offers improved security through industry-standard OAuth 2.0 when connecting to Microsoft SMTP servers. For more information, see SMTP Server Configuration for Cluster and Site Configuration.


Note


Starting from Cisco Secure Workload, Release 3.8 and later, non-ASCII characters are not allowed in any text fields for Site configurations using the Cisco Secure Workload Setup UI.


This section explains the process of Site Admins setting up a site during the Secure Workload cluster set up.

  • Under the General tab, change the SSH public key and click Next.


    Note


    Starting with Cisco Secure Workload, Release 3.10, the Email tab is renamed to Email and Authentication tab. SMTP configuration settings, previously located under the Services tab, are now found under the Email and Authentication tab. A new SMTP configuration switch appears in this tab; however, you cannot modify the settings during an upgrade.


  • Under Email and Authentication, change the UI admin or the admin email address and click Next.

  • (Optional) Under L3, enable the cluster to use IPv6 addresses in addition to IPv4 for certain cluster connectivity after the upgrade. To enable IPv6:

    1. Select the IPv6 check box.

    2. Enter IPv6 addresses in CIDR notation for both Leaf 1 and Leaf 2 switches.

    3. Enter the Leaf1 and Leaf2 IPv6 default gateway.

    4. Click Next.

    If you enable IPv6 on this page, you must also configure IPv6 fields on the Network page, described in the next step. For requirements and limitations on dual stack mode, see the Requirements and Limitations for Dual-Stack Mode (IPv6 Support) section.

  • Under Network:

    • If necessary, change the values for CIMC Internal Network, CIMC Internal Network Gateway, DNS Resolver, and DNS Domain.


      Important


      Do not change or remove the existing External Network value. However, you can add more IPv4 networks.


    • If IPv6 is enabled on the L3 page, the IPv6 check box is automatically selected. To specify the IPv6 addresses that are reserved for Cisco Secure Workload, use the approved IPv6 addresses:

      1. Enter IPv6 External Network in CIDR notation.

      2. (Optional) To use IPv6 only for specified addresses, enter individual External IPv6 IPs.

  • Under Service, change the NTP and SMTP values and click Next.

  • Under Security, enable or disable Strong SSL Ciphers for Agent Connections and click Next. Note that the values entered for the UI, Advanced, and Recovery tabs cannot be changed.

  • (Optional) Under Recovery, if the cluster is configured as a standby cluster, the cluster will deploy in standby mode, which includes reduced functionality (supports only warm standby mode).

  • Click Continue.

    • The following checks are performed during the upgrade process to ensure:

      • the RPM versions are correct.

      • the cluster is healthy.

      • the site information you provided is valid.

      • the physical clusters are configured correctly and may be upgraded to a newer version of NX-OS software.

      • information fields are validated.

      • NTP is synchronized before deployment starts.

      • name node and secondary name node are not in a failed-over state.


      Note


      On physical clusters, if switches need to be upgraded, the checks can take several minutes to an hour. After the checks are complete, an email with the subject is sent to the user: TETRATION CLUSTER MyCluster: Verify Token. Copy the token from the email and use it to continue with the upgrade.


Appendix 2: For a Virtual System

For a virtual system, download the applicable RPM files for your deployment:

Procedure


Step 1

Go to https://software.cisco.com/download/home/286309796/type/286309874/release/.

Step 2

Download these RPM files for your deployment:

  • tetration_os_ova_k9-4.0.1.1-1.noarch.rpm

  • tetration_os_adhoc_k9-4.0.1.1-1.el7.x86_64.rpm

  • tetration_os_mother_rpm_k9-4.0.1.1-1.el7.x86_64.rpm

  • tetration_os_rpminstall_k9-4.0.1.1-1.noarch.rpm

  • tetration_os_enforcement_k9-4.0.1.1-1.el6.x86_64.rpm

  • tetration_os_supplement_k9-4.0.1.1-202510280718.noarch.rpm

    Note

     

    Note that this timestamp within the filename is an instance, we recommend that you always use the latest timestamp.