Upgrading from 2.0.0 to 3.0.0

Table of Contents

Introduction

This document describes the necessary steps when upgrading Infinite Scale from release 2.0.0 to 3.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. Manually add the GRAPH_APPLICATION_ID to the config. The value can be any text string using characters defined by the UUID definition and is preferably a UUID4 string.

    • Either edit the ocis.yaml (preferred and recommended) by adding:

      graph:
  application:
    # required when upgrading ocis to v3.0.0
    id: <your UUID4 string>

    • or by setting GRAPH_APPLICATION_ID as an ENV variable.

    This environment variable will be defined automatically when installing a fresh instance and running ocis init to initialize it.

  4. Automatic Role Assignments have been introduced that need a settings review. All users that do not have a role assigned at the time of their first login will get the role 'user' assigned if the default of the environment variable PROXY_ROLE_ASSIGNMENT_DRIVER is used. The assignment can be changed based to the values of an OpenID Connect Claim of that user using a different setting. See the referenced documentation for more details.

  5. The environment variable OCIS_LDAP_DISABLE_USER_MECHANISM is an option to control the behavior for disabling users. The default value is attribute and requires configuration on the LDAP server. Enabling and disabling users is LDAP implementation specific.

    • If you are using an external LDAP server you can either set OCIS_LDAP_DISABLE_USER_MECHANISM to none to disable it completely or to attribute in which case you need to set OCIS_LDAP_USER_ENABLED_ATTRIBUTE according to your external LDAP server’s requirements.

    • Additionally and due to a bug recently discovered in the IDP service, you must set OCIS_LDAP_USER_ENABLED_ATTRIBUTE="" to overwrite the default setting when OCIS_LDAP_DISABLE_USER_MECHANISM is set to none. This bug will be fixed in a subsequent release.

  6. Delete the full search index. For details about the used path see: OCIS_BASE_DATA_PATH:

    rm -rf <OCIS_BASE_DATA_PATH>/search/*
    The empty search index will be recreated space by space when something changes in a space. You can also use the Infinite Scale CLI to manually trigger a Reindex a Space for Search.

  7. Changes in the Helm Charts
    For any breaking changes that come along with Helm Charts, see the Breaking Changes documentation.

  8. Messagepack Readme First
    If you have manually changed one of the following environment variables to a value other than the default or explicitly set one of the environment variables to the default which was xattrs:

    OCIS_DECOMPOSEDFS_METADATA_BACKEND,
    STORAGE_SYSTEM_OCIS_METADATA_BACKEND,
    STORAGE_USERS_OCIS_METADATA_BACKEND,

    the instance will stay at the configured backend when passing the next step.

    Though you can stay at the xattrs backend, it is highly recommended to migrate to messagepack as the xattrs backend is considered deprecated and will be removed soon.

    To enable migration, remove any of the manually configured environment variables listed above. This can also be done in a later step but it is highly recommended to migrate now.

    If you want to prevent the migration for now, set OCIS_DECOMPOSEDFS_METADATA_BACKEND=xattrs.
    Note that the migration of the metadata backend to messagepack is a one-way process and can not be reverted except via a full restore.

  9. Migrate Metadata to Messagepack:
    It is important to disable clients and users logging in while the migration to messagepack is in progress. To do so, start Infinite Scale with only two necessary services. The following example uses the binary as base:

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

    Because the proxy service is not running, no clients or users can login. During the restart of Infinite Scale, the metadata store in the DecomposedFS will be migrated to messagepack automatically via the storage-users service. The start of the migration can be identified in the log with a message like:

    {"level":"info","root":"/var/lib/ocis/storage/users","time":"2023-06-16T12:21:49.441395153Z","caller":"github.com/cs3org/reva/v2@v2.14.0/pkg/storage/utils/decomposedfs/migrator/0003_switch_to_messagepack_metadata.go:45","message":"Migrating to messagepack metadata backend..."}

    When migration has finished - which can take a while depending on the quantity of files - you can see a log message like the one below:

    {"level":"info","time":"2023-06-16T12:30:05.267986656Z","caller":"github.com/cs3org/reva/v2@v2.14.0/pkg/storage/utils/decomposedfs/migrator/0003_switch_to_messagepack_metadata.go:106","message":"done."}`

    Finally, start the Infinite Scale instance as usual.

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