doc(tutorial): draft tutorial doc (#580)

- complete tutorial - complete cluster deletion - add doc placeholders for backup data - add doc placeholder for upgrade cluster - add doc placeholder for monitor logs - add one more sample manifest for deploying full harbor with all external services Signed-off-by: Steven Zou <szou@vmware.com>
goharbor · Apr 21, 2021 · 157bf76 · 157bf76
1 parent ffc42e9
commit 157bf76
Show file tree

Hide file tree

Showing 15 changed files with 742 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -70,17 +70,17 @@ NOTES:
 
 Harbor operator supports two extra Kubernetes versions besides the current latest version (`n-2` pattern):
 
-|    Versions   |         1.18       |        1.19        |        1.20        |
-|---------------|--------------------|--------------------|--------------------|
-| Compatibility | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+|    Versions   |         1.18       |        1.19        |        1.20        | 1.21 |
+|---------------|--------------------|--------------------|--------------------|------|
+| Compatibility | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |  :o: |
 
 ### Cert manager versions
 
 Harbor operator relies on cert manager to manage kinds of certificates used by Harbor cluster components. Table shown below lists the compatibilities of cert manager versions:
 
-|    Versions   |           <0.16          |       1.0.4        |       1.2.0        |
-|---------------|--------------------------|--------------------|--------------------|
-| Compatibility | :heavy_multiplication_x: | :heavy_check_mark: | :heavy_check_mark: |
+|    Versions   |           <0.16          |       1.0.4        |       1.2.0        | 1.3.0 |
+|---------------|--------------------------|--------------------|--------------------|-------|
+| Compatibility | :heavy_multiplication_x: | :heavy_check_mark: | :heavy_check_mark: |  :o:  |
 
 ### Ingress controller types
 
@@ -95,7 +95,7 @@ NOTES:
 
   :heavy_check_mark: : support
   :heavy_multiplication_x: : not support
-  :white_circle: : support with known issues
+  :o: : not verified (probably support)
 
 ## Documentation
 
@@ -105,11 +105,13 @@ NOTES:
 * [Manifests references](./docs/manifests-reference.md)
 * [Customize images](./docs/customize-images.md)
 * [Day2 configurations](./docs/configurations/day2-config.md)
+* [Upgrade Harbor cluster](./docs/LCM/upgrade-cluster.md)
 * [Delete Harbor cluster](./docs/LCM/cluster-deletion.md)
 * [Backup data](./docs/LCM/backup-data.md)
 * [Useful Makefile Targets](./docs/makefile.md)
 * [Resource configurations](./docs/configurations/resource-configurations.md)
 * [Performance comparison between fs & MinIO](./docs/perf/simple-perf-comprasion.md)
+* [Monitor logs with grafana](./docs/LCM/monitor-logs-with-grafana.md)
 
 ## Contributions
 

diff --git a/docs/LCM/backup-data.md b/docs/LCM/backup-data.md
@@ -0,0 +1,17 @@
+# Backup data
+
+The documentations shown here talk about how to backup the related data created and used by the corresponding in-cluster services such as `PostgreSQL`, `Redis` and `Minio`. For the case of using existing external dependent services, it is not covered by this document.
+
+You can follow the guides to backup your data regularly for data protection or only backup data before upgrading or deleting your Harbor cluster.
+
+## Backup data of in-cluster PostgrSQL
+
+You can check the data backup guideline for [PostgreSQL](./backup-psql-data.md).
+
+## Backup data of in-cluster Redis
+
+You can check the data backup guideline for [Redis](./backup-redis-data.md).
+
+## Backup data of in-cluster Minio
+
+You can check the data backup guideline for [Minio](./backup-minio-data.md).
diff --git a/docs/LCM/backup-minio-data.md b/docs/LCM/backup-minio-data.md
@@ -0,0 +1,5 @@
+# Backup Minio data
+
+Documentation shown here guides you how to backup the Minio data.
+
+TBD
diff --git a/docs/LCM/backup-psql-data.md b/docs/LCM/backup-psql-data.md
@@ -0,0 +1,5 @@
+# Backup Postgresql data
+
+Documentation shown here guides you how to backup the psql database data.
+
+TBD
diff --git a/docs/LCM/backup-redis-data.md b/docs/LCM/backup-redis-data.md
@@ -0,0 +1,5 @@
+# Backup Redis data
+
+Documentation shown here guides you how to backup the Redis data.
+
+TBD
diff --git a/docs/LCM/cluster-controller.md b/docs/LCM/cluster-controller.md
@@ -0,0 +1,104 @@
+# Harbor cluster controller
+
+Cluster operator is responsible for controlling the reconciling process of CR `HarborCluster` that is a top level resource owning the `Harbor` CR and the CRs of Harbor's dependent services. Its primary flow is apply the `Harbor` CR and start `Harbor` CR's reconciling process when the related dependent services CR required in the spec are ready. The apply processes of the related dependent services CR are handled in a concurrent way.
+
+## Resource status
+
+Combination of the conditions that indicates the status of `Harbor` as well as status of its dependent service CRs such as `postgresql`, `redisfailover` and minio `tenant` leads to the current state of the `HarborCluster` resource.
+
+### Conditions
+
+Here are the conditions involved in the status combination process:
+
+|    Condition   |  Description  |
+|----------------|---------------|
+| `StorageReady` | in-cluster storage minio service is ready |
+| `DatabaseReady` | in-cluster database postgresql is ready |
+| `CacheReady` | in-cluster cache redis is ready |
+| `ServiceReady` | the harbor is ready |
+
+> NOTE: condition `ConfigurationReady` indicates if the cfgMap based Day2 configuration has been successfully applied. But it does not take account into the combination of the overall status.
+
+### Overall status
+
+The overall status dimensions and the conditions of its establishment is listed in the table shown below:
+
+|     Status  | Conditions |
+|-------------|------------|
+| `healthy`   | 4 conditions are all `True` |
+| `unhealthy` | at least one of the 4 conditions is `False` |
+| `creating`  | Otherwise |
+
+## Reconcile loop
+
+The reconcile loop is triggered by a Kubernetes event when the `HarborCluster` Resource or relevant resources owned by that `HarborCluster` changes.
+
+```text
+                  Event received      +----------------------+
+                  ------------------->|      Reconcile       |
+                                      +----------+-----------+
+                                                 |
+                                                 |          True
+                                               Deleted? ------------>Exit
+                                                 |
+                                                 |
+                                                 v
+                                     Start service deploy group
+                 +-------------------------------+----------------------------+
+                 |                               |                            |
+                 |                               |                            |
+                 |                               |                            |
++----------------v---------------+   +-----------+-----------+    +-----------v---------+
+|     PostgreSQL Reconcile       |   |    Redis Reconcile    |    |   Minio Reconcile   |
++----------------+---------------+   +-----------+-----------+    +-----------+---------+
+                 |                               |                            |
+                 |                               |                            |
+                 |                               |                            |
+                 |                               |                            |
+                 v                               v                            v
+          Apply or update                  Apply or update             Apply or update
+                 |                               |                            |
+                 |                               |                            |
+                 |                               |                            |
+                 |                               |                            |
+                 |                               v                            |
+                 +--------------------> Any error occurred?<------------------+
+                                                 |      |
+                                                 | NO   |             YES
+                                                 |      +----------------------------> Exit
+                                                 |                                      |
+                                                 v                   NO                 |
+                                      All services are ready?------------------> Exit   |
+                                                 |                                |     |
+                                                 | YES                            |     |
+                                                 |                                |     |
+                                                 |                                |     |
+                                                 v                                |     |
+                                      +----------------------+                    |     |
+                                      |   Harbor Reconcile   |                    |     |
+                                      +----------+-----------+                    |     |
+                                                 |                                |     |
+                                                 |                                |     |
+                                                 |                                |     |
+                                                 v                                |     |
+                                          Apply or update?                        |     |
+                                                 |                                |     |
+                                                 |                                |     |
+                                                 |                                |     |
+                                                 |                                |     |
+                                                 v              YES               |     |
+                                        Any error occurred? -----------> Exit     |     |
+                                                 |                        |       |     |
+                                                 |                        |       |     |
+                                                 | NO                     |       |     |
+                                                 |                        |       |     |
+                                                 v                        |       |     |
+                                             Completed                    |       |     |
+                                                 |                        |       |     |
+                                                 |                        |       |     |
+                                                 |                        |       |     |
+                                                 |                        |       |     |
+                                  +--------------+--------------+         |       |     |
+                                  |  Set status & conditions    <---------+-------+-----+
+                                  +-----------------------------+
+```
diff --git a/docs/LCM/cluster-deletion.md b/docs/LCM/cluster-deletion.md
@@ -1,5 +1,29 @@
 # Delete the Harbor cluster
 
-[backup data](./backup-data.md) before deletion.
+For deleting the deployed Harbor cluster, one important thing to note here is, you should make sure all your data is correctly [backup](./backup-data.md) before deletion if you cares about your data (not development or testing environments).
 
-TBD
+## Delete the Harbor cluster CR
+
+You can delete your Harbor cluster by deleting the CR with `kubectl`:
+
+```shell
+# Replace the text between <> with the real ones.
+kubectl delete HarborCluster/<myClusterName> -n <myNamespace>
+
+# e.g:
+# kubectl delete HarborCluster/harbor-cluster-sample -n sample
+```
+
+> NOTE: the command shown above will delete the Harbor cluster as well as all the associated resources (including all the PVs) except the ones pre-created such as namespace, root password or cert-manager issuer etc.
+
+## Delete by manifest
+
+The Harbor cluster can also be deleted via the deployment manifests that may be either the manifest yaml file or the kustomization template file. With this way, both the associated resources and the resources pre-defined in the manifest like namespace, root password or cert-manager issuer etc. can be cleaned up at the same time.
+
+```shell
+# With deployment manifest
+kubectl delete -f my-deployment.yaml
+
+# OR with kustomization template
+kustomize build | kubectl delete -f -
+```
diff --git a/docs/LCM/controllers.md b/docs/LCM/controllers.md
@@ -1,6 +1,6 @@
 # Controllers
 
-ATM All controllers are based on the same framework except harbor-cluster.
+ATM All controllers are based on the same framework except [harbor-cluster](./cluster-controller.md).
 
 The framework manages basic status fields: `observedGeneration` and `conditions`.
 
@@ -29,7 +29,7 @@ On [Reconciler](#control-loop) side, `unknown` is considered the same way than `
 
 ## Control loop
 
-The control loop is triggered by a kubernetes event when one of the Resource controlled by the operator changes.
+The control loop is triggered by a Kubernetes event when one of the Resource controlled by the operator changes.
 
 ```text
 Event received  +------------ +

diff --git a/docs/LCM/monitor-logs-with-grafana.md b/docs/LCM/monitor-logs-with-grafana.md
@@ -0,0 +1,3 @@
+# Monitor logs with grafana
+
+TBD
diff --git a/docs/LCM/upgrade-cluster.md b/docs/LCM/upgrade-cluster.md
@@ -0,0 +1,3 @@
+# How to upgrade your Harbor cluster
+
+TBD
diff --git a/docs/arch/arch.md b/docs/arch/arch.md
@@ -20,7 +20,7 @@ Each component CR has its own controller that will reconcile the component CR to
 
 Multiple level CRDs simplifies the overall stack and bring more clear responsibility boundary. Cascaded ownership is enabled among CRs at different levels, the deletion of top level CR `HarborCluster` will clear all related CRs and resources.
 
-## References``
+## References
 
-* Learn more about the reconcile process, check [reconcile process](./reconciler.md)
+* Learn more about the reconcile process, check [reconcile process](../LCM/controllers.md)
 * Learn more about day2 operations, check [day2 operation design](./day2-op.md)
diff --git a/docs/makefile.md b/docs/makefile.md
@@ -25,3 +25,6 @@ The `Makefile` is in the root dir of the code repository.
 | `install-dependencies` | Install the related dependencies including cert-manager, ingress controller, redis and postgresql |
 | `dev-tools`    | Install kids of the development tools |
 | `sample-%`    | Deploy the related sample CR. `%` can be the name of sub folders under [samples](../config/samples) |
+| `postgresql` | Deploy a PostgreSQL database with bitnami chart|
+| `redis` | Deploy a Redis database with bitnami chart |
+| `sample-github-secret` | Create a secret wrapping the GitHub token read from the env variable `GITHUB_TOKEN`|
diff --git a/docs/manifests-reference.md b/docs/manifests-reference.md
@@ -70,6 +70,9 @@ This folder contains several sample manifests for you to deploy Harbor cluster w
 | [harbor_core_minio.yaml](../manifests/samples/harbor_core_minio.yaml) |Deploy the Harbor cluster with the structure: harbor core components + in-cluster storage(Minio) + in-cluster PostgreSQL + in-cluster Redis |
 | [harbor_full_fs.yaml](../manifests/samples/harbor_full_fs.yaml) |Deploy the Harbor cluster with the structure: harbor all components + filesystem storage(PV) + in-cluster PostgreSQL + in-cluster Redis |
 | [harbor_full_minio.yaml](../manifests/samples/harbor_full_minio.yaml) |Deploy the Harbor cluster with the structure: harbor all components + in-cluster storage(Minio) + in-cluster PostgreSQL + in-cluster Redis |
+| [harborcluster_standard_stack_external.yaml](../manifests/samples/harborcluster_standard_stack_external.yaml) |Deploy the Harbor cluster with the structure: harbor all components + filesystem storage(PV) + external PostgreSQL + external Redis|
+
+> NOTE: `external` means you need to pre-deploy the required services; `in-cluster` means the Harbor operator will create the required services while deploying the Harbor cluster.
 
 ## What's next