update orchestorator

examples/orchestrator/README.md

@@ -2,99 +2,155 @@
 
 Orchestrator is a MySQL high availability and replication management tool, runs as a service and provides command line access, HTTP API and Web interface.
 
+## Features In KubeBlocks
+
+### Lifecycle Management
+
+| Horizontal<br/>scaling | Vertical <br/>scaling | Expand<br/>volume | Restart   | Stop/Start | Configure | Expose | Switchover |
+|------------------------|-----------------------|-------------------|-----------|------------|-----------|--------|------------|
+| Yes (Share-Backend Mode) | Yes                   | Yes               | Yes       | Yes        | No        | Yes    | No      |
+
+### Versions
+
+| Versions |
+|----------|
+| 3.2.6    |
+
 ## Prerequisites
 
-This example assumes that you have a Kubernetes cluster installed and running, and that you have installed the kubectl command line tool and helm somewhere in your path. Please see the [getting started](https://kubernetes.io/docs/setup/)  and [Installing Helm](https://helm.sh/docs/intro/install/) for installation instructions for your platform.
+- Kubernetes cluster >= v1.21
+- `kubectl` installed, refer to [K8s Install Tools](https://kubernetes.io/docs/tasks/tools/)
+- Helm, refer to [Installing Helm](https://helm.sh/docs/intro/install/)
+- KubeBlocks installed and running, refer to [Install Kubeblocks](../docs/prerequisites.md)
+- Orchestrator Addon Enabled, refer to [Install Addons](../docs/install-addon.md)
+
+## Examples
+
+### [Create](cluster.yaml)
+
+Orchestrator cluster has two modes: *raft* and *share-backend*.
+
+- *share-backend*: Orchestrator cluster with shared backend[^1], here we create an ApeCloud MySQL cluster as the backend. Recommended for large scale.
 
-Also, this example requires kubeblocks installed and running. Here is the steps to install kubeblocks, please replace "`$kb_version`" with the version you want to use.
 ```bash
-# Add Helm repo 
-helm repo add kubeblocks https://apecloud.github.io/helm-charts
-# If github is not accessible or very slow for you, please use following repo instead
-helm repo add kubeblocks https://jihulab.com/api/v4/projects/85949/packages/helm/stable
-
-# Update helm repo
-helm repo update
-
-# Get the versions of KubeBlocks and select the one you want to use
-helm search repo kubeblocks/kubeblocks --versions
-# If you want to obtain the development versions of KubeBlocks, Please add the '--devel' parameter as the following command
-helm search repo kubeblocks/kubeblocks --versions --devel
-
-# Create dependent CRDs
-kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v$kb_version/kubeblocks_crds.yaml
-# If github is not accessible or very slow for you, please use following command instead
-kubectl create -f https://jihulab.com/api/v4/projects/98723/packages/generic/kubeblocks/v$kb_version/kubeblocks_crds.yaml
-
-# Install KubeBlocks
-helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version="$kb_version"
+kubectl apply -f examples/orchestrator/cluster-shareend.yaml
 ```
-Enable orchestrator
-```bash
-# Add Helm repo 
-helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts
-# If github is not accessible or very slow for you, please use following repo instead
-helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable
-# Update helm repo
-helm repo update
-
-# Enable orchestrator 
-helm upgrade -i kb-addon-orchestrator kubeblocks-addons/orchestrator --version $kb_version -n kb-system
-``` 
-
 
-## Examples
+- *raft*: Orchestrator cluster with Raft consensus[^2]. Recommended for small to medium scale.
 
-### [Create](cluster.yaml) 
-Orchestrator cluster has two modes: raft and share-backend.
-Create a orchestrator cluster with specified component definition.
 ```bash
 kubectl apply -f examples/orchestrator/cluster-raft.yaml
 ```
+
+Please choose one of the above cluster creation methods according to your needs and scale.
+
+To visit Orchestrator Web UI, you can use the following command to get the service URL:
+
 ```bash
-kubectl apply -f examples/orchestrator/cluster-shareend.yaml
+kubectl svc/orchestrator-cluster-orchestrator 3000:80
+```
+
+Then you can visit the Orchestrator Web UI with the following URL:
+
+```bash
+http://localhost:3000
+```
+
+### Horizontal scaling
+
+#### [Scale-out](scale-out.yaml)
+
+> [!IMPORTANT]
+> As per the Orchestrator documentation, the number of Orchestrator instances should be odd to avoid split-brain scenarios.
+> Make sure the number of Orchestrator instances is always an odd number after scaling in or out.
+
+To scale out the Orchestrator cluster of Share-Backend Mode
+
+```bash
+kubectl apply -f examples/orchestrator/scale-out.yaml
 ```
 
-### [Horizontal scaling](horizontalscale.yaml)
-Horizontal scaling out or in specified components replicas in the cluster
+#### [Scale-in](scale-in.yaml)
+
+To scale in the Orchestrator cluster of Share-Backend Mode
+
 ```bash
-kubectl apply -f examples/orchestrator/horizontalscale.yaml
+kubectl apply -f examples/orchestrator/scale-in.yaml
+```
+
+#### Scale-in/out using Cluster API
+
+Alternatively, you can update the `replicas` field in the `spec.componentSpecs.replicas` section to your desired non-zero number.
+
+```yaml
+apiVersion: apps.kubeblocks.io/v1
+kind: Cluster
+metadata:
+  name: orchestrator-cluster
+  namespace: default
+spec:
+  componentSpecs:
+    - name: orchestrator
+      componentDef: componentDef: orchestrator-shareend
+      replicas: 3 # Update `replicas` to your desired number
 ```
 
 ### [Vertical scaling](verticalscale.yaml)
+
 Vertical scaling up or down specified components requests and limits cpu or memory resource in the cluster
+
 ```bash
 kubectl apply -f examples/orchestrator/verticalscale.yaml
 ```
 
 ### [Expand volume](volumeexpand.yaml)
+
 Increase size of volume storage with the specified components in the cluster
+
 ```bash
 kubectl apply -f examples/orchestrator/volumeexpand.yaml
 ```
 
 ### [Restart](restart.yaml)
+
 Restart the specified components in the cluster
+
 ```bash
 kubectl apply -f examples/orchestrator/restart.yaml
 ```
 
 ### [Stop](stop.yaml)
+
 Stop the cluster and release all the pods of the cluster, but the storage will be reserved
+
 ```bash
 kubectl apply -f examples/orchestrator/stop.yaml
 ```
 
 ### [Start](start.yaml)
+
 Start the stopped cluster
+
 ```bash
 kubectl apply -f examples/orchestrator/start.yaml
-````
+```
 
 ### Delete
+
 If you want to delete the cluster and all its resource, you can modify the termination policy and then delete the cluster
+
 ```bash
-kubectl patch cluster orch-cluster -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
+kubectl patch cluster orchestrator-cluster -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
 
-kubectl delete cluster orch-cluster
+kubectl delete cluster orchestrator-cluster
+
+# or delete all clusters created in this example
+# you may use the following command:
+# kubectl delete -f examples/orchestrator/cluster-shareend.yaml
+# kubectl delete -f examples/orchestrator/cluster-raft.yaml
 ```
+
+### Reference
+
+[^1]: Shared Backend, https://github.com/openark/orchestrator/blob/master/docs/deployment-shared-backend.md
+[^2]: Raft, https://github.com/openark/orchestrator/blob/master/docs/deployment-raft.md

examples/orchestrator/cluster-raft.yaml

@@ -1,14 +1,13 @@
 apiVersion: apps.kubeblocks.io/v1
 kind: Cluster
 metadata:
-  name: orchestrator-cluster
+  name: orchestrator-cluster-raft
   namespace: default
 spec:
   # Specifies the behavior when a Cluster is deleted.
   # - `DoNotTerminate`: Prevents deletion of the Cluster. This policy ensures that all resources remain intact.
   # - `Halt`: Deletes Cluster resources like Pods and Services but retains Persistent Volume Claims (PVCs), allowing for data preservation while stopping other operations.
   # - `Delete`: Extends the `Halt` policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data.
-  # - `WipeOut`: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss.
   terminationPolicy: Delete
   # Specifies a list of ClusterComponentSpec objects used to define the individual components that make up a Cluster. This field allows for detailed configuration of each component within the Cluster.
   # Note: `shardingSpecs` and `componentSpecs` cannot both be empty; at least one must be defined to configure a cluster.

examples/orchestrator/cluster-shareend.yaml

@@ -4,19 +4,10 @@ metadata:
   name: orchestrator-cluster
   namespace: default
 spec:
-  # Specifies the behavior when a Cluster is deleted.
-  # - `DoNotTerminate`: Prevents deletion of the Cluster. This policy ensures that all resources remain intact.
-  # - `Halt`: Deletes Cluster resources like Pods and Services but retains Persistent Volume Claims (PVCs), allowing for data preservation while stopping other operations.
-  # - `Delete`: Extends the `Halt` policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data.
-  # - `WipeOut`: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss.
   terminationPolicy: Delete
-  # Specifies a list of ClusterComponentSpec objects used to define the individual components that make up a Cluster. This field allows for detailed configuration of each component within the Cluster.
-  # Note: `shardingSpecs` and `componentSpecs` cannot both be empty; at least one must be defined to configure a cluster.
-  # ClusterComponentSpec defines the specifications for a Component in a Cluster.
   componentSpecs:
     - name: orchestrator
       componentDef: orchestrator-shareend
-      disableExporter: true
       replicas: 3
       resources:
         requests:
@@ -52,24 +43,26 @@ metadata:
   namespace: default
 spec:
   terminationPolicy: Delete
+  clusterDef: apecloud-mysql
+  topology: apecloud-mysql
   componentSpecs:
-  - name: mysql
-    componentDef: apecloud-mysql
-    disableExporter: true
-    serviceAccountName: kb-mysqlo-cluster
-    replicas: 3
-    resources:
-      limits:
-        cpu: '0.5'
-        memory: 0.5Gi
-      requests:
-        cpu: '0.5'
-        memory: 0.5Gi
-    volumeClaimTemplates:
-    - name: data
-      spec:
-        accessModes:
-        - ReadWriteOnce
-        resources:
-          requests:
-            storage: 20Gi
+    - name: mysql
+      serviceVersion: "8.0.30"
+      disableExporter: false
+      replicas: 3
+      resources:
+        limits:
+          cpu: '0.5'
+          memory: 0.5Gi
+        requests:
+          cpu: '0.5'
+          memory: 0.5Gi
+      volumeClaimTemplates:
+        - name: data
+          spec:
+            storageClassName: ""
+            accessModes:
+              - ReadWriteOnce
+            resources:
+              requests:
+                storage: 20Gi

examples/orchestrator/restart.yaml

@@ -1,4 +1,4 @@
-apiVersion: apps.kubeblocks.io/v1alpha1
+apiVersion: operations.kubeblocks.io/v1alpha1
 kind: OpsRequest
 metadata:
   name: orchestrator-restart

examples/orchestrator/horizontalscale.yaml → examples/orchestrator/scale-in.yaml

@@ -1,7 +1,7 @@
-apiVersion: apps.kubeblocks.io/v1alpha1
+apiVersion: operations.kubeblocks.io/v1alpha1
 kind: OpsRequest
 metadata:
-  name: orchestrator-horizontalscaling
+  name: orc-scale-in
   namespace: default
 spec:
   # Specifies the name of the Cluster resource that this operation is targeting.
@@ -11,5 +11,8 @@ spec:
   horizontalScaling:
     # Specifies the name of the Component.
   - componentName: orchestrator
-    # Specifies the number of total replicas.
-    replicas: 4
+    # Specifies the replica changes for scaling out components
+    scaleIn:
+      # Specifies the replica changes for the component.
+      # add one more replica to current component
+      replicaChanges: 1

examples/orchestrator/scale-out.yaml

@@ -0,0 +1,18 @@
+apiVersion: operations.kubeblocks.io/v1alpha1
+kind: OpsRequest
+metadata:
+  name: orc-scale-out
+  namespace: default
+spec:
+  # Specifies the name of the Cluster resource that this operation is targeting.
+  clusterName: orchestrator-cluster
+  type: HorizontalScaling
+  # Lists HorizontalScaling objects, each specifying scaling requirements for a Component, including desired total replica counts, configurations for new instances, modifications for existing instances, and instance downscaling options
+  horizontalScaling:
+    # Specifies the name of the Component.
+  - componentName: orchestrator
+    # Specifies the replica changes for scaling out components
+    scaleOut:
+      # Specifies the replica changes for the component.
+      # add one more replica to current component
+      replicaChanges: 1

examples/orchestrator/start.yaml

@@ -1,4 +1,4 @@
-apiVersion: apps.kubeblocks.io/v1alpha1
+apiVersion: operations.kubeblocks.io/v1alpha1
 kind: OpsRequest
 metadata:
   name: orchestrator-start

examples/orchestrator/stop.yaml

@@ -1,4 +1,4 @@
-apiVersion: apps.kubeblocks.io/v1alpha1
+apiVersion: operations.kubeblocks.io/v1alpha1
 kind: OpsRequest
 metadata:
   name: orchestrator-stop

examples/orchestrator/verticalscale.yaml

@@ -1,4 +1,4 @@
-apiVersion: apps.kubeblocks.io/v1alpha1
+apiVersion: operations.kubeblocks.io/v1alpha1
 kind: OpsRequest
 metadata:
   name: orchestrator-verticalscaling
@@ -7,7 +7,7 @@ spec:
   # Specifies the name of the Cluster resource that this operation is targeting.
   clusterName: orchestrator-cluster
   type: VerticalScaling
-  # Lists VerticalScaling objects, each specifying a component and its desired compute resources for vertical scaling. 
+  # Lists VerticalScaling objects, each specifying a component and its desired compute resources for vertical scaling.
   verticalScaling:
     # - orchestrator
   - componentName: orchestrator

examples/orchestrator/volumeexpand.yaml

@@ -1,4 +1,4 @@
-apiVersion: apps.kubeblocks.io/v1alpha1
+apiVersion: operations.kubeblocks.io/v1alpha1
 kind: OpsRequest
 metadata:
   name: orchestrator-volumeexpansion
@@ -7,7 +7,7 @@ spec:
   # Specifies the name of the Cluster resource that this operation is targeting.
   clusterName: orchestrator-cluster
   type: VolumeExpansion
-  # Lists VolumeExpansion objects, each specifying a component and its corresponding volumeClaimTemplates that requires storage expansion. 
+  # Lists VolumeExpansion objects, each specifying a component and its corresponding volumeClaimTemplates that requires storage expansion.
   volumeExpansion:
     # Specifies the name of the Component.
   - componentName: orchestrator