Upgrading to DSE 6.0 or DSE 6.7 from DataStax Installer installations

Strategy to upgrade to DSE 6.0 or DSE 6.7 when earlier versions of DSE were installed using the DataStax Installer.

The DataStax Installer is not available for DataStax Enterprise (DSE) 6.0 and later. Use this strategy to upgrade to DSE 6.0 or DSE 6.7 when DSE 5.0 or DSE 5.1 was installed using the DataStax Installer.

This strategy advises only the high-level steps for converting from DataStax Installer installations. Be sure to read all of the upgrade documentation, starting with Planning your DataStax Enterprise upgrade. Contact DataStax Support for questions.

Attention: Read and understand these instructions before upgrading. Carefully reviewing the planning and upgrading instructions can ensure a smooth upgrade and avoid pitfalls and frustrations.
This upgrade strategy has two required steps:
  1. Migrate from the standalone installer installation to tarball or package installation for the same DSE version.
  2. Upgrade from that DSE version to your target DSE version following the DSE upgrade documentation.

DataStax Enterprise and Apache Cassandra™ configuration files

Configuration file Installer-Services and package installations Installer-No Services and tarball installations
DataStax Enterprise configuration files
byoh-env.sh /etc/dse/byoh-env.sh install_location/bin/byoh-env.sh
dse.yaml /etc/dse/dse.yaml install_location/resources/dse/conf/dse.yaml
logback.xml /etc/dse/cassandra/logback.xml install_location/resources/logback.xml
spark-env.sh /etc/dse/spark/spark-env.sh install_location/resources/spark/conf/spark-env.sh
spark-defaults.conf /etc/dse/spark/spark-defaults.conf install_location/resources/spark/conf/spark-defaults.conf
Cassandra configuration files
cassandra.yaml /etc/cassandra/cassandra.yaml install_location/conf/cassandra.yaml
cassandra.in.sh /usr/share/cassandra/cassandra.in.sh install_location/bin/cassandra.in.sh
cassandra-env.sh /etc/cassandra/cassandra-env.sh install_location/conf/cassandra-env.sh
cassandra-rackdc.properties /etc/cassandra/cassandra-rackdc.properties install_location/conf/cassandra-rackdc.properties
cassandra-topology.properties /etc/cassandra/cassandra-topology.properties install_location/conf/cassandra-topology.properties
jmxremote.password /etc/cassandra/jmxremote.password install_location/conf/jmxremote.password
Tomcat server configuration file
server.xml /etc/dse/resources/tomcat/conf/server.xml install_location/resources/tomcat/conf/server.xml

Prerequisites

For DSE 5.0 or DSE 5.1 installations, you must determine if the DataStax Installer was used to create:
  • Services installation
    Typically when the DSE installer was run with root permissions. With a services installation, you start DSE using the service dse start command.
    Tip: For the smoothest transition from a services installation, DataStax recommends the package install method. When installed from a package (Yum or APT), DataStax Enterprise runs as a service.
  • No-services installation
    When the DSE installer was run without root permissions or with custom directories. With a no-services installation, you start DSE with the dse command.
    Tip: For the smoothest transition from a no-services installation, DataStax recommends the tarball install method. When installed from a tarball, DataStax Enterprise runs as a stand-alone process.

The installation method used determines the migration steps.

Reduce risks
You can reduce risks and effort by employing a continual upgrade strategy to provide access to product improvements and new features and reduce version impacts. Ensure that you repair your nodes regularly. Node repair ensures that data on a replica is consistent with data on other nodes.
Perform this migration on each node in the cluster
In production clusters where service cannot be interrupted, perform this migration in a rolling fashion. Ensuring that each node is healthy and able to service queries for existing data before proceeding to the next node.

Procedure

  1. Verify the current DSE version. 
    dse -v
    Important: You must install the exact patch version to successfully complete the migration.
  2. Back up the configuration files.
  3. Back up your data. DataStax recommends backing up your data prior to any version upgrade, including logs and custom configurations. A backup provides the ability to revert and restore all the data used in the previous version if necessary.
    Tip: OpsCenter provides a Backup service that manages enterprise-wide backup and restore operations for DataStax Enterprise clusters. OpsCenter 6.5 and later is recommended.
  4. Use the DataStax Installer to uninstall your current version:
    Important: When prompted, be sure to keep the existing data and configuration files in place.
  5. Use the appropriate steps for converting your existing DSE installation:

Converting to Yum installation on RHEL-based systems

Steps to change an existing DSE services installation that was created using the DataStax Installer to a Yum-based package installation.

The DataStax Installer is not available for DSE 6.0 and later. Follow these steps to change an existing DSE services installation that was created using the DataStax Installer to a Yum-based package installation.

Prerequisites

The packages you install must match the existing DSE patch release version that you verified in 1 in Upgrading to DSE 6.0 or DSE 6.7 from DataStax Installer installations.

  1. Move the existing DSE Installer backup directory to another location: 
    cd /usr/share/dse
    sudo mv backups backups.old
  2. Configure and install DSE at the same patch version that you verified in 1 in Upgrading to DSE 6.0 or DSE 6.7 from DataStax Installer installations. Because you are keeping the existing configuration files in place when you used the DataStax Installer to uninstall your current version, the Yum installation respects those files and they will be used by the package installed version of DSE. Use the installation instructions for your DSE version:
    For example, to install DSE 5.1.11:
    sudo install dse-full=5.1.11-1 
dse=5.1.11-1 dse-libsolr=5.1.11-1 dse-libtomcat=5.1.11-1 
dse-liblog4j=5.1.11-1 dse-libcassandra=5.1.11-1 dse-libspark=5.1.11-1 
dse-libgraph=5.1.11-1 dse-libhadoop2-client-native=5.1.11-1 
dse-libhadoop2-client=5.1.11-1
  3. Repeat these steps on each remaining node.

Converting to APT installation on Debian-based systems

Steps to change an existing DSE services installation that was created using the DataStax Installer to a APT-based package installation.

The DataStax Installer is not available for DSE 6.0 and later. Follow these steps to change an existing DSE services installation that was created using the DataStax Installer to a APT-based package installation.

Prerequisites

The packages you install must match the existing DSE patch release version that you verified in 1 in Upgrading to DSE 6.0 or DSE 6.7 from DataStax Installer installations.

  1. Move the old DSE Installer backup directory to another location: 
    cd /usr/share/dse
    sudo mv backups backups.old
  2. Configure and install DSE at the same patch version that you verified in 1. Use the version-appropriate installation instructions but add Dpkg options to the apt-get install step.
    For example, to install DSE 5.1.11:
    sudo apt-get -o Dpkg::Options::="--force-confdef" -o 
Dpkg::Options::="--force-confold" install dse-full=5.1.11-1 
dse=5.1.11-1 dse-libsolr=5.1.11-1 dse-libtomcat=5.1.11-1 
dse-liblog4j=5.1.11-1 dse-libcassandra=5.1.11-1 dse-libspark=5.1.11-1 
dse-libgraph=5.1.11-1 dse-libhadoop2-client-native=5.1.11-1 
dse-libhadoop2-client=5.1.11-1

    This change keeps the existing configuration files in place and prevents them from being overwritten by the new packages

    Be sure to list all packages with the same version.
  3. Repeat these steps on each remaining node.

Converting to binary tarball installation

Steps to change an existing DSE no-services installation that was created using the DataStax Installer to a binary tarball installation.

The DataStax Installer is not available for DSE 6.0 and later. Follow these steps to change an existing DSE no-services installation that was created using the DataStax Installer to a binary tarball installation.

DataStax Enterprise and Apache Cassandra™ configuration files

Configuration file Installer-Services and package installations Installer-No Services and tarball installations
DataStax Enterprise configuration files
byoh-env.sh /etc/dse/byoh-env.sh install_location/bin/byoh-env.sh
dse.yaml /etc/dse/dse.yaml install_location/resources/dse/conf/dse.yaml
logback.xml /etc/dse/cassandra/logback.xml install_location/resources/logback.xml
spark-env.sh /etc/dse/spark/spark-env.sh install_location/resources/spark/conf/spark-env.sh
spark-defaults.conf /etc/dse/spark/spark-defaults.conf install_location/resources/spark/conf/spark-defaults.conf
Cassandra configuration files
cassandra.yaml /etc/cassandra/cassandra.yaml install_location/conf/cassandra.yaml
cassandra.in.sh /usr/share/cassandra/cassandra.in.sh install_location/bin/cassandra.in.sh
cassandra-env.sh /etc/cassandra/cassandra-env.sh install_location/conf/cassandra-env.sh
cassandra-rackdc.properties /etc/cassandra/cassandra-rackdc.properties install_location/conf/cassandra-rackdc.properties
cassandra-topology.properties /etc/cassandra/cassandra-topology.properties install_location/conf/cassandra-topology.properties
jmxremote.password /etc/cassandra/jmxremote.password install_location/conf/jmxremote.password
Tomcat server configuration file
server.xml /etc/dse/resources/tomcat/conf/server.xml install_location/resources/tomcat/conf/server.xml

Prerequisites

The version you install must match the existing DSE patch release version that you verified in 1 in Upgrading to DSE 6.0 or DSE 6.7 from DataStax Installer installations.

  1. DSE Analytics nodes: Re-create the Spark RDD directory, adjusting the base direction as appropriate: 
    mkdir ~/dse/spark/rdd
  2. Download DSE at the same patch version that you verified in 1 in Upgrading to DSE 6.0 or DSE 6.7 from DataStax Installer installations. Use the installation instructions for your DSE version:
  3. Extract the tarball into a different directory:
    For example, to extract the DSE 5.1.11 tarball to /tmp/dse511tar:
    tar xvzf dse-5.1.11-bin.tar.gz -C /tmp/dse511tar
  4. To configure the newly installed DSE version (same as your original version):
    1. Compare your backup configuration files to the new tarball configuration files:
      • Look for any deprecated, removed, or changed settings.
      • Transfer customizations from the no-services installation of your current DSE version into the tarball installation.
      • Be sure to use the same directory locations as set in the original version.
  5. Repeat these steps on each remaining node.
  6. Start the DSE cluster and verify proper operation for the tarball DSE installation.
  7. After all nodes are confirmed to be operating, the tarball installation is eligible for upgrade to the target DSE 6.0 or 6.7 version.