Upgrading from 3.0.0 to 4.0.0

Introduction

This document describes the necessary steps when upgrading Infinite Scale from release 3.0.0 to 4.0.0.

Read the important notes in the Upgrading Infinite Scale documentation before you start.

Upgrade Steps

  1. Shut down the Infinite Scale instance.

  2. Update Infinite Scale via:

  3. Migrate the Space Index to Messagepack:
    It is important to disable clients and users logging in while the space index migration to messagepack is in progress. To do so, you have two choices:

    1. Start Infinite Scale with only two necessary services. The example uses the binary as base:

      OCIS_RUN_SERVICES="gateway,nats,storage-system,storage-users" \
ocis server

    2. If configured, shut-down or disable the reverse proxy for Infinite Scale.

    Because either the Infinite Scale proxy service is not running or the reverse proxy is inaccessible, no clients or users can login.

  4. Migration process

    During the restart of Infinite Scale, the symlinks of spaces in the DecomposedFS will be migrated to messagepack automatically via the storage-users service.

    1. Monitoring progress via logs

      The start of the migration can be identified in the log by messages like:

      {"level":"info","root":"/var/lib/ocis/storage/users","time":"2023-08-02T06:08:21.002825802Z","caller":"github.com/cs3org/reva/v2@v2.15.0/pkg/storage/utils/decomposedfs/migrator/0004_switch_to_messagepack_space_index.go:46","message":"Migrating /var/lib/ocis/storage/users/indexes/by-user-id/b7a2149b-3320-43a3-9bd2-c216340c212d.mpk to messagepack index format..."}
...
{"level":"info","root":"/var/lib/ocis/storage/users","time":"2023-08-02T06:08:21.028153362Z","caller":"github.com/cs3org/reva/v2@v2.15.0/pkg/storage/utils/decomposedfs/migrator/0005_fix_messagepack_space_index_format.go:37","message":"Fixing index format of /var/lib/ocis/storage/users/indexes/by-user-id/b7a2149b-3320-43a3-9bd2-c216340c212d.mpk"}

      When migration has finished - which can take a while depending on the quantity of spaces - you can see log messages like this:

      {"level":"info","time":"2023-08-02T06:08:21.026943689Z","caller":"github.com/cs3org/reva/v2@v2.15.0/pkg/storage/utils/decomposedfs/migrator/0004_switch_to_messagepack_space_index.go:92","message":"done."}
...
{"level":"info","time":"2023-08-02T06:08:21.028422073Z","caller":"github.com/cs3org/reva/v2@v2.15.0/pkg/storage/utils/decomposedfs/migrator/0005_fix_messagepack_space_index_format.go:66","message":"done."}

    2. Monitoring progress via command

      • Use the command below to check the status of the migration steps.

      • Replace <path-to-decomposedFS> with the physical path of the environment variable:
        OCIS_BASE_DATA_PATH + /storage/users
        Example: /var/lib/ocis/storage/users

      • For more details see the Base Data Directory documentation.

      • Command

        ocis migrate decomposedfs -r <path-to-decomposedFS> list

        Depending on the number of steps to process, you will see an output like the following:

        +-----------+-----------+---------+
| Migration |   State   | Message |
+-----------+-----------+---------+
|      0001 | succeeded |         |
|      0002 | succeeded |         |
|      0003 | succeeded |         |
|      0004 | succeeded |         |
|      0005 | succeeded |         |
+-----------+-----------+---------+

  5. Run the "repair and migrate jsoncs3 indexes" command:

    • Note, run this command only if there are shares present.

    • If you run this command and no shares are present, an error will be printed like the following:
      error: not found: list container: error: not found: jsoncs3-share-manager-metadata/storages
      This error has no impact and can be neglected.

    ocis migrate rebuild-jsoncs3-indexes

    When finished, you will see an output like this:

    Scanning storage storage-users-1 (1/1)
  Rebuilding space 1/1...  done
done

  6. Finally, either start the Infinite Scale instance as usual or re-enable the reverse proxy.

  7. Check your Instance
    When the instance has started successfully, check the logs for any unusual entries.

Manage Breaking Changes

  • All environment variables that were marked for deprecation in Infinite Scale release 4.0.0 have finally been removed.

  • Client pool selectors have changed from IP addresses 127.0.0.1:9xxx to service names com.owncloud.api.*. There is no need to configure them at the moment.

How to Identify if You Are Affected

  • If you are using deprecated environment variables in your config.
    See the deprecation notices in each service in the List of Services and the Global Environment Variables. Note that you need to select the 3.0.0 tab to identify deprecations that may affect you.

  • If you have changed the default configuration for the OCIS_REVA_GATEWAY environment variable.

In all other cases, there is nothing that needs to be done as the new defaults for client pool selectors will be used automatically.

How to Manage the Change

  • Manage deprecated variables

    • Environment variables that have been deprecated without successor can safely be removed from the configuration. These envvars do not harm as they are not used anymore.

    • Environment variables that have been deprecated with a successor need to be updated accordingly.

  • The OCIS_REVA_GATEWAY environment variable

    Manually reconfigure the environment variable to the new namespace:

    Default used value, new and old

    Global envvar

    Namespace (new)

    IP (old)

    OCIS_REVA_GATEWAY

    com.owncloud.api.gateway

    127.0.0.1:9142