This page outlines how to upgrade Cribl LogStream's Single-Instance or Distributed Deployment packages along one of the following supported upgrade paths:

• v2.x ==> v2.x
• v1.7.x/v2.0.x ==> v2.x.x
• v1.6.x or below ==> v1.7.x ==> v2.x.x

🚧

See notes on Upgrading to LogStream 2.3 below.

LogStream does not support direct upgrades from a Beta to a GA version. To get the GA version running, you must perform a new install.

Standalone/Single-Instance

This path requires upgrading only the single/standalone node:

1. Stop Cribl LogStream.

2. Uncompress the new version on top of the old one.

   On some Linux systems, tar might complain with: cribl/bin/cribl: Cannot open: File exists. In this case, please remove the cribl/bin/cribl directory if it's empty, and untar again. If you have custom functions in cribl/bin/cribl, please move them under $CRIBL_HOME/local/cribl/functions/ before untarring again.

3. Restart LogStream.

Distributed Deployment

For a distributed deployment, the order of upgrade is: Upgrade first the Master Node, then upgrade the Worker Nodes, then commit and deploy the changes on the Master.

Upgrade the Master Node

1. Commit and deploy your desired last version. (This will be your most recent checkpoint.)

   • Optionally, git push to your configured remote repo.

2. Stop Cribl LogStream.

   • Optional but recommended: Back up the entire $CRIBL_HOME directory.

   • Optional: Check that the Worker Nodes are still functioning as expected. In absence of the Master Node, they should continue to work with their last deployed configurations.

3. Uncompress the new LogStream version on top of the old one.

4. Restart LogStream and log back in.

5. Wait for all the Worker Nodes to report to the Master, and ensure that they are correctly reporting the last committed configuration version.

📘

Workers' UI will not be available until the Worker version has been upgraded to match the version on the Master. Errors like those below will appear until the Worker nodes are upgraded.

Upgrade the Worker Nodes

These are the same basic steps as when upgrading a Standalone Instance, above:

1. Stop Cribl LogStream on each Worker Node.

2. Uncompress the new version on top of the old one.

3. Restart LogStream.

Commit and Deploy Changes on the Master Node

1. Ensure that newly upgraded Worker Nodes report to the Master with their new software version.

2. Commit and deploy the newly updated configuration only after all Workers have upgraded.

Upgrading to LogStream 2.3

As of version 2.3, LogStream Free and One licenses are permanent, but they enforce certain restrictions that especially affect distributed deployments:

• Even if you have more than one Worker Group defined, only one Worker Group will be visible and usable.

  • This will be the first Group listed in $CRIBL_HOME/local/cribl/groups.yml – typically, the default Group. You can edit groups.yml to move the desired Group to the top.

• Your cluster will be limited to 10 Worker Processes across all Worker Nodes.

  • LogStream will balance (or rebalance) these Processes as evenly as possible across the Worker Nodes.

• Authentication will fall back to local authorization. You will not be able to authenticate via Splunk, LDAP, or SSO/OpenID.

• Git Push to remote repos will not be supported through the product.

🚧

If you are upgrading LogStream Free or LogStream One from version 2.2.x or lower, these changes might require you to adjust your existing configuration and/or workflows.

See Licensing for details on all current license options.

As of LogStream 2.3, licenses no longer need to be deployed directly to Worker Groups. The Master will push license information down to Worker Groups as part of the heartbeat.

Splunk App Package Upgrade Steps

🚧

See Deprecation note for v.2.1.

Follow these steps to upgrade from v.1.7, or higher, of the Cribl App for Splunk:

1. Stop Splunk.

2. Untar/unzip the new app version on top of the old one.

   On some Linux systems, tar might complain with: cribl/bin/cribl: Cannot open: File exists. In this case, please remove the cribl/bin/cribl directory if it's empty, and untar again. If you have custom functions in cribl/bin/cribl, please move them under $CRIBL_HOME/local/cribl/functions/ before untarring again.

3. Restart Splunk.

Upgrading from Splunk App v.1.6 (or Lower)

As of v.1.7, contrary to prior versions, Cribl's Splunk App package defaults to Search Head Mode. If you have v.1.6 or earlier deployed as a Heavy Forwarder app, upgrading requires an extra step to restore this setting:

1. Stop Splunk.

2. Untar/unzip the new app version on top of the old one.

3. Convert to HF mode by running: $SPLUNK_HOME/etc/apps/cribl/bin/cribld mode-hwf

4. Restart Splunk.