I lately decided to upgrade my local Docker registry installation. I use VMware Harbor as a Docker registry – In my opinion, it is much better and easier than official registry software. Recently I upgraded it from version 1.5.1 to 1.6.2.

VMware Harbor runs in containers which simplifies managing the software, but the upgrade is not straightforward as you may think. Most significant change is database consolidation. Instead of separate databases for Harbor, Clair and Notary version 1.6.0 introduces a single database engine for all components – the PostgreSQL. The 1.5.0 Harbor uses the MySQL, while Clair already uses the PostgreSQL. The developers prepared a dedicated container with migration engine that performs all the work. However, I found upgrade documentation missing the crucial explanation of steps and commands which may lead to loss of your data. I will try to cover my findings in this post.

Make your own backups

The first problem I found is that documentation does not clearly explain if you should refer to configuration file from the old or new version. It does not even explain that in some aspects upgrade scripts update the configuration file. So before you start doing step described in the documentation, do the following:

You are now safe having own manual backup in case you run migration tool with wrong parameters.

Database backup

The migration process should be simple because developers created a container with dedicated software and scripts performing all operations for us. It is available on Docker Hub at goharbor/harbor–migrator. You need to download containers using the proper tag, but the documentation is not clear which one. You can choose between the v1.5.0 and v1.6.0 tags. Use the tag matching the final version of your upgrade! If you select the container with the tag matching your current VMware Harbor version the scripts will not work and error messages will not be clear on that.

Then the documentation asks you to backup the database/harbor.cfg file to some backup location. If you have no such file just ignore this step. I could not find the configuration file in other locations than root project folder.

Now you need to run the harbor-migrator container to make a database backup. It mounts three volumes defined in docker run command but again the documentation is not clear on exact directories you should refer to. Instead, you find some system variables you probably never defined on your host. Replace the variables or define them using following values:

1. ${harbor_db_path}:/var/lib/mysql – directory of current version of database, by defailt it is /data/database
2. ${harbor_cfg}:/harbor-migration/harbor-cfg/harbor.cfg – location of the configuration file from the old Harbor version
3. ${backup_path}:/harbor-migration/backup – anywhere on host disk where you want to save the backup files generated by the script in container. It will make copy of the harbor.cfg files and dump the MySQL database into registry.sql file

Database migration

In the next step, you will perform the actual migration of the database using the same harbor-migrator software in a container. The command requires the volumes defined in points 1 and 2 in the previous paragraph as its parameters. It will overwrite the content of the /data/database folder on the host with a new database. If you by mistake run the harbor-migrator container using the tag that matches your current VMWare Harbor version the conversion will not work and you may lose all files in /data/database directory. Usually, the script will end with the message that no migration was performed for Harbor version defined in the harbor.cfg file.

If the database migration completes successfully your configuration file will be updated with a new _version variable definition. Remember, it changed the file in the folder of your old Harbor version, not the one you unpacked few minutes ago.

If you use the Clair or Notary modules you must migrate their databases separately using again the harbor-migrator software. You will find the commands to execute in the documentation. Again you need to mount the volumes with an old and new database but surprisingly this time documentation refers to explicit paths instead of some variables.

The last task you will use the harbor-migrator is moving the updated configuration file to the directory with new Harbor version files. However, instead of running the script in the container again you can just copy the harbor.cfg file manually. If you followed steps I described earlier copy harbor.cfg from folder harbor-1.5.1 to folder harbor.  

Recreate the configuration files

In the last step described in the upgrade manual, you use the install.sh script to generate required configuration files. If you want to use Clair, Notary or Chartmuseum you need to run the script with additional parameters as described here. It will create the new configuration files in common/config subfolder. 

If you use a modified version of the docker-compose configuration files you must update the default ones found in the harbor archive you downloaded previously. I have changed mine by upgrading them to version 3. Also to connect Harbor with Jenkins containers I run on the same host I defined a dedicated subnet which I had to include in my configuration.

If installation script runs with no problems it will pull containers of all VMware Harbor components from the Docker Hub repository (or local archive if you decided to perform the offline installation) and run containers. 

Summary

Upgrading the VMware Harbor is not a hard task. Everything, even the migration scripts, runs in containers – you just download new images and recreate the containers after all. Database migration might be tricky because the documentation lacks some details in my opinion. In most production or test containers setups you do not refer to system variables in docker-compose configuration files. For security reasons, everything except the credentials should be hardcoded.