full-docs changes for operator 1.1.0 (#1256)

* full-docs changes for operator 1.1.0 * use macros for version * Update 1.configurations.md * bug fix * Update docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md Co-authored-by: randomJoe211 <[email protected]> * Update 6.eco-tool-version.md * Update 9.upgrade-nebula-cluster.md * Update mkdocs.yml Co-authored-by: randomJoe211 <[email protected]>
vesoft-inc · Apr 21, 2022 · a908574 · a908574
1 parent cc09ae2
commit a908574
Show file tree

Hide file tree

Showing 13 changed files with 127 additions and 93 deletions.
diff --git a/docs-2.0/20.appendix/6.eco-tool-version.md b/docs-2.0/20.appendix/6.eco-tool-version.md
@@ -74,9 +74,13 @@ Nebula Exchange (Exchange for short) is an Apache Spark&trade application for ba
 |:---|:---|:--|
 | {{ nebula.release }}  | {{exchange.release}} | {{exchange_ent.release}} |
 
-<!-- ## Nebula Operator
+## Nebula Operator
 
-Nebula Operator (Operator for short) is a tool to automate the deployment, operation, and maintenance of Nebula Graph clusters on Kubernetes. Building upon the excellent scalability mechanism of Kubernetes, Nebula Graph introduced its operation and maintenance knowledge into the Kubernetes system, which makes Nebula Graph a real cloud-native graph database. For more information, see [What is Nebula Operator](../nebula-operator/1.introduction-to-nebula-operator.md). -->
+Nebula Operator (Operator for short) is a tool to automate the deployment, operation, and maintenance of Nebula Graph clusters on Kubernetes. Building upon the excellent scalability mechanism of Kubernetes, Nebula Graph introduced its operation and maintenance knowledge into the Kubernetes system, which makes Nebula Graph a real cloud-native graph database. For more information, see [What is Nebula Operator](../nebula-operator/1.introduction-to-nebula-operator.md).
+
+|Nebula Graph version|Operator version|
+|:---|:---|
+| {{ nebula.release }}  | {{operator.release}}|
 
 ## Nebula Importer
 

diff --git a/docs-2.0/20.appendix/learning-path.md b/docs-2.0/20.appendix/learning-path.md
@@ -179,11 +179,11 @@ This topic is for anyone interested in learning more about Nebula Graph. You can
   | ------------------------------------------------------------ |
   | [Nebula Bench](../nebula-bench.md) |
 
-<!-- - Cluster O&M
+- Cluster O&M
 
   | Document  |
   | -------- |
-  | [Nebula Operator](../nebula-operator/1.introduction-to-nebula-operator.md) | -->
+  | [Nebula Operator](../nebula-operator/1.introduction-to-nebula-operator.md) |
 
 - Graph algorithm
 

diff --git a/docs-2.0/5.configurations-and-logs/1.configurations/1.configurations.md b/docs-2.0/5.configurations-and-logs/1.configurations/1.configurations.md
@@ -89,7 +89,6 @@ Each initial configuration file of all services contains `local_config`. The def
 
 For clusters installed with Docker Compose, the configuration file's default installation path of the cluster is `<install_path>/nebula-docker-compose/docker-compose.yaml`. The parameters in the `command` field of the file are the launch parameters for each service.  
 
-<!-- Unhide until Operator is published next version
 
 ### Configuration files for clusters installed with Nebula Operator
 
@@ -120,5 +119,5 @@ By default, each Nebula Graph service gets configured from its configuration fil
 
 1. Use a text editor to modify the configuration files of the target service and save the modification.
 
-2. Choose an appropriate time to restart **all** Nebula Graph services to make the modifications valid. -->
+2. Choose an appropriate time to restart **all** Nebula Graph services to make the modifications valid.
 
diff --git a/docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md b/docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md
@@ -18,7 +18,7 @@ The following features are already available in Nebula Operator:
 
 - **Scale clusters**: Nebula Operator calls Nebula Graph's native scaling interfaces in a control loop to implement the scaling logic. You can simply perform scaling operations with YAML configurations and ensure the stability of data. For more information, see [Scale clusters with Kubectl](3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md) or [Scale clusters with Helm](3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md).
 
-- **Cluster Upgrade**: Nebula Operator supports cluster upgrading from version 2.5.x to version 2.6.x.
+- **Cluster Upgrade**: Nebula Operator supports cluster upgrading from version {{operator.upgrade_from}} to version {{operator.upgrade_to}}.
 
 - **Self-Healing**: Nebula Operator calls interfaces provided by Nebula Graph clusters to dynamically sense cluster service status. Once an exception is detected, Nebula Operator performs fault tolerance. For more information, see [Self-Healing](5.operator-failover.md).
 
@@ -32,13 +32,20 @@ Nebula Operator does not support the v1.x version of Nebula Graph. Nebula Operat
 
 | Nebula Operator version | Nebula Graph version |
 | ------------------- | ---------------- |
-| {{operator.release}}| 2.5.x ~ 2.6.x |
+| 1.1.0| 3.0.0 ~ 3.1.x |
+| 1.0.0| 3.0.0 ~ 3.1.x |
+| 0.9.0| 2.5.x ~ 2.6.x |
 |0.8.0|2.5.x|
 
+!!! Compatibility "Legacy version compatibility"
+
+    - The 1.x version Nebula Operator is not compatible with Nebula Graph of version below v3.x.
+    - Starting from Nebula Operator 0.9.0, logs and data are stored separately. Using Nebula Operator 0.9.0 or later versions to manage a Nebula Graph 2.5.x cluster created with Operator 0.8.0 can cause compatibility issues. You can backup the data of the Nebula Graph 2.5.x cluster and then create a 2.6.x cluster with Operator 0.9.0.
+
 ### Feature limitations
 
 Nebula Operator currently only supports manual scaling of Nebula Graph clusters, and does not support automatic scaling of Nebula Graph clusters.
 
 ## Release note
 
-[Release](https://github.com/vesoft-inc/nebula-operator/releases/tag/{{operator.branch}})
+[Release](https://github.com/vesoft-inc/nebula-operator/releases/tag/v{{operator.release}})
diff --git a/docs-2.0/nebula-operator/2.deploy-nebula-operator.md b/docs-2.0/nebula-operator/2.deploy-nebula-operator.md
@@ -94,7 +94,7 @@ For example:
 [k8s@master ~]$ helm show values nebula-operator/nebula-operator
 image:
   nebulaOperator:
-    image: vesoft/nebula-operator:{{operator.branch}}
+    image: vesoft/nebula-operator:v{{operator.release}}
     imagePullPolicy: Always
   kubeRBACProxy:
     image: gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0
@@ -139,7 +139,7 @@ Part of the above parameters are described as follows:
 
 | Parameter                                   | Default value                          | Description                                 |
 | :------------------------------------- | :------------------------------ | :----------------------------------------- |
-| `image.nebulaOperator.image`           | `vesoft/nebula-operator:{{operator.branch}}` | The image of Nebula Operator, version of which is {{operator.release}}. |
+| `image.nebulaOperator.image`           | `vesoft/nebula-operator:v{{operator.release}}` | The image of Nebula Operator, version of which is {{operator.release}}. |
 | `image.nebulaOperator.imagePullPolicy` | `IfNotPresent`                  | The image pull policy in Kubernetes.                            |
 | `imagePullSecrets`                     | -                               | The image pull secret in Kubernetes.                            |
 | `kubernetesClusterDomain`              | `cluster.local`                 | The cluster domain.                                |
@@ -162,37 +162,40 @@ For more information about `helm install`, see [Helm Install](https://helm.sh/do
 
 ### Update Nebula Operator
 
-After installing Nebula Operator, you can update it by modifying the parameter values in the `${HOME}/nebula-operator/charts/nebula-operator/values.yaml` file.
-
-1. Clone the Nebula Operator repository to your local server.
+1. Update the information of available charts locally from chart repositories.
    
   ```bash
-  git clone https://github.com/vesoft-inc/nebula-operator.git
-  ```
+  helm repo update
+  ``` 
 
-2. Modify the parameter values in `${HOME}/nebula-operator/charts/nebula-operator/values.yaml`.
+2. Update Nebula Operator by passing configuration parameters via `-set` or `-values` flag.
+
+  - `--set`：Overrides values using the command line. 
+  - `--values` (or `-f`)：Overrides values using YAML files. 
+
+  For configurable items, see the above-mentioned section **Customize Helm charts**.
+
+  For example, to disable the AdmissionWebhook ( AdmissionWebhook is enabled by default), run the following command:
 
-3. Run the following command to update Nebula Operator.
-   
   ```bash
-  helm upgrade nebula-operator nebula-operator/nebula-operator --namespace=<namespace_name> -f ${HOME}/nebula-operator/charts/nebula-operator/values.yaml
+  helm upgrade nebula-operator nebula-operator/nebula-operator --namespace=nebula-operator-system --version={{operator.release}} --set admissionWebhook.create=false
   ```
 
-  `<namespace_name>` is a user-created namespace name. Pods related to the nebula-operator repository are in this namespace.
+  For more information, see [Helm upgrade](https://helm.sh/docs/helm/helm_update/).
 
 ### Upgrade Nebula Operator
 
 !!! Compatibility "Legacy version compatibility"
 
-    Starting from Nebula Operator 0.9.0, logs and data are stored separately. Managing a Nebula Graph 2.5.x cluster with Nebula Operator 0.9.0 or later versions can cause compatibility issues. You can backup the data of the Nebula Graph 2.5.x cluster and then create a 2.6.x cluster with Operator.
+    The 1.x version Nebula Operator is not compatible with Nebula Graph of version below v3.x.
 
 1. Update the information of available charts locally from chart repositories.
    
   ```bash
   helm repo update
   ``` 
 
-2. Upgrade Operator.
+2. Upgrade Operator to v{{operator.release}}.
 
   ```bash
   helm upgrade nebula-operator nebula-operator/nebula-operator --namespace=<namespace_name> --version={{operator.release}}
@@ -209,7 +212,7 @@ After installing Nebula Operator, you can update it by modifying the parameter v
   ```bash
   Release "nebula-operator" has been upgraded. Happy Helming!
   NAME: nebula-operator
-  LAST DEPLOYED: Tue Nov 16 02:21:08 2021
+  LAST DEPLOYED: Tue Apr 16 02:21:08 2022
   NAMESPACE: nebula-operator-system
   STATUS: deployed
   REVISION: 3
@@ -221,28 +224,37 @@ After installing Nebula Operator, you can update it by modifying the parameter v
 3. Pull the latest CRD configuration file.
 
   !!! note
-        You need to upgrade the corresponding CRD configurations after Nebula Operator is upgraded. Otherwise, the creation of Nebula Graph clusters will fail. For information about the CRD configurations, see [apps.nebula-graph.io_nebulaclusters.yaml](https://github.com/vesoft-inc/nebula-operator/blob/{{operator.branch}}/config/crd/bases/apps.nebula-graph.io_nebulaclusters.yaml).
+        You need to upgrade the corresponding CRD configurations after Nebula Operator is upgraded. Otherwise, the creation of Nebula Graph clusters will fail. For information about the CRD configurations, see [apps.nebula-graph.io_nebulaclusters.yaml](https://github.com/vesoft-inc/nebula-operator/blob/v{{operator.release}}/config/crd/bases/apps.nebula-graph.io_nebulaclusters.yaml).
 
-  ```bash
-  helm pull nebula-operator/nebula-operator
-  ```
+  1. Pull the Nebula Operator chart package.
 
-4. Upgrade the CRD configuration file.
+    ```bash
+    helm pull nebula-operator/nebula-operator --version={{operator.release}}
+    ```
 
-  ```bash
-  kubectl apply -f <crd_file_name>.yaml
-  ```
+    - `--version`: The Nebula Operator version you want to upgrade to. If not specified, the latest version will be pulled.
 
-  For example:
+  2. Run `tar -zxvf` to unpack the charts.
+
+    For example: To unpack v{{operator.release}} chart to the `/tmp` path, run the following command:
+
+    ```bash
+    tar -zxvf nebula-operator-{{operator.release}}.tgz -C /tmp
+    ```
+
+    - `-C /tmp`: If not specified, the chart files will be unpacked to the current directory.
+  
+
+4. Upgrade the CRD configuration file in the `nebula-operator` directory.
 
   ```bash
-  kubectl apply -f config/crd/bases/apps.nebula-graph.io_nebulaclusters.yaml
+  kubectl apply -f crds/nebulacluster.yaml
   ```
 
   Output:
 
   ```bash
-  customresourcedefinition.apiextensions.k8s.io/nebulaclusters.apps.nebula-graph.io created
+  customresourcedefinition.apiextensions.k8s.io/nebulaclusters.apps.nebula-graph.io configured
   ```
   
 ### Uninstall Nebula Operator

diff --git a/...nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md b/...nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md
@@ -1,5 +1,9 @@
 # Deploy Nebula Graph clusters with Kubectl
 
+!!! Compatibility "Legacy version compatibility"
+
+    The 1.x version Nebula Operator is not compatible with Nebula Graph of version below v3.x.
+
 ## Prerequisites
 
 [Install Nebula Operator](../2.deploy-nebula-operator.md)
@@ -28,7 +32,7 @@ The following example shows how to create a Nebula Graph cluster by creating a c
           memory: "1Gi"
       replicas: 1
       image: vesoft/nebula-graphd
-      version: {{nebula.branch}}
+      version: v{{nebula.release}}
       service:
         type: NodePort
         externalTrafficPolicy: Local
@@ -47,7 +51,7 @@ The following example shows how to create a Nebula Graph cluster by creating a c
           memory: "1Gi"
       replicas: 1
       image: vesoft/nebula-metad
-      version: {{nebula.branch}}
+      version: v{{nebula.release}}
       dataVolumeClaim:
         resources:
           requests:
@@ -68,7 +72,7 @@ The following example shows how to create a Nebula Graph cluster by creating a c
           memory: "1Gi"
       replicas: 3
       image: vesoft/nebula-storaged
-      version: {{nebula.branch}}
+      version: v{{nebula.release}}
       dataVolumeClaim:
         resources:
           requests:
@@ -93,17 +97,17 @@ The following example shows how to create a Nebula Graph cluster by creating a c
   | `metadata.name`              | -                                                            | The name of the created Nebula Graph cluster. |
   | `spec.graphd.replicas`       | `1`                                                          | The numeric value of replicas of the Graphd service.         |
   | `spec.graphd.images`         | `vesoft/nebula-graphd`                                       | The container image of the Graphd service.      |
-  | `spec.graphd.version`        | `{{nebula.branch}}`                                          | The version of the Graphd service.         |
+  | `spec.graphd.version`        | `v{{nebula.release}}`                                          | The version of the Graphd service.         |
   | `spec.graphd.service`        | -                                                            | The Service configurations for the Graphd service.      |
   | `spec.graphd.logVolumeClaim.storageClassName`   | -                                         | The log disk storage configurations for the Graphd service.         |
   | `spec.metad.replicas`        | `1`                                                          | The numeric value of replicas of the Metad service.          |
   | `spec.metad.images`          | `vesoft/nebula-metad`                                        | The container image of the Metad service.        |
-  | `spec.metad.version`         | `{{nebula.branch}}`                                          | The version of the Metad service.          |
+  | `spec.metad.version`         | `v{{nebula.release}}`                                          | The version of the Metad service.          |
   | `spec.metad.dataVolumeClaim.storageClassName`    | -                                        | The data disk storage configurations for the Metad service.          |
   | `spec.metad.logVolumeClaim.storageClassName`|-                                              | The log disk storage configurations for the Metad service.|
   | `spec.storaged.replicas`     | `3`                                                          | The numeric value of replicas of the Storaged service.       |
   | `spec.storaged.images`       | `vesoft/nebula-storaged`                                     | The container image of the Storaged service.     |
-  | `spec.storaged.version`      | `{{nebula.branch}}`                                          | The version of the Storaged service.       |
+  | `spec.storaged.version`      | `v{{nebula.release}}`                                          | The version of the Storaged service.       |
   | `spec.storaged.dataVolumeClaim.storageClassName` | -                                        | The data disk storage configurations for the Storaged service.       |
   | `spec.storaged.logVolumeClaim.storageClassName`|-                                           | The log disk storage configurations for the Storaged service.|
   | `spec.reference.name`        | -                                                            | The name of the dependent controller.           |
@@ -139,7 +143,8 @@ The following example shows how to create a Nebula Graph cluster by creating a c
 
 !!! enterpriseonly
 
-    The cluster scaling feature is for Nebula Graph Enterprise Edition only. Scaling a Nebula Graph cluster for Enterprise Edition is supported only with Nebula Operator version 1.1.0 or later. 
+    - The cluster scaling feature is for Nebula Graph Enterprise Edition only. 
+    - Scaling a Nebula Graph cluster for Enterprise Edition is supported only with Nebula Operator version 1.1.0 or later. 
 
 You can modify the value of `replicas` in `apps_v1alpha1_nebulacluster.yaml` to scale a Nebula Graph cluster.
 
@@ -160,7 +165,7 @@ The following shows how to scale out a Nebula Graph cluster by changing the numb
           memory: "1Gi"
       replicas: 5
       image: vesoft/nebula-storaged
-      version: {{nebula.branch}}
+      version: v{{nebula.release}}
       dataVolumeClaim:
         resources:
           requests:

diff --git a/....0/nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md b/....0/nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md
@@ -1,5 +1,9 @@
 # Deploy Nebula Graph clusters with Helm
 
+!!! Compatibility "Legacy version compatibility"
+
+    The 1.x version Nebula Operator is not compatible with Nebula Graph of version below v3.x.
+
 ## Prerequisite
 
 [Install Nebula Operator](../2.deploy-nebula-operator.md)
@@ -65,7 +69,8 @@
 
 !!! enterpriseonly
 
-    The cluster scaling feature is for Nebula Graph Enterprise Edition only. Scaling a Nebula Graph cluster for Enterprise Edition is supported only with Nebula Operator version 1.1.0 or later. 
+    - The cluster scaling feature is for Nebula Graph Enterprise Edition only. 
+    - Scaling a Nebula Graph cluster for Enterprise Edition is supported only with Nebula Operator version 1.1.0 or later. 
 
 You can scale a Nebula Graph cluster by defining the value of the `replicas` corresponding to the different services in the cluster.
 
@@ -85,7 +90,7 @@ Similarly, you can scale in a Nebula Graph cluster by setting the value of the `
 
     Nebula Operator currently only supports scaling Graph and Storage services and does not support scale Meta services.
 
-You can click on [nebula-cluster/values.yaml](https://github.com/vesoft-inc/nebula-operator/blob/{{operator.branch}}/charts/nebula-cluster/values.yaml) to see more configurable parameters of the nebula-cluster chart. For more information about the descriptions of configurable parameters, see **Configuration parameters of the nebula-cluster Helm chart** below.
+You can click on [nebula-cluster/values.yaml](https://github.com/vesoft-inc/nebula-operator/blob/v{{operator.release}}/charts/nebula-cluster/values.yaml) to see more configurable parameters of the nebula-cluster chart. For more information about the descriptions of configurable parameters, see **Configuration parameters of the nebula-cluster Helm chart** below.
 
 ## Delete clusters
 
@@ -104,7 +109,7 @@ helm uninstall "${NEBULA_CLUSTER_NAME}" --namespace="${NEBULA_CLUSTER_NAMESPACE}
 | Parameter                        | Default value                                                       | Description                                                         |
 | :-------------------------- | :----------------------------------------------------------- | ------------------------------------------------------------ |
 | `nameOverride`              | `nil`                                                        | Replaces the name of the chart in the `Chart.yaml` file.                                        |
-| `nebula.version`            | `{{nebula.branch}}`                                                     | The version of Nebula Graph.                                        |
+| `nebula.version`            | `v{{nebula.release}}`                                                     | The version of Nebula Graph.                                        |
 | `nebula.imagePullPolicy`    | `IfNotPresent`                                               | The Nebula Graph image pull policy. For details, see [Image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy). |
 | `nebula.storageClassName`   | `nil`                                                        | The StorageClass name. StorageClass is the default persistent volume type.                |
 | `nebula.schedulerName`      | `default-scheduler`                                          | The scheduler name of a Nebula Graph cluster.                                   |