Upgrading procedures for Apache Cassandra™ 

Detailed upgrade instructions for Apache Cassandra.

cassandra.yaml 

The location of the cassandra.yaml file depends on the type of installation:

Installer-Services /etc/cassandra/cassandra.yaml
Package installations /etc/cassandra/cassandra.yaml
Installer-No Services install_location/conf/cassandra.yaml
Tarball installations install_location/conf/cassandra.yaml
General upgrade restrictions
  • Do not enable new features.
  • Do not run nodetool repair.
  • During upgrades between major versions, do not bootstrap or decommission nodes.
  • Do not issue these types of CQL queries during a rolling restart: DDL and TRUNCATE.
  • During upgrades, the nodes on different versions might show a schema disagreement.
  • Failure to upgrade SSTables when required results in a significant performance impact and increased disk usage. Upgrading is not complete until the SSTables are upgraded.

Prerequisites

  • Apache Cassandra 2.0.x and 2.1.x - The latest version of the Java SE Runtime Environment (JRE) 7 is required. The JDK is recommended.
  • Apache Cassandra 2.2.x, 3.0.x, and 3.x - The latest version of the Java SE Runtime Environment (JRE) 8 is required. The JDK is recommended.
  • Remove all dead nodes.
    Do not upgrade if nodes in the cluster are down. Use the nodetool removenode command to remove dead nodes.
    Tip: In earlier releases, nodetool removenode was nodetool removetoken.
  • In the old cassandra.yaml, check the value of index_interval and change it if you want a different default value applied to tables during the upgrade. In Cassandra 2.0 and later, index_interval has been moved out of the cassandra.yaml and is now a table property.

    During the upgrade, the value defined in the old cassandra.yaml is applied as the default property to your upgraded tables. You can use CQL to alter this property after the upgrade.

  • If your cluster does not use virtual nodes (vnodes), disable vnodes in each new cassandra.yaml before doing the rolling restart. To disable:
    1. In the cassandra.yaml file, set num_tokens to 1.
    2. Uncomment the initial_token property and set it to 1 or to the value of a generated token for a multi-node cluster.
    Note: Vnodes are enabled by default starting with Cassandra 2.0.0.). Vnodes are not enabled or did not exist in earlier Cassandra versions. To switch to vnodes in existing cluster, see Enabling virtual nodes on an existing production cluster for your Cassandra version.

Procedure

  1. Familiarize yourself with the changes and features in this release:
    • General upgrade advice and Cassandra features in NEWS.txt. If you are upgrading from an earlier release, read NEWS.txt all the way back to your current version.
    • Cassandra changes in CHANGES.txt.
  2. When your Apache Cassandra upgrade includes a major version, such as Cassandra 2.1 to 3.0, or a major point release, such as Cassandra 2.0 to 2.1, upgrade the SSTables on each node to ensure that all SSTables are on the current version. If the SSTables are already on the current version, the command returns immediately and no action is taken.
    $ nodetool upgradesstables
    Warning: Failure to upgrade SSTables when required results in a significant performance impact and increased disk usage. Upgrading is not complete until the SSTables are upgraded.
  3. Run nodetool drain before shutting down the existing Cassandra service. This prevents overcounts of counter data, and also speeds up restart post-upgrade.
  4. Stop the node.
  5. Back up your configuration files.

    Depending on how you install the product, these files might get overwritten with default values during the installation. After backing up your configuration, follow the appropriate installation instructions depending on your current installation type.

  6. Install the new version of Apache Cassandra:
  7. Configure the new product.
    Using the backups you made of your configuration files, merge any modifications you have previously made into the new configuration files for the new version. Configuration options change often, so be sure to double check the version restrictions for additional steps and changes regarding configuration.
    Ensure that the latest default values from cassandra-env.sh match your local cassandra-env.sh file.
  8. Start the node.
    An explicit compatibility check is performed on startup. If you skipped any upgrade step, startup fails. Changes from the new release are not modified, and SSTables are not upgraded to the new format. Review the error messages to correct the problem and then start the node.
  9. One each node after the upgrade is performed, run $ nodetool upgradesstables.
    Upgrading SSTables is required for Cassandra upgrades that include a major version (for example, from Cassandra 1.2 to 2.0) or a major point release (for example, from Cassandra 2.0 to 2.1).
  10. Check the logs for warnings, errors, and exceptions.
  11. Repeat these upgrade steps on each node in the cluster.