From 18fb55372016f5911bc82352e4af8ef124057b2f Mon Sep 17 00:00:00 2001 From: mmattel Date: Tue, 5 Mar 2024 12:21:47 +0100 Subject: [PATCH 1/6] prepare ocis migration guide from 4 to 5 --- .../deployment/services/env-var-changes.adoc | 2 +- .../ROOT/pages/migration/upgrading-ocis.adoc | 17 +++ .../migration/upgrading_3.0.0_4.0.0.adoc | 2 +- .../migration/upgrading_4.0.0_5.0.0.adoc | 144 ++++++++++++++++++ 4 files changed, 163 insertions(+), 2 deletions(-) create mode 100644 modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc diff --git a/modules/ROOT/pages/deployment/services/env-var-changes.adoc b/modules/ROOT/pages/deployment/services/env-var-changes.adoc index b0a78def..3e0677d3 100644 --- a/modules/ROOT/pages/deployment/services/env-var-changes.adoc +++ b/modules/ROOT/pages/deployment/services/env-var-changes.adoc @@ -1,6 +1,6 @@ # Changed Environment Variables in Versions :toc: right -:description: This page contains tables with added and removed environment variables between Infinite Scale version 4.0.5 and 5.0.0. +:description: This page contains tables with added and removed environment variables between Infinite Scale version 4.0.0 and 5.0.0. :source_path: {ocis-services-raw-url}{service_tab_1}{ocis-services-final-path}adoc/env-var-deltas/ // https://raw.githubusercontent.com/owncloud/ocis/docs-stable-5.0/services/_includes/adoc/env-var-deltas/ diff --git a/modules/ROOT/pages/migration/upgrading-ocis.adoc b/modules/ROOT/pages/migration/upgrading-ocis.adoc index 6dfb1a8b..2adf607c 100644 --- a/modules/ROOT/pages/migration/upgrading-ocis.adoc +++ b/modules/ROOT/pages/migration/upgrading-ocis.adoc @@ -15,6 +15,23 @@ IMPORTANT: If not explicitly mentioned, any upgrade is forward only and a backst IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrade steps from each release must be taken in order and none can be skipped. +== Version 4.0.0 to 5.0.0 + +=== Notable Changes Requiring Manual Intervention + +* The xref:deployment/container/orchestration/orchestration.adoc#using-our-helm-charts-with-infinite-scale[Helm Chart] has been upgraded. + +=== Breaking Changes Requiring Manual Intervention + +* All environment variables that were marked for deprecation in Infinite Scale release 4.0.0 have finally been removed. +* The default service registry has been changed. +* Service accounts are now needed for some backend operations. +* Resharing is now disabled by default and will be removed from the product. + +=== Upgrade Steps + +For a detailed description of the steps to upgrade, see the xref:migration/upgrading_4.0.0_5.0.0.adoc[Upgrading from 4.0.0 to 5.0.0] documentation. + == Version 3.0.0 to 4.0.0 === Notable Changes Requiring Manual Intervention diff --git a/modules/ROOT/pages/migration/upgrading_3.0.0_4.0.0.adoc b/modules/ROOT/pages/migration/upgrading_3.0.0_4.0.0.adoc index 7e373354..c3f81bef 100644 --- a/modules/ROOT/pages/migration/upgrading_3.0.0_4.0.0.adoc +++ b/modules/ROOT/pages/migration/upgrading_3.0.0_4.0.0.adoc @@ -132,7 +132,7 @@ When the instance has started successfully, check the logs for any unusual entri == Manage Breaking Changes -* All environment variables that were marked for deprecation in Infinite Scale release 4.0.0 have finally been removed. +* All environment variables that were marked for deprecation in Infinite Scale release 3.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 diff --git a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc new file mode 100644 index 00000000..136f4394 --- /dev/null +++ b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc @@ -0,0 +1,144 @@ += Upgrading from 4.0.x to 5.0.0 +:toc: right +:description: This document describes the necessary steps when upgrading Infinite Scale from release 4.0.x to 5.0.0. + +== Introduction + +{description} + +IMPORTANT: Read the important notes in the xref:migration/upgrading-ocis.adoc#introduction[Upgrading Infinite Scale] documentation before you start. + +== Upgrade Steps + +. Shut down the Infinite Scale instance. +. Update Infinite Scale via: ++ +-- +* Docker ++ +[source,bash] +---- +docker pull owncloud/ocis:5.0.0 +---- + +* or get the binary from {ocis-downloadpage-url}?sort=time&order=desc[download.owncloud.com,window=_blank]. +-- + +== Manage Breaking Changes + +* All environment variables that were marked for deprecation in Infinite Scale release 4.0.0 have finally been removed. +* The default service registry has been changed. +* Service accounts are now needed for some backend operations. +* Resharing is now disabled by default and will be removed from the product. +* The structure of the `theme.json` file has changed. + +=== How to Identify if You Are Affected + +* If you are using deprecated environment variables in your config. +** See the xref:deployment/services/env-var-changes.adoc[Added and Removed Environment Variables] documentation. +* If you have changed the default configuration for the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY] environment variable. +* If you have used custom theming in your Infinite Scale instance by providing a custom theme.json file. + +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 `MICRO_REGISTRY` environment variable +** We changed the service registry to use the natsjs key-value store from the `nats` service as a storage. ++ +-- +{empty} +[width="100%",cols="40%,30%,20%"] +|=== +3+^h| Default used value, new and old +h| Global envvar +h| New value +h| Old value + +| xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY] +| nats-js-kv +| memory + +| xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY_ADDR] +| 127.0.0.1:9233 +| +|=== +{empty} +-- + +** If you have more than one container or process for the Infinite Scale deployment: ++ +-- +You need to make the same service registry available to all Infinite Scale processes and expose the micro registry in the container or process where you have the `nats` service running and use that from the other processes as a shared registry. + +Docker compose example with an app provider: + +[source,yaml] +---- +--- +version: "3.7" + +services: + ocis: + environment: + NATS_NATS_HOST: 0.0.0.0 # bind on all interfaces to expose the nats service + ... + ocis-appprovider-collabora: + environment: + # use the shared registry from the ocis container + MICRO_REGISTRY_ADDRESS: ocis:9233 + +---- +-- +* We introduced service accounts in the area of service-to-service communication. We need this change to properly authenticate backend calls which are not triggered by user interaction like search indexing, auto accepting of shares or timed trashbin cleanup jobs. Instances which are migrated from ocis 4.x need manual steps to avoid becoming non functional. ++ +-- +Two new global environment variables have been introduced to manually configure the instance: `OCIS_SERVICE_ACCOUNT_ID` and `OCIS_SERVICE_ACCOUNT_SECRET`. Please set the first one to a random uuid and create a strong secret value for the second one. +[source, sh] +---- +OCIS_SERVICE_ACCOUNT_ID= +OCIS_SERVICE_ACCOUNT_SECRET= +---- + +NOTE: For new deployments starting with ocis 5.0.0, these values are autogenerated by running `ocis init` + +WARNING: If no values are provided during an upgrade, ocis will not start and log a fatal error. +-- + +* We've changed the structure of the `theme.json` file. This was done for several reasons: +** To be able to support multiple client platforms, +** to be able to create a fallback chain of theming information and +** to reduce the amount of configuration needed for theming. + ++ +-- +If you have a custom `theme.json` file, you need to update it to the new structure. + +* The old structure can be found here: https://doc.owncloud.com/ocis/4.0/deployment/webui/webui-theming.html#example-theme[Infinite Scale 4.0 Example Theme, window=_blank]. +* The new structure can be found here: https://owncloud.dev/clients/web/theming/#example-theme[Infinite Scale 5.0 Example Theme, window=_blank]. + +The most important adjustment is the fact, that the old structure only supported multiple themes on a single platform (web). The new structure defines a `common` section and a `clients` section on the root level of the file. + +* The `common` section provides defaults for all client platforms. +* The `clients` section provides platform specific general theming information and a list of themes. + +Note that the "Desktop", "Android" and "iOS" platforms currently lack support for the themes provided by Infinite Scale. + +The theming data from your old `theme.json` file needs to be moved to the "web" section of the new `theme.json` file. +This can be done with copy & paste and only small adjustments, since the structure of a single, web-specific theme within the `theme.json` remains mostly unchanged. +-- + +=== Deprecations + +* Service Registries + +We deprecated some service registries. If your `MICRO_REGISTRY` config is set to one of these values `mdns, nats, kubernetes, etcd, consul` please use `nats-js-kv` in the future (`memory` is only intended for testing environments). + +* Micro caches and stores + +We deprecated some micro caches and stores. If one of your `*_CACHE_STORE` variables is using one of there values `redis-sentinel, redis, etcd, nats, ocmem` please use `nats-js-kv` in the future (`memory` is only intended for testing environments). + +* Resharing + +We have disabled the resharing feature by default. It will be removed from the product. Existing reshares will still be visible to the original resource owner. Creation of new reshares will not be possible. Make sure that `OCIS_ENABLE_RESHARING` is *not* set to `true` in your deployments. From f9c92a2ea7a110c2d6f81216b724a9d2336d5242 Mon Sep 17 00:00:00 2001 From: mmattel Date: Tue, 5 Mar 2024 12:42:09 +0100 Subject: [PATCH 2/6] small text fixes --- modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc index 136f4394..f7b1428e 100644 --- a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc +++ b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc @@ -109,7 +109,7 @@ NOTE: For new deployments starting with ocis 5.0.0, these values are autogenerat WARNING: If no values are provided during an upgrade, ocis will not start and log a fatal error. -- -* We've changed the structure of the `theme.json` file. This was done for several reasons: +* We have changed the structure of the `theme.json` file. This was done for several reasons: ** To be able to support multiple client platforms, ** to be able to create a fallback chain of theming information and ** to reduce the amount of configuration needed for theming. @@ -121,7 +121,7 @@ If you have a custom `theme.json` file, you need to update it to the new structu * The old structure can be found here: https://doc.owncloud.com/ocis/4.0/deployment/webui/webui-theming.html#example-theme[Infinite Scale 4.0 Example Theme, window=_blank]. * The new structure can be found here: https://owncloud.dev/clients/web/theming/#example-theme[Infinite Scale 5.0 Example Theme, window=_blank]. -The most important adjustment is the fact, that the old structure only supported multiple themes on a single platform (web). The new structure defines a `common` section and a `clients` section on the root level of the file. +The most important adjustment is the fact, that the old structure only supported multiple themes on a single platform (web). The new structure defines a `common` and a `clients` section on the root level of the file. * The `common` section provides defaults for all client platforms. * The `clients` section provides platform specific general theming information and a list of themes. @@ -138,7 +138,7 @@ This can be done with copy & paste and only small adjustments, since the structu We deprecated some service registries. If your `MICRO_REGISTRY` config is set to one of these values `mdns, nats, kubernetes, etcd, consul` please use `nats-js-kv` in the future (`memory` is only intended for testing environments). * Micro caches and stores + -We deprecated some micro caches and stores. If one of your `*_CACHE_STORE` variables is using one of there values `redis-sentinel, redis, etcd, nats, ocmem` please use `nats-js-kv` in the future (`memory` is only intended for testing environments). +We deprecated some micro caches and stores. If one of your `*_CACHE_STORE` variables is using one of there values `redis-sentinel`, `redis`, `etcd`, `nats` or `ocmem`, use `nats-js-kv` in the future. Note that `memory` is only intended for testing environments. * Resharing + We have disabled the resharing feature by default. It will be removed from the product. Existing reshares will still be visible to the original resource owner. Creation of new reshares will not be possible. Make sure that `OCIS_ENABLE_RESHARING` is *not* set to `true` in your deployments. From bc84f20b834af4ff568d7a3856d817428fdd4df6 Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Tue, 5 Mar 2024 12:52:31 +0100 Subject: [PATCH 3/6] docs: add warning about failing logo upload --- modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc index f7b1428e..5d26ac0f 100644 --- a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc +++ b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc @@ -37,7 +37,9 @@ docker pull owncloud/ocis:5.0.0 * If you are using deprecated environment variables in your config. ** See the xref:deployment/services/env-var-changes.adoc[Added and Removed Environment Variables] documentation. * If you have changed the default configuration for the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY] environment variable. -* If you have used custom theming in your Infinite Scale instance by providing a custom theme.json file. +* If you have used custom theming in your Infinite Scale instance... +** by providing a custom theme.json file. +** by uploading a custom logo without additional changes to the theme. In all other cases, there is nothing that needs to be done as the new defaults for client pool selectors will be used automatically. @@ -130,6 +132,8 @@ Note that the "Desktop", "Android" and "iOS" platforms currently lack support fo The theming data from your old `theme.json` file needs to be moved to the "web" section of the new `theme.json` file. This can be done with copy & paste and only small adjustments, since the structure of a single, web-specific theme within the `theme.json` remains mostly unchanged. + +WARNING: If you have uploaded a custom logo without additional changes to the theme, oCIS internally created a custom theme.json anyway which now needs to be deleted. Otherwise any logo upload attempt will fail. -- === Deprecations From 727bfdd6c921516fff7597e0125a04a622098346 Mon Sep 17 00:00:00 2001 From: Martin Date: Tue, 5 Mar 2024 14:28:40 +0100 Subject: [PATCH 4/6] Update modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc Co-authored-by: Phil Davis --- modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc index 5d26ac0f..fd57028d 100644 --- a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc +++ b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc @@ -108,7 +108,7 @@ OCIS_SERVICE_ACCOUNT_SECRET= NOTE: For new deployments starting with ocis 5.0.0, these values are autogenerated by running `ocis init` -WARNING: If no values are provided during an upgrade, ocis will not start and log a fatal error. +WARNING: If no values are provided during an upgrade, ocis will not start and will log a fatal error. -- * We have changed the structure of the `theme.json` file. This was done for several reasons: From 2f9a0c868bb44eb158906921577ae92d2a79b7ca Mon Sep 17 00:00:00 2001 From: mmattel Date: Tue, 5 Mar 2024 14:53:31 +0100 Subject: [PATCH 5/6] just some small text fixes --- .../migration/upgrading_4.0.0_5.0.0.adoc | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc index fd57028d..b14bc70c 100644 --- a/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc +++ b/modules/ROOT/pages/migration/upgrading_4.0.0_5.0.0.adoc @@ -37,8 +37,8 @@ docker pull owncloud/ocis:5.0.0 * If you are using deprecated environment variables in your config. ** See the xref:deployment/services/env-var-changes.adoc[Added and Removed Environment Variables] documentation. * If you have changed the default configuration for the xref:deployment/services/env-vars-special-scope.adoc#extended-environment-variables[MICRO_REGISTRY] environment variable. -* If you have used custom theming in your Infinite Scale instance... -** by providing a custom theme.json file. +* If you have used custom theming in your Infinite Scale instance: +** by providing a custom `theme.json` file. ** by uploading a custom logo without additional changes to the theme. In all other cases, there is nothing that needs to be done as the new defaults for client pool selectors will be used automatically. @@ -96,22 +96,23 @@ services: ---- -- -* We introduced service accounts in the area of service-to-service communication. We need this change to properly authenticate backend calls which are not triggered by user interaction like search indexing, auto accepting of shares or timed trashbin cleanup jobs. Instances which are migrated from ocis 4.x need manual steps to avoid becoming non functional. +* We introduced service accounts in the area of service-to-service communication. This change was needed to properly authenticate backend calls which are not triggered by user interaction like search indexing, auto accepting of shares or timed trashbin cleanup jobs. Instances which are migrated from Infinite Scale 4.x need manual steps to avoid becoming non functional. + -- Two new global environment variables have been introduced to manually configure the instance: `OCIS_SERVICE_ACCOUNT_ID` and `OCIS_SERVICE_ACCOUNT_SECRET`. Please set the first one to a random uuid and create a strong secret value for the second one. -[source, sh] + +[source,plaintext] ---- OCIS_SERVICE_ACCOUNT_ID= OCIS_SERVICE_ACCOUNT_SECRET= ---- -NOTE: For new deployments starting with ocis 5.0.0, these values are autogenerated by running `ocis init` +NOTE: For new deployments starting with Infinite Scale 5.0.0, these values are autogenerated by running the `'ocis init'` command. -WARNING: If no values are provided during an upgrade, ocis will not start and will log a fatal error. +WARNING: If no values are provided during an upgrade, Infiinite Scale will not start and log a fatal error. -- -* We have changed the structure of the `theme.json` file. This was done for several reasons: +* We have changed the structure of the `theme.json` file which was done for several reasons: ** To be able to support multiple client platforms, ** to be able to create a fallback chain of theming information and ** to reduce the amount of configuration needed for theming. @@ -120,8 +121,8 @@ WARNING: If no values are provided during an upgrade, ocis will not start and wi -- If you have a custom `theme.json` file, you need to update it to the new structure. -* The old structure can be found here: https://doc.owncloud.com/ocis/4.0/deployment/webui/webui-theming.html#example-theme[Infinite Scale 4.0 Example Theme, window=_blank]. -* The new structure can be found here: https://owncloud.dev/clients/web/theming/#example-theme[Infinite Scale 5.0 Example Theme, window=_blank]. +* The old structure can be found at: https://doc.owncloud.com/ocis/4.0/deployment/webui/webui-theming.html#example-theme[Infinite Scale 4.0 Example Theme, window=_blank]. +* The new structure can be found at: https://owncloud.dev/clients/web/theming/#example-theme[Infinite Scale 5.0 Example Theme, window=_blank]. The most important adjustment is the fact, that the old structure only supported multiple themes on a single platform (web). The new structure defines a `common` and a `clients` section on the root level of the file. @@ -130,10 +131,10 @@ The most important adjustment is the fact, that the old structure only supported Note that the "Desktop", "Android" and "iOS" platforms currently lack support for the themes provided by Infinite Scale. -The theming data from your old `theme.json` file needs to be moved to the "web" section of the new `theme.json` file. +The theming data from your old `theme.json` file needs to be moved to the `web` section of the new `theme.json` file. This can be done with copy & paste and only small adjustments, since the structure of a single, web-specific theme within the `theme.json` remains mostly unchanged. -WARNING: If you have uploaded a custom logo without additional changes to the theme, oCIS internally created a custom theme.json anyway which now needs to be deleted. Otherwise any logo upload attempt will fail. +WARNING: If you have uploaded a custom logo without additional changes to the theme, Infinite Scale internally created a custom 'theme.json' anyway which now needs to be deleted. Otherwise any logo upload attempt will fail. -- === Deprecations From d4103300dec411fa2a197a7ba1320a112c3f4a73 Mon Sep 17 00:00:00 2001 From: mmattel Date: Wed, 6 Mar 2024 14:57:00 +0100 Subject: [PATCH 6/6] adding a notable change --- modules/ROOT/pages/migration/upgrading-ocis.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/migration/upgrading-ocis.adoc b/modules/ROOT/pages/migration/upgrading-ocis.adoc index 2adf607c..a1b42fd6 100644 --- a/modules/ROOT/pages/migration/upgrading-ocis.adoc +++ b/modules/ROOT/pages/migration/upgrading-ocis.adoc @@ -20,6 +20,7 @@ IMPORTANT: When upgrading from an older release to the desired one, *ALL* upgrad === Notable Changes Requiring Manual Intervention * The xref:deployment/container/orchestration/orchestration.adoc#using-our-helm-charts-with-infinite-scale[Helm Chart] has been upgraded. +* The maintenance command `ocis storage-users uploads list` has been deprecated and will be removed in a later release. A successor with more capabilities has been implemented, see the xref:deployment/services/s-list/storage-users.adoc#manage-unfinished-uploads[Manage Unfinished Uploads] documentation for more details. === Breaking Changes Requiring Manual Intervention