docs: merge apecloud mysql and es API docs

docs/user_docs/connect_database/connect-database-in-production-environment.md

@@ -78,8 +78,6 @@ The following command creates a LoadBalancer instance for the database instance,
 
 :::
 
-:::
-
 <Tabs>
 <TabItem value="kbcli" label="kbcli" default>
 

docs/user_docs/handle-an-exception/handle-a-cluster-exception.md

@@ -6,6 +6,9 @@ sidebar_position: 1
 sidebar_label: Handle an exception
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Handle an exception
 
 When an exception occurs during your operation, you can perform the following steps to solve it.
@@ -14,10 +17,26 @@ When an exception occurs during your operation, you can perform the following st
 
 1. Check the cluster status.
 
+   <Tabs>
+
+   <TabItem value="kbcli" label="kbcli" default>
+
+   ```bash
+   kbcli cluster list mycluster
+   ```
+
+   </TabItem>
+
+   <TabItem value="kubectl" label="kubectl">
+
     ```bash
-    kbcli cluster list mycluster
+    kubectl describe cluster mycluster
     ```
 
+   </TabItem>
+
+   </Tabs>
+
 2. Handle the exception according to the status information.
 
     | **Status**       | **Information** |

docs/user_docs/kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md

@@ -17,27 +17,76 @@ This tutorial shows how to create and connect to an ApeCloud MySQL cluster.
 
 ### Before you start
 
-* [Install kbcli](./../../installation/install-with-kbcli/install-kbcli.md).
-* [Install KubeBlocks by kbcli](./../../installation/install-with-kbcli/install-kubeblocks-with-kbcli.md).
-* Make sure the ApeCloud MySQL addon is enabled. If this addon is not enabled, [enable it](./../../installation/install-with-kbcli/install-addons.md#enabledisable-addons) first.
+* [Install kbcli](./../../installation/install-with-kbcli/install-kbcli.md) if you want to create and connect a MySQL cluster by `kbcli`.
+* Install KubeBlocks [by kbcli](./../../installation/install-with-kbcli/install-kubeblocks-with-kbcli.md) or [by Helm](./../../installation/install-with-helm/install-kubeblocks.md).
+* Check whether the ApeCloud MySQL Addon is enabled. The ApeCloud MySQL Addon is enabled by KubeBlocks by default. If you disable it when installing KubeBlocks,[enable it](./../../installation/install-with-kbcli/install-addons.md#enabledisable-addons) first.
+
+  <Tabs>
+
+  <TabItem value="kbcli" label="kbcli" default>
 
   ```bash
   kbcli addon list
   >
-  NAME                           TYPE   STATUS     EXTRAS         AUTO-INSTALL   
+  NAME                           VERSION         PROVIDER    STATUS     AUTO-INSTALL
   ...
-  apecloud-mysql                 Helm   Enabled                   true
+  apecloud-mysql                 0.9.0           apecloud    Enabled    true
   ...
   ```
 
+  </TabItem>
+
+  <TabItem value="kubectl" label="kubectl">
+
+  ```bash
+  kubectl get addons.extensions.kubeblocks.io apecloud-mysql
+  >
+  NAME             TYPE   VERSION   PROVIDER   STATUS    AGE
+  apecloud-mysql   Helm                        Enabled   61m
+  ```
+
+  </TabItem>
+
+  </Tabs>
+
 * View all the database types and versions available for creating a cluster.
 
+  <Tabs>
+
+  <TabItem value="kbcli" label="kbcli" default>
+
   ```bash
   kbcli clusterdefinition list
 
   kbcli clusterversion list
   ```
 
+  </TabItem>
+
+  <TabItem value="kubectl" label="kubectl">
+
+  Make sure the `apecloud-mysql` cluster definition is installed.
+
+  ```bash
+  kubectl get clusterdefinition apecloud-mysql
+  >
+  NAME             TOPOLOGIES   SERVICEREFS   STATUS      AGE
+  apecloud-mysql                              Available   85m
+  ```
+
+  View all available versions for creating a cluster.
+
+  ```bash
+  kubectl get clusterversions -l clusterdefinition.kubeblocks.io/name=apecloud-mysql
+  >
+  NAME                CLUSTER-DEFINITION   STATUS      AGE
+  ac-mysql-8.0.30     apecloud-mysql       Available   85m
+  ```
+
+  </TabItem>
+
+  </Tabs>
+
 * To keep things isolated, create a separate namespace called `demo` throughout this tutorial.
 
   ```bash
@@ -46,49 +95,212 @@ This tutorial shows how to create and connect to an ApeCloud MySQL cluster.
 
 ### Create a cluster
 
-KubeBlocks supports creating two types of MySQL clusters: Standalone and RaftGroup Cluster. Standalone only supports one replica and can be used in scenarios with lower requirements for availability. For scenarios with high availability requirements, it is recommended to create a RaftGroup Cluster, which creates a cluster with three replicas. To ensure high availability, all replicas are distributed on different nodes by default.
+KubeBlocks supports creating two types of ApeCloud MySQL clusters: Standalone and RaftGroup Cluster. Standalone only supports one replica and can be used in scenarios with lower requirements for availability. For scenarios with high availability requirements, it is recommended to create a RaftGroup Cluster, which creates a cluster with three replicas. To ensure high availability, all replicas are distributed on different nodes by default.
 
-Create a Standalone.
+<Tabs>
 
-```bash
-kbcli cluster create <clustername> --cluster-definition apecloud-mysql
-```
+<TabItem value="kbcli" label="kbcli" default>
 
-Create a RaftGroup Cluster.
+1. Create an ApeCloud MySQL cluster.
 
-```bash
-kbcli cluster create <clustername> --cluster-definition apecloud-mysql --set replicas=3 <clustername>
-```
+   Below are some common examples to create a cluster with default settings. If you want to customize your cluster specifications, kbcli provides various options, such as setting cluster version, termination policy, CPU, and memory. You can view these options by adding `--help` or `-h` flag.
+
+   ```bash
+   kbcli cluster create apecloud-mysql --help
 
-If you only have one node for deploying a RaftGroup Cluster, set the `topology-keys` as `null` when creating a RaftGroup Cluster.
+   kbcli cluster create apecloud-mysql -h
+   ```
 
-```bash
-kbcli cluster create <clustername> --cluster-definition apecloud-mysql --set replicas=3 --topology-keys null
-```
+   Create a Standalone.
 
-If you want to specify a cluster version, you can first view the available versions and use `--cluster-version` to specify a version.
+   ```bash
+   kbcli cluster create mycluster --cluster-definition apecloud-mysql --namespace demo
+   ```
 
-```bash
-kbcli clusterversion list
+   Create a RaftGroup Cluster.
 
-kbcli cluster create <clustername> --cluster-definition apecloud-mysql --cluster-version ac-mysql-8.0.30
-```
+   ```bash
+   kbcli cluster create mycluster --cluster-definition apecloud-mysql --set replicas=3 --namespace demo
+   ```
 
-:::note
+   If you only have one node for deploying a RaftGroup Cluster, set the `topology-keys` as `null` when creating a RaftGroup Cluster. But you should note that for a production environment, it is not recommended to deploy all replicas on one node, which may decrease the cluster availability.
 
-* In the production environment, it is not recommended to deploy all replicas on one node, which may decrease the cluster availability.
-* View more flags for creating a cluster to create a cluster with customized specifications.
-
-  ```bash
-  kbcli cluster create --help
-  ```
+   ```bash
+   kbcli cluster create mycluster --cluster-definition apecloud-mysql --set replicas=3 --topology-keys null --namespace demo
+   ```
 
-:::
+2. Verify whether this cluster is created successfully.
+
+   ```bash
+   kbcli cluster list -n demo
+   >
+   NAME        NAMESPACE   CLUSTER-DEFINITION   VERSION           TERMINATION-POLICY   STATUS    CREATED-TIME
+   mycluster   demo        apecloud-mysql       ac-mysql-8.0.30   Delete               Running   Sep 19,2024 16:01 UTC+0800
+   ```
+
+</TabItem>
+
+<TabItem value="kubectl" label="kubectl">
+
+1. Create an ApeCloud MySQL cluster.
+
+   KubeBlocks implements a `Cluster` CRD to define a cluster. Here is an example of creating a RaftGroup Cluster.
+
+   If you only have one node for deploying a RaftGroup Cluster, set `spec.affinity.topologyKeys` as `null`. But for a production environment, it is not recommended to deploy all replicas on one node, which may decrease the cluster availability.
+
+   ```yaml
+   cat <<EOF | kubectl apply -f -
+   apiVersion: apps.kubeblocks.io/v1alpha1
+   kind: Cluster
+   metadata:
+     name: mycluster
+     namespace: demo
+   spec:
+     clusterDefinitionRef: apecloud-mysql
+     clusterVersionRef: ac-mysql-8.0.30
+     terminationPolicy: Delete
+     affinity:
+       podAntiAffinity: Preferred
+       topologyKeys:
+       - kubernetes.io/hostname
+     tolerations:
+       - key: kb-data
+         operator: Equal
+         value: 'true'
+         effect: NoSchedule
+     componentSpecs:
+     - name: mysql
+       componentDefRef: mysql
+       enabledLogs:
+       - error
+       - general
+       - slow
+       disableExporter: true
+       replicas: 3
+       serviceAccountName: kb-acmysql-cluster
+       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
+   EOF
+   ```
+
+   | Field                                 | Definition  |
+   |---------------------------------------|--------------------------------------|
+   | `spec.clusterDefinitionRef`           | It specifies the name of the ClusterDefinition for creating a specific type of cluster.  |
+   | `spec.clusterVersionRef`              | It is the name of the cluster version CRD that defines the cluster version.  |
+   | `spec.terminationPolicy`              | It is the policy of cluster termination. The default value is `Delete`. Valid values are `DoNotTerminate`, `Halt`, `Delete`, `WipeOut`.  <p> - `DoNotTerminate` blocks deletion operation.  </p><p> - `Halt` deletes workload resources such as statefulset and deployment workloads but keep PVCs.  </p><p> - `Delete` is based on Halt and deletes PVCs. </p><p> - `WipeOut` is based on Delete and wipe out all volume snapshots and snapshot data from a backup storage location. </p>|
+   | `spec.affinity`                       | It defines a set of node affinity scheduling rules for the cluster's Pods. This field helps control the placement of Pods on nodes within the cluster.  |
+   | `spec.affinity.podAntiAffinity`       | It specifies the anti-affinity level of Pods within a component. It determines how pods should spread across nodes to improve availability and performance. |
+   | `spec.affinity.topologyKeys`          | It represents the key of node labels used to define the topology domain for Pod anti-affinity and Pod spread constraints.   |
+   | `spec.tolerations`                    | It is an array that specifies tolerations attached to the cluster's Pods, allowing them to be scheduled onto nodes with matching taints.  |
+   | `spec.componentSpecs`                 | It is the list of components that define the cluster components. This field allows customized configuration of each component within a cluster.   |
+   | `spec.componentSpecs.componentDefRef` | It is the name of the component definition that is defined in the cluster definition and you can get the component definition names with `kubectl get clusterdefinition apecloud-mysql -o json \| jq '.spec.componentDefs[].name'`.   |
+   | `spec.componentSpecs.name`            | It specifies the name of the component.     |
+   | `spec.componentSpecs.disableExporter` | It defines whether the monitoring function is enabled. |
+   | `spec.componentSpecs.replicas`        | It specifies the number of replicas of the component.  |
+   | `spec.componentSpecs.resources`       | It specifies the resource requirements of the component.  |
+
+   KubeBlocks operator watches for the `Cluster` CRD and creates the cluster and all dependent resources. You can get all the resources created by the cluster by running the command below.
+
+   ```bash
+   kubectl get all,secret,rolebinding,serviceaccount -l app.kubernetes.io/instance=mycluster -n demo
+   ```
+
+   Run the following command to view the details of the created ApeCloud MySQL cluster:
+
+   ```bash
+   kubectl get cluster mycluster -n demo -o yaml
+   ```
+
+2. Verify whether this cluster is created successfully.
+
+   ```bash
+   kubectl get cluster mycluster -n demo
+   >
+   NAME        CLUSTER-DEFINITION   VERSION           TERMINATION-POLICY   STATUS    AGE
+   mycluster   apecloud-mysql       ac-mysql-8.0.30   Delete               Running   12m
+   ```
+
+</TabItem>
+
+</Tabs>
 
 ## Connect to an ApeCloud MySQL Cluster
 
+<Tabs>
+
+<TabItem value="kbcli" label="kbcli" default>
+
 ```bash
-kbcli cluster connect <clustername>  --namespace <name>
+kbcli cluster connect mycluster  -n demo
 ```
 
+</TabItem>
+
+<TabItem value="kubectl" label="kubectl">
+
+You can use `kubectl exec` to exec into a Pod and connect to a database.
+
+KubeBlocks operator creates a new Secret called `mycluster-conn-credential` to store the connection credential of the ApeCloud MySQL cluster. This secret contains the following keys:
+
+* `username`: the root username of the MySQL cluster.
+* `password`: the password of the root user.
+* `port`: the port of the MySQL cluster.
+* `host`: the host of the MySQL cluster.
+* `endpoint`: the endpoint of the MySQL cluster and it is the same as `host:port`.
+
+1. Run the command below to get the `username` and `password` for the `kubectl exec` command.
+
+   ```bash
+   kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d
+   >
+   root
+
+   kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d
+   >
+   2gvztbvz
+   ```
+
+2. Exec into the Pod `mycluster-mysql-0` and connect to the database using username and password.
+
+   ```bash
+   kubectl exec -ti -n demo mycluster-mysql-0 -- bash
+
+   mysql -uroot -p2gvztbvz
+   ```
+
+</TabItem>
+
+<TabItem value="port-forward" label="port-forward">
+
+You can also port forward the service to connect to a database from your local machine.
+
+1. Run the following command to port forward the service.
+
+   ```bash
+   kubectl port-forward svc/mycluster-mysql 3306:3306 -n demo
+   ```
+
+2. Open a new terminal and run the following command to connect to the database.
+
+   ```bash
+   mysql -uroot -p2gvztbvz
+   ```
+
+</TabItem>
+
+</Tabs>
+
 For the detailed database connection guide, refer to [Connect database](./../../connect_database/overview-of-database-connection.md).