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:
-
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.
-
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.
-
-
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.
-
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 singlerole
attribute is provided only for users that have one role.If your application or script only includes single-role users, no updates are required.
-
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.
-
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.
-
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:
-
Stop the secondary (backup) OpsCenter instance.
-
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. -
Follow the same steps to upgrade the secondary instance, and then start or restart the secondary instance.
Upgrade your OpsCenter installation
Upgrade your OpsCenter installation, and then start or restart the opscenterd
daemon.
-
Package installations
-
Tarball installations
-
Open the
cluster_name.conf
file. The default location is/etc/opscenter/clusters/cluster_name.conf
. -
If you set
api_port
under the[cassandra]
or[storage_cassandra]
headers, then delete those entries fromcluster_name.conf
.OpsCenter cannot start if there is an
api_port
entry under these headers. -
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.
-
-
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
-
-
If your package manager prompts you for
opscenterd.conf
options, choose to keep your currently installed version. -
Restart the OpsCenter daemon:
sudo service opscenterd restart
-
Open the
cluster_name.conf
file. The default location is<install_location>/conf/clusters/cluster_name.conf
. -
If you set
api_port
under the[cassandra]
or[storage_cassandra]
headers, then delete those entries fromcluster_name.conf
.OpsCenter cannot start if there is an
api_port
entry under these headers. -
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/*
-
If SSL is enabled, copy the contents of the SSL configuration directory
/ssl/*
to your new installation directory. -
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.
-
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.
-
In the DataStax Agents Status View, click Upgrade all agents.
-
On the Set Up Agents dialog, select Install or start agents automatically, and then click Next.
-
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.
-
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:
-
Download the DataStax Agent tarball that matches your version of OpsCenter:
curl -L http://downloads.datastax.com/enterprise/datastax-agent-VERSION.tar.gz
-
Copy the new
agent.tar.gz
file to all nodes in the cluster:scp agent.tar.gz node_name
-
On each node, extract the tarball:
tar -xvf agent.tar.gz
-
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.