Detailed upgrade instructions for Apache Cassandra.
The location of the cassandra.yaml file depends on the type of installation:
- 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:
- 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.
- 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_intervalhas 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:
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.
- In the cassandra.yaml file, set
- Uncomment the
initial_tokenproperty and set it to 1 or to the value of a generated token for a multi-node cluster.
- In the cassandra.yaml file, set
- Familiarize yourself with the changes and features in this release:
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 upgradesstablesWarning: 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.
- Run nodetool drain before shutting down the existing Cassandra service. This prevents overcounts of counter data, and also speeds up restart post-upgrade.
- Stop the node.
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.
- Install the new version of Apache Cassandra:
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.
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.
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).
- Check the logs for warnings, errors, and exceptions.
- Repeat these upgrade steps on each node in the cluster.