23.10 (Cobia) Upgrades

There are a variety of options for upgrading to SCALE 23.10.

See the Software Status page for iXsystems’ software version recommendations based on user type.

Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new TrueNAS SCALE major version.

System configuration files generated from releases before 22.12.4 (Bluefin) are not compatible with 23.10 (Cobia). When available, update the system to 22.12.4 (Bluefin), resolve any migrations from deprecated services to replacement apps, and download a fresh system configuration file before attempting to upgrade.

Log in to the SCALE web interface and go to System Settings > Update. The Update Screen displays the current active update train. For more information on other available trains, see Release Schedules.

When a new maintenance version is available from the current train, TrueNAS SCALE stages available updates. Click Apply Pending Update to install it.

Alternately, upload an .update file and perform a manual update.

Manual Update Process (Click to expand) expand

SCALE Manual update files are available from the TrueNAS SCALE Download page website.

Click Install Manual Update File. The Save configuration settings from this machine before updating? window opens. Click Export Password Secret Seed then click Save Configuration. The Manual Update screen opens.

Click Choose File to locate the update file on the system. Select a temporary location to store the update file. Select Memory Device or select one of the mount locations on the dropdown list to keep a copy in the server.

Click Apply Update to start the update process. A status window opens and displays the installation progress. When complete, a Restart window opens.

Click Confirm, then Continue to restart the system.

Uploading an .update file from another train and manually updating switches the system between train types. Changing trains is a one-way operation! Do not change to a prerelease or nightly release unless the system is intended to permanently remain on early versions and is not storing any critical data.

Upgrading from Bluefin to Cobia when applications are deployed is a one-way operation.

You cannot return to or roll back to an earlier SCALE release by simply activating an earlier release boot environment. You also cannot easily roll back app on-disk data after updating the structure to Cobia. After upgrading to Cobia, deployed apps do not work in the earlier release boot environment because the path to system dataset/ix-applications/docker does not exist in Cobia and is not restored when rolling back.

When apps are deployed in an earlier SCALE major version, you must take snapshots of all datasets that the deployed apps use, then create and run replication tasks to back up those snapshots. After rolling back to the earlier version from 23.10 (Cobia), these snapshots are used to restore the applications datasets to their pre-upgrade condition and allow previously installed apps to resume normal functionality.

At minimum, you need pre-upgrade snapshots of the ix-applications dataset and a recursive snapshot of ix-applications to get the docker dataset, and then snapshots of all datasets apps use as host paths. Without these snapshots, to downgrade to Bluefin requires deleting the app(s) and redeploying it/them.

It is recommended to use replication tasks to copy snapshots to a remote server used for backups of your data. If you do not have a remote server to store backup snapshots, you can create a new pool and dataset on the system for local replications, but this is not a recommended general backup strategy.

When you rollback the TrueNAS SCALE system from Cobia to an earlier SCALE major version, copy the snapshots from the remote backup server to the local system in a new temporary dataset. Create a new dataset on the same pool as the ix-applications dataset (the pool apps use).

1. Verify your Bluefin apps are running (not stopped or in the deploying state), and that you have access to your data and the application web portals.

2. Create and run replication tasks to a remote server. See Setting Up a Remote Replication Task for more information. Before upgrading to Cobia, create and replicate snapshots for:

   • The ix-applications dataset to restore the migration JSON files to the earlier version.
   • A recursive replication of the ix-applications dataset to see the docker snapshot.
   • Snapshots of any datasets that deployed apps use for storage, such as the MinIO app data dataset.

   If a Bluefin app uses host path(s) to existing datasets, such as with the MinIO and the /data dataset, create and run remote replication tasks for these datasets. If you nested these datasets for apps under a parent dataset, set up a recursive remote replication of the parent dataset to create the snapshots of all the nested child datasets the apps use.

3. Upgrade to Cobia and save the configuration file. This is always recommended so you can restore your system configuration if necessary.

Do not replicate remote backup snapshots into the ix-applications dataset! Create a dataset or use an existing dataset on the same pool as the ix-applications dataset to hold these snapshots.

1. Select the earlier release boot environment, make it the active boot environment, then reboot the system. See Managing Boot Environments for more information.

2. Go to the remote system and create and run a replication task to copy the snapshots back to the system you rolled back to an earlier SCALE release. Alternately, create a Pull replication task on the rolled-back system to bring the snapshots from the remote system to the local system.

   Replicate each snapshot: the ix-applications, ix-applications/docker, and all snapshots of datasets set up as host paths in an application.

   When moving a snapshot from a different pool on the same server, replicate to a dataset on the same pool as the ix-applications dataset (for example, tank/repsnaps if ix-applications is in the tank pool).

3. Go to the location of the snapshots, then:

   a. Roll back to the ix-applications snapshot taken before the upgrade. This updates the migration JSON files to the pre-upgrade version of the files.

   b. Locate the ix-applications/docker snapshot, click on it to expand it, then click Clone to Dataset. Rename the dataset to poolname/ix-applications/docker to create the missing docker dataset from this snapshot.

   c. Roll back the snapshots for any dataset used as a host path in an application to the snapshots taken before the upgrade.

4. Go to Shell or open an SSH session and verify the docker dataset exists. Enter:

   cd /mnt/poolname/ix-applications

   ls

   Where poolname is the name of the pool assigned as the pool for applications to use and with the ix-applications dataset.

   The command output now show the docker dataset.

5. Reboot the system.

The applications now show on the Applications > Installed Applications screen. It takes a while for apps to return to the Active state.

Troubleshooting if Apps don't return to an Active state expand

After doing the above, if the applications do not show on the Installed Applications screen, either open an SSH session or go to Shell, cd to the ix-applications dataset location, and remove the app_migrations.json and migrations.json files.

This command is destructive and could interfere with automatic updating for the currently installed applications.

Enter at the prompt:

sudo rm app_migrations.json

When prompted, enter the admin password. Repeat the command for the migrations.json file.

Reboot the system, then return to the Applications > Installed Applications screen. The applications are now visible. Wait for the apps to return to the Active state.

SCALE is a new and maturing software. CORE systems with High Availability enabled (HA) can not be upgraded to SCALE with HA.

Migrating from CORE to SCALE is not recommended when custom modifications have been made to the system database. If any such modifications are present in CORE, these must be reverted before attempting a migration to SCALE. CORE users should always exercise caution and back up their data and system configuration before starting an upgrade.

Systems with TrueNAS CORE major version 12.0 or earlier must update to the latest CORE 13.0 release (e.g. 13.0-U5) prior to migrating to SCALE.

When appropriate, a CORE to SCALE migration is performed with an .iso and USB stick and preserves much of your existing CORE configuration. See Migrating from CORE for the USB migration process.