Merge pull request #8694 from romayalon/romy-online-upgrade-documentation

romayalon · web-flow · commit e24c62765857 · 2025-01-16T18:45:47.000+02:00
NC | Online Upgrade | Documentation
diff --git a/docs/NooBaaNonContainerized/NooBaaCLI.md b/docs/NooBaaNonContainerized/NooBaaCLI.md
@@ -21,8 +21,12 @@
     1. [Health](#health)
     2. [Metrics](#metrics)
     3. [Gather Logs](#gather-logs)
-9. [Global Options](#global-options)
-10. [Examples](#examples)
+9. [Upgrade](#upgrade)
+    1. [Upgrade Start](#upgrade-start)
+    2. [Upgrade Status](#upgrade-status)
+    3. [Upgrade History](#upgrade-history)
+10. [Global Options](#global-options)
+11. [Examples](#examples)
     1. [Bucket Commands Examples](#bucket-commands-examples)
     2. [Account Commands Examples](#account-commands-examples)
     3. [White List Server IP Command Example](#white-list-server-ip-command-example)
@@ -458,8 +462,70 @@ noobaa-cli diagnose metrics
 The `gather-logs` command is used for extract NooBaa non containerized logs.
 Not implemented yet, running this command will fail with not implemented error.
 
+## Upgrade
 
-## Global Flags
+The `upgrade` command is being used for running config directory upgrade operations.
+- **[Start](#upgrade-start)**: Initiate config directory upgrade.
+- **[Status](#upgrade-status)**: Retrieve the in progress config directory upgrade status.
+- **[History](#upgrade-history)**: Retrieve the history information of past config directory upgrades.
+
+For more information about the config directory upgrade, See - [Upgrade](./Upgrade.md#online-upgrade-version--5180)
+
+### Upgrade Start
+
+The `upgrade start` command is used to start a config directory upgrade run.
+
+#### Usage
+```sh
+noobaa-cli upgrade start --expected_version <expected-version> --expected_hosts <expected-hosts> [--skip-verification] [--custom_upgrade_scripts_dir]
+```
+
+#### Flags -
+- `expected_version` (Required)
+    - Type: String
+    - Description: Specifies the upgrade's expected target version.
+    - Example - `--expected_version 5.18.0`
+
+- `expected_hosts` (Required)
+    - Type: String
+    - Description: Specifies the upgrade's expected hosts. String of hostnames separated by comma (,). 
+    - Example - `--expected_hosts hostname1,hostname2,hostname3`
+
+- `skip_verification`
+    - Type: Boolean
+    - Description: Specifies if NooBaa should skip upgrade verification. </br>
+      The upgrade verification process contains the following checks - </br>
+        * The expected_hosts appear in system.json.
+        * The expected_version is the version that runs in the host that is running the upgrade.
+        * The source code (RPM) in all the expected_hosts is upgraded to the expected_version.
+    - **WARNING:** Can cause corrupted config directory files created by hosts running old code. This should generally not be used and is intended exclusively for NooBaa team support. 
+
+- `custom_upgrade_scripts_dir`
+    - Type: String
+    - Description: Specifies a custom upgrade scripts directory. Used for running custom config directory upgrade scripts.
+    - **WARNING:** Can cause corrupted config directory, specifying a custom upgrade scripts directory will initiate a non NooBaa official config directory upgrade. This should generally not be used and is intended exclusively for NooBaa team support. Requires a special code fix provided by NooBaa dev team and stored in the custom_upgrade_scripts_dir.
+
+### Upgrade Status
+
+The `upgrade status` command is used for displaying the status of an ongoing upgrade run. </br>
+The available status information is upgrade start timestamp, from_version, to_version, config_dir_from_version, config_dir_to_version, running_host etc.
+
+#### Usage
+```sh
+noobaa-cli upgrade status
+```
+
+### Upgrade History
+
+The `upgrade history` command is used for displaying the history information of past config directory upgrades. </br> 
+The available history information is an array of upgrade information - upgrade start timestamp, from_version, to_version, config_dir_from_version,config_dir_to_version, running_host etc.
+
+#### Usage
+```sh
+noobaa-cli upgrade history
+```
+
+## Global Options
 
 Global options used by the CLI to define the config directory settings. 
 
diff --git a/docs/NooBaaNonContainerized/Upgrade.md b/docs/NooBaaNonContainerized/Upgrade.md
@@ -6,7 +6,11 @@
 4. [Offline Upgrade (Version < 5.18.0)](#offline-upgrade-version--5180)
     1. [Offline Upgrade steps](#offline-upgrade-steps)
 5. [Online Upgrade (Version >= 5.18.0)](#online-upgrade-version--5180)
-
+    1. [Online Upgrade Goals](#online-upgrade-goals)
+    2. [Online Upgrade Algorithm](#online-upgrade-algorithm)
+    3. [Additional Upgrade Properties of `system.json`](#additional-upgrade-properties-of-systemjson)
+    4. [Upgrade Helpers](#upgrade-helpers)
+    5. [Config Directory Upgrade - 5.18.0](#config-directory-upgrade---5180)
 
 ## Introduction
 This document provides step-by-step instructions to help you successfully upgrade your current Upstream NooBaa RPM version to a newer version.
@@ -101,7 +105,7 @@ Online Upgrade Algorithm commands examples -
 4. Restart NooBaa service - `systemctl restart noobaa`
 5. `noobaa-cli upgrade start --expected_version=5.18.0 --expected_hosts=hostname1,hostname2,hostname3` 
 
-### Additional Upgrade Properties of `system.json`-
+### Additional Upgrade Properties of `system.json`
 
 1. New per host property -   
     - config_dir_version
@@ -229,3 +233,34 @@ Online Upgrade Algorithm commands examples -
 1. NooBaa Health CLI - will report on the config directory status, upgrade failures and hosts that are blocked for config directory updates.
 2. NooBaa CLI upgrade status - will print the upgrade status per the information written in system.json.
 
+## Config Directory Upgrade - 5.18.0
+During the upgrade to NooBaa NC 5.18.0, NooBaa will execute an upgrade script that will convert NooBaa's config directory structure to have identities directory for storing accounts config files. The motivation for this change is to transition from an account name-based structure to an ID-based structure, which allows for greater scalability and the inclusion of additional identity types in the future. </br>
+For more details about the new config directory structure and components, See - 
+1. [Config Directory Structure](./Configuration.md#configuration-directory-structure).
+2. [Config Directory Components](./Configuration.md#configuration-directory-components).
+
+### Config Directory Upgrade Steps
+**1. Creation of `identities/` Directory - </br>**
+The identities/ directory will serve as the primary storage location for account configuration files. Each account will have a dedicated subdirectory named after its unique identifier and identity.json file that will contain the account's configuration content.
+
+**2. Creation of `accounts_by_name/` directory - </br>**
+On some S3/CLI flows, NooBaa will search for an account by name, therefore, the accounts_by_name/ directory will be created. It will contain symbolic links that map each account name to the corresponding identity.json file under the ID-based subdirectory within identities/.
+
+**3. Upgrade configuration files of all the existing accounts - </br>**
+Each account config file in the old `accounts/` directory will be migrated to the new structure:
+
+- **Identity creation - </br>**
+An ID-based subdirectory will be created under `identities/`, and an `identity.json` file will contain the original account config file content. The ID is the original account's id taken from the account's config file. </br>
+Example of identity path - `/etc/noobaa.conf.d/identities/123456789/identity.json`
+
+- **Account name symlink creation - </br>**
+A symbolic link will be created in the `accounts_by_name/` directory, mapping the account name to the newly created `identity.json` file under the ID-based subdirectory. </br>
+Example of the new account name symlink path - `/etc/noobaa.conf.d/accounts_by_name/alice.symlink -> ../../identities/123456789/identity.json`
+
+- **Account access Key symlink update - </br>**
+Any symbolic links related to access keys will be updated to point to the new ID-based `identity.json` file. </br>
+Example of old (NooBaa 5.17.z or lower) access_key symlink path - `/etc/noobaa.conf.d/access_keys/AKIAIOSFODNN7EXAMPLE.symlink -> ../accounts/alice.json`. </br>
+Example of new (NooBaa 5.18 and higher) access_key symlink path - `/etc/noobaa.conf.d/access_keys/AKIAIOSFODNN7EXAMPLE.symlink -> ../../identities/123456789/identity.json`.
+
+**4. Backup and deletion of `accounts/` directory - </br>**
+Once all account configurations have been migrated and verified, the `accounts/` directory will be backed-up and removed to finalize the upgrade process. A backup of the old account config files can be found under `.backup_accounts_dir_${from_version}/` while from_version is the version upgraded from.
diff --git a/src/manage_nsfs/manage_nsfs_help_utils.js b/src/manage_nsfs/manage_nsfs_help_utils.js
@@ -417,19 +417,25 @@ Usage:
 
 Flags:
 
-    --expected_version                             <string>                             The expected target version of the upgrade
-    --expected_hosts                               <string>                             The expected hosts running NooBaa NC, a string of hosts separated by ,
-    --skip_verification                            <boolean>        (optional)          skip verification of the hosts package version
-                                                                                        WARNING: can cause corrupted config dir files created by hosts running old code
-    --custom_upgrade_scripts_dir                   <string>         (optional)          custom upgrade scripts dir, use for running custom config dir upgrade scripts
+    --expected_version              <string>                            The expected target version of the upgrade
+    --expected_hosts                <string>                            The expected hosts running NooBaa NC, a string of hosts separated by ,
+    --skip_verification             <boolean>        (optional)         skip upgrade verification
+                                                                        WARNING: can cause corrupted config dir files created by hosts running old code.
+                                                                        this should generally not be used and is intended exclusively for NooBaa team support. 
+    --custom_upgrade_scripts_dir    <string>         (optional)         a custom upgrade scripts dir, use for running custom config dir upgrade scripts.
+                                                                        WARNING: can cause corrupted config directory. specifying a custom upgrade scripts directory
+                                                                        will initiate a non NooBaa official config directory upgrade.
+                                                                        this should generally not be used and is intended exclusively for NooBaa team support.
+                                                                        requires a special code fix provided by NooBaa dev team and stored in the
+                                                                        custom_upgrade_scripts_dir directory.
 
 `;
 
 const UPGRADE_STATUS_OPTIONS = `
 Help:
 
     'upgrade status' is a noobaa-cli command that will return the status of an ongoing upgrade run,
-    the available status information is upgrade start timestmp, from_version, to_version, config_dir_from_version,
+    the available status information is upgrade start timestamp, from_version, to_version, config_dir_from_version,
     config_dir_to_version, running_host etc.
 
 Usage:
@@ -442,7 +448,7 @@ const UPGRADE_HISTORY_OPTIONS = `
 Help:
 
     'upgrade history' is a noobaa-cli command that will return the history of past upgrades,
-    the available history information is an array of upgrade information - upgrade start timestmp, from_version, to_version, config_dir_from_version,
+    the available history information is an array of upgrade information - upgrade start timestamp, from_version, to_version, config_dir_from_version,
     config_dir_to_version, running_host etc.
 
 Usage:
diff --git a/src/upgrade/nc_upgrade_manager.js b/src/upgrade/nc_upgrade_manager.js
@@ -148,12 +148,12 @@ class NCUpgradeManager {
 
     /**
      * _verify_config_dir_upgrade verifies that - 
-     * 1. All hosts appearing in system.json were RPM upgraded to the same version the host running the upgrade
+     * 1. All hosts appearing in expected_hosts were RPM upgraded to the same version the host running the upgrade
      * 2. The user's expected_version is the host's package version - 
      *    expected_version is the expected source code version that the user asks to upgrade to, it's an optional verification, 
      *    if expected_version was not provided we assume that the source code on this host is 
      * 3. The user's expected_hosts exist in system.json
-     * 4. If there are hosts in system.json that ere not provided in the expected_hosts we will print a warning but won't fail
+     * 4. If there are hosts in system.json thatwere not provided in the expected_hosts we will print a warning but won't fail
      * we do that because of hostname can be renamed, hosts that are on maintainance and we don't want to block the upgrade becuase it might take a lot of time,
      * or because of hosts that used to be a part of the cluster and they were removed from the cluster, we don't get the updated info of the hosts on system.json 
      * therefore we can not treat the system.json as the source of truth of the hosts information
diff --git a/src/upgrade/nc_upgrade_scripts/1.0.0/config_dir_restructure.js b/src/upgrade/nc_upgrade_scripts/1.0.0/config_dir_restructure.js
@@ -51,7 +51,7 @@ async function run({ dbg, from_version }) {
 
 /**
  * upgrade_accounts_config_files list all old accounts and upgrade their config files by doing the following - 
- * 1. Iterate all accounts under accounts/ (old dire
+ * 1. Iterate all accounts under accounts/ (old directory)
  * 2. upgrade account config file with 3 retries
  * @param {import('../../../sdk/config_fs').ConfigFS} config_fs 
  * @param {String[]} old_account_names 
@@ -96,7 +96,6 @@ async function upgrade_accounts_config_files(config_fs, old_account_names, from_
  * 1.1. identity creation
  * 1.2. account name symlink creation
  * 1.3. account access key symlink update
- * 1.4. delete account old path
  * @param {import('../../../sdk/config_fs').ConfigFS} config_fs 
  * @param {String} account_name 
  * @param {String} backup_access_keys_path
