Upgrade DSE OpsCenter

Use this guide to upgrade your version of OpsCenter.

Although OpsCenter’s definition files allow it to manage multiple versions of DSE without immediately upgrading OpsCenter itself, DataStax recommends updating OpsCenter regularly to get the latest features and fixes.

Carefully review all of these instructions before you begin the upgrade process. This can help you understand what to expect, avoid failed upgrades, and minimize issues.

Prepare to upgrade

Before upgrading OpsCenter, carefully consider the following information and follow any recommended or required actions:

  1. Review the release notes and known issues before upgrading OpsCenter, particularly for major version upgrades that can introduce breaking changes.

    Look for new features, deprecated features, and changes to configuration files, metrics, and APIs.

  2. Make sure your target version of OpsCenter is compatible with your version of DataStax Enterprise (DSE).

    • For DSE 6.9, the minimum supported OpsCenter version is 6.8.39 (latest recommended).

    • For DSE 6.8, the minimum supported OpsCenter version is 6.8.0 (latest recommended).

    • For DSE 5.1, the minimum supported OpsCenter version is 6.8.4 (latest recommended).

    For compatibility with earlier versions of DSE or OpsCenter, see OpsCenter compatibility with DSE.

  3. Create a backup of your OpsCenter keyspace in case there is a problem with the upgrade and you need to downgrade or rollback to your current version of OpsCenter.

  4. When upgrading from a version earlier than 6.8.0, be aware of changes to LDAP authentication with multiple role assignments.

    Support for multiple user roles using LDAP authentication

    Users can have multiple roles when using LDAP authentication. If the list of groups assigned to a user map to more than one role in OpsCenter, the user is granted each of the mapped roles. Permissions from all mapped roles are combined into a superset of permissions for that user. For more information, see Add a role for an LDAP user.

    If your upgrade path includes OpsCenter 6.1.10 and later or 6.5.3 and later, you must update custom scripts and applications that use the OpsCenter API when using multiple user roles with LDAP authentication.

    If a custom script or application that uses the OpsCenter API doesn’t account for multiple user roles, the script or application will fail if a user has multiple roles because it cannot find the role attribute. A single role attribute is provided only for users that have one role.

    If your application or script only includes single-role users, no updates are required.

  5. If you want to use Oracle Java instead of OpenJDK or you are upgrading from a version earlier than OpsCenter 6.7.0, be aware that OpsCenter installs OpenJDK by default.

    Starting with OpsCenter 6.7.0, LCM installs OpenJDK as distributed by operating system vendors through .deb or .rpm packages. Existing clusters are migrated to OpenJDK unless you explicitly set Oracle as the Java vendor before running any install or upgrade job from within the new version of OpsCenter.

    To understand how this change effects your OpsCenter installation, see Choosing a Java vendor in Lifecycle Manager.

  6. If you are upgrading from OpsCenter 6.1, you must first upgrade to OpsCenter 6.5 before upgrading to OpsCenter 6.8. Follow the steps in this guide entirely for version 6.5, and then repeat them for 6.8.

  7. Know how to start, stop, and restart OpsCenter.

Upgrade sequence when failover is enabled

If failover is enabled, you must upgrade your OpsCenter instances in the following order:

  1. Stop the secondary (backup) OpsCenter instance.

  2. Stop the primary OpsCenter instance, and then follow the steps to Upgrade your OpsCenter installation, including starting or restarting the opscenterd daemon for the primary instance.

  3. Follow the same steps to upgrade the secondary instance, and then start or restart the secondary instance.

  4. Upgrade agents.

Upgrade your OpsCenter installation

Upgrade your OpsCenter installation, and then start or restart the opscenterd daemon.

  • Package installations

  • Tarball installations

  1. Open the cluster_name.conf file. The default location is /etc/opscenter/clusters/cluster_name.conf.

  2. If you set api_port under the [cassandra] or [storage_cassandra] headers, then delete those entries from cluster_name.conf.

    OpsCenter cannot start if there is an api_port entry under these headers.

  3. On the OpsCenter daemon host, update the packages:

    • Debian or Ubuntu

    • RHEL or CentOS

    sudo apt-get update

    Yum automatically updates package lists when necessary.

  4. Install the upgraded OpsCenter package, specifying the version that you want to upgrade to:

    • Debian or Ubuntu

    • RHEL or CentOS

    sudo apt-get install opscenter=VERSION
    sudo yum install opscenter-VERSION

  5. If your package manager prompts you for opscenterd.conf options, choose to keep your currently installed version.

  6. Restart the OpsCenter daemon:

    sudo service opscenterd restart

  1. Open the cluster_name.conf file. The default location is <install_location>/conf/clusters/cluster_name.conf.

  2. If you set api_port under the [cassandra] or [storage_cassandra] headers, then delete those entries from cluster_name.conf.

    OpsCenter cannot start if there is an api_port entry under these headers.

  3. Download and extract the OpsCenter tarball.

  4. Copy the following files and directories from the old OpsCenter tarball installation directory to the new one:

    conf/clusters/*
conf/event-plugins/*
conf/install_id
conf/logback.xml
conf/opscenterd.conf
./passwd.db
./lcm.db
./keys/lcm.key

    For example, the following command copies the files in /conf/clusters to the new installation directory. You can use similar commands to transfer your files, replacing the placeholders with your actual installation directory paths.

    scp -r <old_directory>/conf/clusters/* <new_directory>/conf/clusters/*

  5. If SSL is enabled, copy the contents of the SSL configuration directory /ssl/* to your new installation directory.

  6. If opscenterd is running, stop the instance, and then start it from the new tarball installation directory.

After upgrading your OpsCenter version, upgrade your DataStax Agents and synchronize your backup history, as explained in the following sections.

Upgrade agents

Your OpsCenter upgrade is incomplete until you upgrade all DataStax Agents to the same version as your OpsCenter installation. Mismatched versions of OpsCenter and agents can cause unexpected behavior and compatibility issues.

Upgrade the DataStax Agents on each node in the managed clusters after restarting the upgraded OpsCenter daemon.

  • Upgrade agents automatically

  • Upgrade agents manually

For package installations, you can use the OpsCenter interface to automatically upgrade the DataStax Agents.

  1. In the OpsCenter interface, click your cluster’s name, select Nodes, and then click the Agents tab.

    OpsCenter 6.1 and later include the OpsCenter and agent compatibility awareness feature that notifies you of potential deprecations and breaking changes on older agent versions.

    The Agents tab shows a warning if there are any agents running an earlier version that might be incompatible with your new version of OpsCenter.

  2. In the DataStax Agents Status View, click Upgrade all agents.

  3. On the Set Up Agents dialog, select Install or start agents automatically, and then click Next.

  4. Provide the authentication credentials and SSH key to connect to the nodes.

    Automatic installation requires that all nodes in the cluster use the same SSH keys. If the nodes don’t use the same SSH keys, you must either normalize the SSH keys across all nodes or manually install the agents.

  5. Click Submit, and then wait while the agents are upgraded.

    You can monitor the upgrade progress on the Agents tab. If there are any issues, OpsCenter shows an error message with a link to more details so you can investigate the issue and retry the upgrade. For more information, see Install DataStax Agents automatically.

To upgrade DataStax Agents manually with tarballs, do the following:

  1. Download the DataStax Agent tarball that matches your version of OpsCenter:

    curl -L http://downloads.datastax.com/enterprise/datastax-agent-VERSION.tar.gz

  2. Copy the new agent.tar.gz file to all nodes in the cluster:

    scp agent.tar.gz node_name

  3. On each node, extract the tarball:

    tar -xvf agent.tar.gz

  4. On each node, copy the contents of /conf/* and /ssl/* from the old DataStax Agent tarball directory to the new tarball directory. In the following examples, replace the placeholders with your actual tarball directory paths.

    scp -r <old_directory>/conf/* <new_directory>/conf/*
    scp -r <old_directory>/ssl/* <new_directory>/ssl/*

For more information and additional manual installation options, see Manually deploy DataStax Agents from a tarball.

Synchronize and repopulate backup history

After upgrading OpsCenter, synchronize and repopulate your backup history.

Downgrade OpsCenter

Downgrading OpsCenter is a manual and case-specific process. If you require a downgrade, contact DataStax Support for assistance before proceeding.

To downgrade, you must have a backup of your OpsCenter keyspace from the earlier version.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com