Merge pull request #4058 from stonezdj/migrate_ova_guide

OVA migration guide

docs/expand_hard_disk.md

@@ -0,0 +1,104 @@
+# Expand the Hard Disk of Virtual Appliance
+
+If you install Harbor with OVA, the persistent data(such as images and database) is stored in a hard disk which is mounted on directory "/data", and the default size is 60GB. As more and more images are pushed into it, the capacity may not meet your requirements.  
+
+You can check the space on Harbor web UI by clicking on **Projects**:
+
+
+
+![lvm](img/lvm/check_on_ui_01.png)
+
+If your free space is running out, you can expand the size of the hard disk by the following steps:  
+
+1. Add New Hard Disk to VM  
+
+    (1) Log in vSphere web client. Power off Harbor's virtual appliance.  
+    (2) Right click on the VM and select "Edit Settings".  
+    (3) Select "New Hard Disk", and click "OK".  
+	
+    ![lvm](img/lvm/add_new_hard_disk.png)
+		
+    We add a 10GB new hard disk to show the operations.  
+	
+    (4) Power on the VM.  
+
+2. Expand Hard Disk using LVM  
+
+	Login from the console of the virtual appliance and run the following commands:  
+
+	(1) Check the current size of "/data":  
+	```sh
+	df -h /data
+	```
+	
+	![lvm](img/lvm/size_of_data_01.png)
+	
+	(2) Find the new hard disk, e.g. "/dev/sdc". Replace all "/dev/sdc" with your disk in the following commands.  
+	```sh
+	fdisk -l
+	```
+	
+	![lvm](img/lvm/find_the_new_harddisk.png)
+	
+	(3) Create new physical volume:  
+	```sh
+	pvcreate /dev/sdc
+	```
+	
+	(4) Check the volume group:  
+	```sh
+	vgdisplay
+	```
+	
+	![lvm](img/lvm/vg_01.png)
+	
+	(5) Expand the volume group:
+	```sh
+	vgextend data1_vg /dev/sdc
+	```
+	
+	(6) Check the volume group again:  
+	```sh
+	vgdisplay
+	```
+	
+	![lvm](img/lvm/vg_02.png)
+	
+	(7) Check the logical volume:
+	```sh
+	lvdisplay
+	```
+	
+	![lvm](img/lvm/lv_01.png)
+	
+	(8) Resize the logical volume:  
+	```sh
+	lvresize -l +100%FREE /dev/data1_vg/data
+	```
+	
+	![lvm](img/lvm/resize_lv.png)
+	
+	(9) Check the logical volume again, note the change of "LV Size":
+	```sh
+	lvdisplay
+	```
+	
+	![lvm](img/lvm/lv_02.png)
+	
+	(10) Resize the file system:
+	```sh
+	resize2fs /dev/data1_vg/data
+	```
+	
+	(11) Check the size "/data" again:
+	```sh
+	df -h /data
+	```
+	
+	![lvm](img/lvm/size_of_data_02.png)
+	
+	You can also check the size on Harbor web UI:
+	
+	![lvm](img/lvm/check_on_ui.png)
+
+After that, your disk should be expanded successfully. If you want to add more hard disks, do the steps again.

docs/install_guide_ova.md

@@ -110,4 +110,8 @@
 
     ![Screenshot of after login](img/ovainstall/afterlogin.png)
 
-Please run "tdnf distro-sync" command from time to time to keep the OS up to date.
+    To migrate Harbor OVA, please refer [migrate OVA guide](migrate_ova_guide.md)
+  
+    To extend the data disk in Harbor OVA, please refer [Expand the Hard Disk of Virtual Appliance](expand_hard_disk.md)
+
+    Please run "tdnf distro-sync" command from time to time to keep the OS up to date.

docs/migrate_ova_guide.md

@@ -0,0 +1,41 @@
+# Harbor OVA upgrade and database migration guide
+
+This guide is limited to migrate a Harbor OVA instance to a next release. All Harbor data storeage settings is not manually changed after the existing Harbor OVA deployed.
+
+**Steps to migrate Harbor OVA instances:**
+
+1. Before migration, you need to note down these following items:
+   - Note down the value of db_password in /data/harbor.cfg.
+   - **"Networking properties"** if need to keep these settings. you can find them in **"Edit Settings"** -> **"vApp Options"**  
+   ![Screenshot of vApp Options](img/ovainstall/vappoptions.png)
+
+2. In the vSphere Web Client, Select **"Shut Down Guest OS"** on the existing OVA instances, then select **"Edit Settings"**, remove the **"Hard disk 2"**, uncheck **"Delete files from datastore"**. All disks in the logical volume "data1_vg" should be removed if the original logic volume have been extended. Use pvscan command to check disks in logical volume "data1_vg".
+   
+   ![Screenshot of pvscan](img/ovainstall/pvscan.png)
+   
+    Usually, the sda is the Hard Disk1 in the **"Edit Settings"** pannel, and the sdb is Hard Disk2 and so on. Note down all location of disk files in logical volume "data1_vg".
+   
+   ![Screenshot of Remove Disk](img/ovainstall/removedisk.png)
+
+3. Deploy a new Harbor OVA instances. You may use different settings or keep same settings.
+
+    |  Configuration Section Name |Use Different Settings | Keep Same Settings | 
+    |-------------------------------- | ------------------|---------------------------------------------  |   
+    | Certificates                    | Leave blank to use auto-generated certificates or paste in new certificates  |Replace files in /data/ca_download and /data/cert with backup files in the same path of prevous Harbor instance and restart Harbor OVA after migration | 
+    | Harbor Configuration            | N/A |Input a random administrator password to bypass the data validation, it uses previous settings after migration |   
+    | LDAP Configuration              | N/A |Leave blank, it uses previous settings after migration                 | 
+    | Networking Properties           | Input new settings | Input previous settings                                | 
+    | System                          | Input new settings | Input previous settings                                |
+    
+4. Copy all disk files of logic volume "data1_vg" in Step 2 to the new Harbor OVA's folder in vSphere's datastore.
+5. Before powering on the new Harbor OVA instances, select **"Edit Settings"**, after remove the "Hard disk 2", then click **" Existing Hard Disk"** in **"New Device"**, let it point to the disk file copied in Step 4. Please add all disk files in the same order with previous OVA instance.
+6. Power on the new OVA instance, login to the console and run following commands:
+   ```
+   chmod 700 /migrate_OVA.sh
+   /migrate_OVA.sh 
+   ```
+   When prompt, input the value of db_password that note down in Step 1.
+7. After the script is complete, visit URL: https://*<DNS Name>* to verify the new Harbor OVA instance. the administrator's password is the same password of previous Harbor instance.
+
+
+

docs/migration_guide.md

@@ -9,6 +9,8 @@ When upgrading your existing Habor instance to a newer version, you may need to
 
 - You must back up your data before any data migration.
 
+- To migrate harbor OVA, please refer [migrate OVA guide](migrate_ova_guide.md)
+
 ### 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: