Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Offline Upgrade from Enterprise Analytics to Operational Insights

    Learn more about the per-node procedure for an offline cluster upgrade across the Enterprise Analytics to Operational Insights rename, for both .rpm and .deb package formats.

    Operational Insights replaces Enterprise Analytics as the product name, starting with this release, and the rename changes both the package name and the install-prefix used on every node. Because standard package managers, such as apt and yum/dnf, have no built-in way to know that the operational-insights package is meant to replace enterprise-analytics, an ordinary in-place upgrade does not carry a node across this rename safely. Use the following offline, per-node procedure to perform an upgrade that handles the package renaming.

    A plain apt upgrade or yum update does not pick up Operational Insights, and fails silently: the node stays on Enterprise Analytics with no error.

    If you can upgrade with the cluster online, see Upgrade an Online Cluster. That procedure does not require any special handling for the Enterprise Analytics to Operational Insights rename. Use this page only if you’re upgrading with the cluster offline, which does require the rename-specific steps described here. Complete the cluster-level steps in Prepare the Cluster before you start on the first node. For nodes that run in Docker containers, see Offline Upgrade of a Docker Cluster from Enterprise Analytics to Operational Insights instead.

    Prerequisites

    • This is a per-node procedure, and the cluster is down for its entire duration.

    • Rolling back from Operational Insights to Enterprise Analytics is not supported.

    • Nothing under the node’s var directory is moved at any point, with one exception: the conditional data-relocation step, which applies only if the node’s data directory sits under /opt/couchbase/var.

    • Note the node’s UUID and its configured data path now, so you can verify against them at the end. Both come from the same call:

      curl -s -u <admin>:<password> http://127.0.0.1:8091/nodes/self \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["nodeUUID"], d["storage"]["hdd"][0]["path"])'

    Upgrade Procedure for RHEL (rpm/dnf)

    Use this procedure on nodes that run the .rpm package format.

    Prerequisites

    • The successor package refuses to install while Enterprise Analytics is present; the check runs from the package’s own %pre script, so that an operator cannot reach the install step without first stopping, backing up, and removing the predecessor. Do not try to bypass it: rpm -i --noscripts (or --nopre, or dnf’s --setopt=tsflags=noscripts) skips the check and lays both products on top of each other.

    • You will not see dnf offer --allowerasing or --skip-broken for this install, because the successor declares no conflict with the predecessor for either flag to resolve. If you meet either flag in another context on this node, do not take it: --allowerasing erases the other product and runs its removal scripts before the install it was meant to enable ever runs, leaving the node stripped and with nothing installed.

    • A dnf versionlock entry on the predecessor does not block the removal step below; the removal proceeds normally.

    • Do not purge, do not delete /opt/enterprise-analytics, and do not move the var tree yourself. The node’s configuration records absolute paths that nothing can rewrite.

    Procedure

    1. Stop the node with the following command:

      systemctl stop enterprise-analytics

    2. Use the following command to copy the node’s state aside. This deliberately excludes the bulk data: it’s never touched, and copying it would be far too large. If you skip this step, see If You Skipped the State Backup.

      mkdir -p /var/tmp/ea-state-backup
tar -C /opt/enterprise-analytics/var/lib/couchbase -cf - --exclude=./data --exclude=./logs . \
  | tar -C /var/tmp/ea-state-backup -xf -

    3. Remove the predecessor:

      dnf remove -y enterprise-analytics

      This deletes 23 paths from the state tree, including config/chronicle, config/certs, config/config.dat, config/dist_cfg, and ip. It leaves the bulk data, gosecrets.cfg, the data encryption keys, and isasl.pw, since the package does not own those.

    4. Install the successor without letting it start:

      INSTALL_DONT_START_SERVER=1 dnf install -y ./operational-insights-<version>-linux.<arch>.rpm

      Replace <arch> with x86_64 or aarch64 to match the node. uname -m prints the value to use.

      The environment variable is not optional. The package starts the server on install by default, and a server that starts before you restore state in the next step initializes itself as a fresh, empty node.

    5. If the data path you noted begins with /opt/couchbase/var/, you must move the data out of the way before the next step.

      If the data path is anywhere else, such as the Enterprise Analytics default or a separate mount, skip this step.

      Run the following command:

      DATA=<data_path>
DEST=/opt/enterprise-analytics/var/${DATA#/opt/couchbase/var/}
mkdir -p "$(dirname "$DEST")" && mv "$DATA" "$DEST"

      The node is stopped. If you’re working within one filesystem, this is a rename and happens instantly. Across multiple filesystems, this process is a real copy. Make sure you have the time and disk space for this process. If you needed to do this and did not, see If You Skipped the Conditional Data Move.

    6. Restore the state, and point the successor at the tree:

      tar -C /var/tmp/ea-state-backup -cf - . \
  | tar -C /opt/enterprise-analytics/var/lib/couchbase -xf -
chown -R couchbase:couchbase /opt/enterprise-analytics/var
rm -rf /opt/couchbase/var
ln -s /opt/enterprise-analytics/var /opt/couchbase/var

    7. Start the node with the new command for Operational Insights:

      systemctl start operational-insights

    If You Skipped the State Backup

    rpm renames the packaged configuration files it removes, rather than deleting them, so recovery is usually possible. Look for config/config.dat.rpmsave and ip.rpmsave under /opt/enterprise-analytics/var/lib/couchbase, and rename each back to its original name. Which files are renamed varies with what the node had modified, so restore every .rpmsave file you find.

    If You Skipped the Conditional Data Move

    If you did not move the data aside, you cannot recover your data. Restore it from backup, into the path the node records, which you can read back with the verify command.

    Verify Before Moving to the Next Node

    Run the same check you ran at the start, and confirm the values match:

    curl -s -u <admin>:<password> http://127.0.0.1:8091/nodes/self \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["nodeUUID"], d["storage"]["hdd"][0]["path"])'

    Both values must match the ones you noted at the start, and the data path must still exist:

    test -d "<data_path>" && echo data present

    A different UUID means the node reinitialized itself as a new, empty node. Stop it immediately and do not rebalance. The node might still look healthy.

    Upgrade Procedure for Ubuntu and Debian (deb/apt)

    The state-backup step below is mandatory on this format, and there is no recovery if you skip it. The .deb package declares no conffiles, so dpkg deletes the node’s configuration outright on removal and leaves nothing behind.

    Prerequisites

    • The successor package refuses to install while Enterprise Analytics is present, whether the predecessor is in its ordinary state or has been pinned with a hold. The check runs from the package’s own preinst script, so that an operator cannot reach the install step without first stopping, backing up, and removing the predecessor.

    • Do not purge, do not delete /opt/enterprise-analytics, and do not move the var tree yourself. The node’s configuration records absolute paths that nothing can rewrite.

    Procedure

    1. Run the following command to stop the node:

      systemctl stop enterprise-analytics

    2. Use the following command to make a copy of the node’s state aside. On this format, it’s the only copy that exists. If you skip this step, see If You Skipped the State Backup.

      mkdir -p /var/tmp/ea-state-backup
tar -C /opt/enterprise-analytics/var/lib/couchbase -cf - --exclude=./data --exclude=./logs . \
  | tar -C /var/tmp/ea-state-backup -xf -

      Confirm the backup is not empty before continuing:

      ls /var/tmp/ea-state-backup/config/config.dat

    3. Check whether the predecessor is held, then remove it. Use remove, not purge.

      dpkg-query -W -f='${Status}\n' enterprise-analytics

      A held package reports hold ok installed; an ordinary one reports install ok installed. If it’s held, clear the hold by resetting the package’s selection state to install:

      echo "enterprise-analytics install" | dpkg --set-selections

      Then remove the predecessor:

      apt-get remove -y enterprise-analytics

      If you skip the hold check and the package is held, the command above stops without removing anything, and displays the following message:

      E: Held packages were changed and -y was used without --allow-change-held-packages.

      Removal deletes 23 paths from the state tree, including config/chronicle, config/certs, config/config.dat, config/dist_cfg, and ip, and leaves nothing renamed aside. It leaves the bulk data, gosecrets.cfg, the data encryption keys, and isasl.pw, since the package does not own those.

    4. Run the following command to install the successor without letting it start:

      INSTALL_DONT_START_SERVER=1 apt-get install -y ./operational-insights_<version>-linux_<arch>.deb

      Replace <arch> with amd64 or arm64 to match the node. dpkg --print-architecture prints the value to use.

      The environment variable is not optional. The package starts the server on install by default, and a server that starts before you restore state in the next step initializes itself as a fresh, empty node.

    5. If the data path you noted begins with /opt/couchbase/var/, you must move the data out of the way before the next step.

      If the data path is anywhere else, such as the Enterprise Analytics default or a separate mount, skip this step.

      Run the following command:

      DATA=<data_path>
DEST=/opt/enterprise-analytics/var/${DATA#/opt/couchbase/var/}
mkdir -p "$(dirname "$DEST")" && mv "$DATA" "$DEST"

      The node is stopped. If you’re working within one filesystem, this is a rename and happens instantly. Across multiple filesystems, this process is a real copy. Make sure you have the time and disk space for this process. If you needed to do this and did not, see If You Skipped the Conditional Data Move.

    6. Restore the state, and point the successor at the tree:

      tar -C /var/tmp/ea-state-backup -cf - . \
  | tar -C /opt/enterprise-analytics/var/lib/couchbase -xf -
chown -R couchbase:couchbase /opt/enterprise-analytics/var
rm -rf /opt/couchbase/var
ln -s /opt/enterprise-analytics/var /opt/couchbase/var

    7. Start the node with the new command for Operational Insights:

      systemctl start operational-insights

    If You Skipped the State Backup

    No recovery is possible on this format. The node’s configuration is gone. Restore the node from a cluster backup, or rebuild it and rebalance it back into the cluster.

    If You Skipped the Conditional Data Move

    If you did not move the data aside, you cannot recover your data. Restore it from backup, into the path the node records, which you can read back with the verify command.

    Verify Before Moving to the Next Node

    Run the same check you ran at the start, and confirm the values match:

    curl -s -u <admin>:<password> http://127.0.0.1:8091/nodes/self \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["nodeUUID"], d["storage"]["hdd"][0]["path"])'

    Both values must match the ones you noted at the start, and the data path must still exist:

    test -d "<data_path>" && echo data present

    A different UUID means the node reinitialized itself as a new, empty node. Stop it immediately and do not rebalance. The node might still look healthy.

    Known Limitations

    Scenario Status

    Multi-version jumps, upgrading from an older Enterprise Analytics release straight to Operational Insights

    Supported from every previously released version of Enterprise Analytics. The procedure does not depend on the predecessor’s version. This applies to offline upgrade only: for online upgrade, see Upgrade Paths.

    Mixed-OS clusters, with some nodes on .deb and others on .rpm

    Not yet documented. Follow the procedure that matches each node’s own package format.

    Rollback or downgrade, from Operational Insights back to Enterprise Analytics

    Not supported, and not validated.

    Air-gapped environments, with no package repository access during the upgrade

    Covered. This procedure installs the Operational Insights package file directly, so no repository metadata is needed.

    See Also