Upgrading DDAC

Steps for upgrading DDAC 5.1 between patch (point) releases.

Review this information on upgrading DataStax Distribution of Apache Cassandra™ (DDAC) between patch (point) releases, such as upgrading from DDAC 5.1.11 to 5.1.12.

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.

General recommendations

Attention: DataStax recommends upgrading to the latest version of DDAC 5.1.17.

General restrictions and limitations during the upgrade process

Restrictions and limitations apply while a cluster is in a partially upgraded state. The cluster continues to work as though it were on the earlier version of DDAC until all of the nodes in the cluster are upgraded.

Restrictions for all nodes during an upgrade
  • Do not enable new features.
  • Do not run nodetool repair.
  • Do not bootstrap or decommission nodes.
  • 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.
Note: Nodes on different versions might show a schema disagreement during an upgrade.

Preparing to upgrade

  1. 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.
  2. Verify your current product version:
    cassandra -v
  3. Before upgrading, be sure that each node has ample free disk space.

    The required space depends on the compaction strategy. See Disk space.

  4. Familiarize yourself with the changes and features in DDAC and Apache Cassandra™:
    • DDAC release notes for the upgrade version and complete all required actions.
  5. Back up the configuration files to a folder separate from the installation folder.

    The configuration files are overwritten with default values during installation of the new version.

  6. Run nodetool repair to ensure that data on each replica is consistent with data on other nodes.

Upgrade steps

The upgrade process for DDAC provides minimal downtime (ideally zero). During this process, upgrade and restart one node at a time while other nodes continue to operate online. With a few exceptions, the cluster continues to work as though it were on the earlier version of DDAC until all of the nodes in the cluster are upgraded.

  1. Upgrade order matters. Upgrade nodes in this order:
    • In multiple datacenter clusters, upgrade every node in one datacenter before upgrading another datacenter.
    • Upgrade the seed nodes within a datacenter first.
  2. Run nodetool drain to flush the commit log of the old installation:
    nodetool -h hostname drain 

    This step saves time when nodes start up after the upgrade.

  3. Stop the node.
  4. Install the new product version, Installing the DataStax Distribution of Apache Cassandra™.
  5. To configure the new product version:
    1. Compare your backup configuration files files to the new configuration files:
      • Look for any deprecated, removed, or changed settings.
      • Be sure you are familiar with the Apache Cassandra™ and DDAC changes and features in the new release.
      • Check for any other configuration files that you might have changed. See configuration files.
    2. Merge the applicable modifications into the new version.
  6. Start the node.
  7. Verify that the upgraded datacenter names match the datacenter names in the keyspace schema definition:
    nodetool status
  8. Review the logs for warnings, errors, and exceptions.

    Warnings, errors, and exceptions are frequently found in the logs when starting an upgraded node. Some of these log entries are informational to help you execute specific upgrade-related steps. If you find unexpected warnings, errors, or exceptions, contact DataStax Support.

  9. Repeat the upgrade and restart on each node in the cluster following the recommended upgrade order as described in 1.
  10. After the new version is installed on each node, DataStax recommends upgrading the SSTables on each node.

    Upgrading SSTables is recommended for optimal performance, but is not required for patch releases.

    nodetool upgradesstables

    If the SSTables are already on the current version, the command returns immediately and no action is taken.

    Use the --jobs option to set the number of SSTables that upgrade simultaneously. The default setting is 2, which minimizes impact on the cluster. Set to 0 to use all available compaction threads. For information about nodetool upgradesstables, including how to speed it up, see the DataStax Support KB article Nodetool upgradesstables FAQ.