Merge pull request #9045 from stuclem/upgrade

Updated upgrade and migration guide for 1.9

docs/migration_guide.md

@@ -1,28 +1,20 @@
-# Harbor upgrade and migration guide
+# Harbor Upgrade and Migration Guide
 
-This guide only covers upgrade and migration to version >= v1.8.0
+This guide covers upgrade and migration to version 1.9.0. This guide only covers migration from v1.7.x and later to the current version. If you are upgrading from an earlier version, refer to the migration guide in the `release-1.7.0` branch to upgrade to v1.7.x first, then follow this guide to perform the migration to this version. 
 
-When upgrading your existing Harbor instance to a newer version, you may need to migrate the data in your database and the settings in `harbor.cfg`. 
-Since the migration may alter the database schema and the settings of `harbor.cfg`, you should **always** back up your data before any migration.
+When upgrading an existing Harbor 1.7.x instance to a newer version, you might need to migrate the data in your database and the settings in `harbor.cfg`. 
+Since the migration might alter the database schema and the settings of `harbor.cfg`, you should **always** back up your data before any migration.
 
-**NOTE:**
+**NOTES:**
 
 - Again, you must back up your data before any data migration.
+- Since v1.8.0, the configuration of Harbor has changed to a `.yml` file. If you are upgrading from 1.7.x, the migrator will transform the configuration file from `harbor.cfg` to `harbor.yml`. The command will be a little different to perform this migration, so make sure you follow the steps below.
+- In version 1.9.0, some containers are started by `non-root`. This does not pose problems if you are upgrading an officially released version of Harbor, but if you have deployed a customized instance of Harbor, you might encounter permission issues.
+- In previous releases, user roles took precedence over group roles in a project. In this version, user roles and group roles are combined so that the user has whichever set of permissions is highest. This might cause the roles of certain users to change during upgrade.
+- With the introduction of storage and artifact quotas in version 1.9.0, migration from 1.7.x and 1.8.x might take a few minutes. This is because the `core` walks through all blobs in the registry and populates the database with information about the layers and artifacts in projects.
+- With the introduction of storage and artifact quotas in version 1.9.0, replication between version 1.9.0 and a previous version of Harbor does not work. You must upgrade all Harbor nodes to 1.9.0 if you have configured replication between them.
 
-- This guide only covers the migration from v1.6.0 to current version, if you are upgrading from earlier versions please 
-refer to the migration guide in release branch to upgrade to v1.6.0 and follow this guide to do the migration to later version. 
-
-- From v1.6.0 on, Harbor will automatically try to do the migrate the DB schema when it starts, so if you are upgrading from v1.6.0 
-or above it's not necessary to call the migrator tool to migrate the schema.
-
-- For the change in Database schema please refer to [change log](../tools/migration/db/changelog.md).
-
-- Since v1.8.0, the configuration of Harbor has changed to `.yml` file, the migrator will transform the configuration 
-file from `harbor.cfg` to `harbor.yml`.  The command will be a little different to perform this migration, please make sure
-you follow the steps below.
-
-
-### Upgrading Harbor and migrating data
+## Upgrading Harbor and Migrating Data
 
 1. Log in to the host that Harbor runs on, stop and remove existing Harbor instance if it is still running:
     ```
@@ -30,7 +22,7 @@ you follow the steps below.
     docker-compose down
     ```
 
-2.  Back up Harbor's current files so that you can roll back to the current version when it is necessary.
+2.  Back up Harbor's current files so that you can roll back to the current version if necessary.
     ```
     mv harbor /my_backup_dir/harbor
     ```
@@ -42,28 +34,25 @@ you follow the steps below.
 3. Get the latest Harbor release package from Github:
    https://github.com/goharbor/harbor/releases
 
-4. Before upgrading Harbor, perform migration first.  The migration tool is delivered as a docker image, so you should pull the image from docker hub. Replace [tag] with the release version of Harbor (e.g. v1.5.0) in the below command:
+4. Before upgrading Harbor, perform a migration first. The migration tool is delivered as a docker image, so you should pull the image from docker hub. Replace [tag] with the release version of Harbor (for example, v1.9.0) in the command below:
     ```
     docker pull goharbor/harbor-migrator:[tag]
     ```
 
-5. Upgrade from `harbor.cfg` to `harbor.yml`
+5. If you are upgrading from v1.7.x, migrate from `harbor.cfg` to `harbor.yml`.
     **NOTE:** You can find the ${harbor_yml} in the extracted installer you got in step `3`, after the migration the file `harbor.yml` 
     in that path will be updated with the values from ${harbor_cfg}
     
     ```
     docker run -it --rm -v ${harbor_cfg}:/harbor-migration/harbor-cfg/harbor.yml -v ${harbor_yml}:/harbor-migration/harbor-cfg-out/harbor.yml goharbor/harbor-migrator:[tag] --cfg up
     ```
-    **NOTE:** The schema upgrade and data migration of Database is performed by core when Harbor starts, if the migration fails,
-    please check the log of core to debug.
+    **NOTE:** The schema upgrade and data migration of the database is performed by core when Harbor starts, if the migration fails, please check the log of core to debug.
 
-6. Under the directory `./harbor`, run the `./install.sh` script to install the new Harbor instance. If you choose to install Harbor with components like Notary, Clair, and chartmuseum, refer to [Installation & Configuration Guide](../docs/installation_guide.md) for more information.
+6. Under the directory `./harbor`, run the `./install.sh` script to install the new Harbor instance. If you choose to install Harbor with components such as Notary, Clair, and chartmuseum, refer to [Installation & Configuration Guide](../docs/installation_guide.md) for more information.
 
 
-### Roll back from an upgrade
-For any reason, if you want to roll back to the previous version of Harbor, follow the below steps:
-
-**NOTE:** Roll back doesn't support upgrade across v1.5.0, like from v1.2.0 to v1.7.0. This is because Harbor changes DB to PostgreSQL from v1.7.0, the migrator cannot roll back data to MariaDB.    
+## Roll Back from an Upgrade
+If, for any reason, you want to roll back to the previous version of Harbor, perform the following steps: 
 
 1. Stop and remove the current Harbor service if it is still running.
     ```
@@ -89,3 +78,4 @@ For any reason, if you want to roll back to the previous version of Harbor, foll
     cd harbor
     ./install.sh
     ```
+**NOTE**: While you can roll back an upgrade to the state before you started the upgrade, Harbor does not support downgrades.