chore: add examples (#7199)

Co-authored-by: huangzhangshu <huangzhangshu@apecloud.com>

examples/apecloud-mysql/README.md

@@ -0,0 +1,174 @@
+# Apecloud-mysql
+
+ApeCloud MySQL is a database that is compatible with MySQL syntax and achieves high availability through the utilization of the RAFT consensus protocol. This example shows how it can be managed in Kubernetes with KubeBlocks.
+
+## 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. 
+
+Also, this example requires kubeblocks installed and running. Here is the steps to install kubeblocks, please replace "0.9.0" with the version you want to use.
+```bash
+# Create dependent CRDs
+kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.0/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/v0.9.0/kubeblocks_crds.yaml
+
+# 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
+
+# Install KubeBlocks
+helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version="0.9.0"
+```
+
+
+## Examples
+
+### [Create](cluster.yaml) 
+Create an apecloud-mysql cluster with specified cluster definition 
+```bash
+kubectl apply -f examples/apecloud-mysql/cluster.yaml
+```
+Starting from kubeblocks 0.9.0, we introduced a more flexible cluster creation method based on components, allowing customization of cluster topology, functionalities and scale according to specific requirements.
+```bash
+kubectl apply -f examples/apecloud-mysql/cluster-cmpd.yaml
+```
+### [Horizontal scaling](horizontalscale.yaml)
+Horizontal scaling out or in specified components replicas in the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/horizontalscale.yaml
+```
+
+### [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/apecloud-mysql/verticalscale.yaml
+```
+
+### [Expand volume](volumeexpand.yaml)
+Increase size of volume storage with the specified components in the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/volumeexpand.yaml
+```
+
+### [Restart](restart.yaml)
+Restart the specified components in the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/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/apecloud-mysql/stop.yaml
+```
+
+### [Start](start.yaml)
+Start the stopped cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/start.yaml
+```
+
+### [Switchover](switchover.yaml)
+Switchover a non-primary or non-leader instance as the new primary or leader of the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/switchover.yaml
+```
+
+### [Switchover-specified-instance](switchover-specified-instance.yaml)
+Switchover a specified instance as the new primary or leader of the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/switchover-specified-instance.yaml
+```
+
+### [Configure](configure.yaml)
+Configure parameters with the specified components in the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/configure.yaml
+```
+
+### [BackupRepo](backuprepo.yaml)
+BackupRepo is the storage repository for backup data, using the full backup and restore function of KubeBlocks relies on BackupRepo
+```bash
+# Create a secret to save the access key
+kubectl create secret generic <storage-provider>-credential-for-backuprepo\
+  --from-literal=accessKeyId=<ACCESS KEY> \
+  --from-literal=secretAccessKey=<SECRET KEY> \
+  -n kb-system 
+
+kubectl apply -f examples/apecloud-mysql/backuprepo.yaml
+```
+
+### [Backup](backup.yaml)
+Create a backup for the cluster
+```bash
+kubectl apply -f examples/apecloud-mysql/backup.yaml
+```
+
+### [Restore](restore.yaml)
+Restore a new cluster from backup
+```bash
+# Get backup connection password
+kubectl get backup acmysql-cluster-backup -ojsonpath='{.metadata.annotations.dataprotection\.kubeblocks\.io\/connection-password}' -n default
+
+kubectl apply -f examples/apecloud-mysql/restore.yaml
+```
+
+### Expose
+Expose a cluster with a new endpoint
+#### [Enable](expose-enable.yaml)
+```bash
+kubectl apply -f examples/apecloud-mysql/expose-enable.yaml
+```
+#### [Disable](expose-disable.yaml)
+```bash
+kubectl apply -f examples/apecloud-mysql/expose-disable.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 acmysql-cluster -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"
+
+kubectl delete cluster acmysql-cluster
+```
+
+## SmartEngine
+
+SmartEngine is an OLTP storage engine based on LSM-Tree architecture and supports complete ACID transaction constraints.
+
+### [Enable](smartengine-enable.yaml)
+
+```bash
+kubectl apply -f examples/apecloud-mysql/smartengine-enable.yaml
+```
+
+### [Disable](smartengine-disable.yaml)
+
+```bash
+kubectl apply -f examples/apecloud-mysql/smartengine-disable.yaml
+```
+
+## ApeCloud MySQL Proxy
+
+ApeCloud MySQL Proxy is a database proxy designed to be highly compatible with MySQL.
+It supports the MySQL wire protocol, read-write splitting without stale reads, connection pooling, and transparent failover.
+
+### [Create Proxy](cluster-proxy.yaml)
+```bash
+kubectl apply -f examples/apecloud-mysql/cluster-proxy.yaml
+```
+
+### [Configure Vtgate](configure-vtgate.yaml)
+```bash
+kubectl apply -f examples/apecloud-mysql/configure-vtgate.yaml
+```
+
+### [Configure Vttablet](configure-vttablet.yaml)
+```bash
+kubectl apply -f examples/apecloud-mysql/configure-vttablet.yaml
+```

examples/apecloud-mysql/backup.yaml

@@ -0,0 +1,16 @@
+apiVersion: dataprotection.kubeblocks.io/v1alpha1
+kind: Backup
+metadata:
+  name: acmysql-cluster-backup
+  namespace: default
+spec:
+  # Specifies the backup method name that is defined in the backup policy.
+  # - xtrabackup
+  # - volume-snapshot
+  backupMethod: xtrabackup
+  # Specifies the backup policy to be applied for this backup.
+  backupPolicyName: acmysql-cluster-mysql-backup-policy
+  # Determines whether the backup contents stored in the backup repository should be deleted when the backup custom resource(CR) is deleted. Supported values are `Retain` and `Delete`.
+  # - `Retain` means that the backup content and its physical snapshot on backup repository are kept.
+  # - `Delete` means that the backup content and its physical snapshot on backup repository are deleted.
+  deletionPolicy: Delete

examples/apecloud-mysql/backuprepo.yaml

@@ -0,0 +1,36 @@
+apiVersion: dataprotection.kubeblocks.io/v1alpha1
+kind: BackupRepo
+metadata:
+  name: s3-repo
+  annotations:
+    dataprotection.kubeblocks.io/is-default-repo: 'true'
+spec:
+  # Specifies the name of the `StorageProvider` used by this backup repository.
+  # Currently, KubeBlocks supports configuring various object storage services as backup repositories
+  # - s3 (Amazon Simple Storage Service)
+  # - oss (Alibaba Cloud Object Storage Service)
+  # - cos (Tencent Cloud Object Storage)
+  # - gcs (Google Cloud Storage)
+  # - obs (Huawei Cloud Object Storage)
+  # - minio, and other S3-compatible services.
+  storageProviderRef: s3
+  # Specifies the access method of the backup repository.
+  # - Tool
+  # - Mount
+  accessMethod: Tool
+  # Specifies reclaim policy of the PV created by this backup repository.
+  pvReclaimPolicy: Retain
+  # Specifies the capacity of the PVC created by this backup repository.
+  volumeCapacity: 100Gi
+  # Stores the non-secret configuration parameters for the `StorageProvider`.
+  config:
+    bucket: <storage-provider-bucket-name>
+    endpoint: ''
+    mountOptions: --memory-limit 1000 --dir-mode 0777 --file-mode 0666
+    region: <storage-provider-region-name>
+  # References to the secret that holds the credentials for the `StorageProvider`.
+  credential:
+    # name is unique within a namespace to reference a secret resource.
+    name: s3-credential-for-backuprepo
+    # namespace defines the space within which the secret name must be unique.
+    namespace: kb-system

examples/apecloud-mysql/cluster-cmpd.yaml

@@ -0,0 +1,58 @@
+apiVersion: apps.kubeblocks.io/v1alpha1
+kind: Cluster
+metadata:
+  name: acmysql-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. 
+  componentSpecs:
+    # Specifies the name of the Component. This name is also part of the Service DNS name and must comply with the IANA service naming rule. 
+    - name: mysql
+    # References the name of a ComponentDefinition. The ComponentDefinition specifies the behavior and characteristics of the Component. If both `componentDefRef` and `componentDef` are provided, the `componentDef` will take precedence over `componentDefRef`.
+    componentDef: apecloud-mysql
+    # Specifies a group of affinity scheduling rules for the Component. It allows users to control how the Component's Pods are scheduled onto nodes in the cluster.
+    affinity:
+      podAntiAffinity: Preferred
+      topologyKeys:
+      - kubernetes.io/hostname
+      tenancy: SharedNode
+    # Allows the Component to be scheduled onto nodes with matching taints. 
+    tolerations:
+    - key: kb-data
+      operator: Equal
+      value: 'true'
+      effect: NoSchedule
+    # Specifies which types of logs should be collected for the Cluster. 
+    enabledLogs:
+    - error
+    - general
+    - slow
+    # Determines whether the metrics exporter needs to be published to the service endpoint.  
+    monitorEnabled: false
+    # Specifies the name of the ServiceAccount required by the running Component.   
+    serviceAccountName: kb-acmysql-cluster
+    # Each component supports running multiple replicas to provide high availability and persistence. This field can be used to specify the desired number of replicas.
+    replicas: 2
+    # Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component's containers.
+    resources:
+      limits:
+        cpu: '0.5'
+        memory: 0.5Gi
+      requests:
+        cpu: '0.5'
+        memory: 0.5Gi
+    # Specifies a list of PersistentVolumeClaim templates that define the storage requirements for the Component. 
+    volumeClaimTemplates:
+    - name: data
+      spec:
+        accessModes:
+        - ReadWriteOnce
+        resources:
+          requests:
+            storage: 20Gi

examples/apecloud-mysql/cluster-proxy.yaml

@@ -0,0 +1,95 @@
+apiVersion: apps.kubeblocks.io/v1alpha1
+kind: Cluster
+metadata:
+  name: acmysql-cluster
+  namespace: default
+spec:
+  # Specifies the name of the ClusterDefinition to use when creating a Cluster.
+  clusterDefinitionRef: apecloud-mysql
+  # Refers to the ClusterVersion name. Deprecated since v0.9, use ComponentVersion instead. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
+  clusterVersionRef: ac-mysql-8.0.30
+  # 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
+  # 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.
+  affinity:
+   # Specifies the anti-affinity level of Pods within a Component. It determines how pods should be spread across nodes to improve availability and performance.
+    podAntiAffinity: Preferred
+    # Represents the key of node labels used to define the topology domain for Pod anti-affinity and Pod spread constraints. 
+    topologyKeys:
+    - kubernetes.io/hostname
+    # Determines the level of resource isolation between Pods. It can have the following values: `SharedNode` and `DedicatedNode`. 
+    # - SharedNode: Allow that multiple Pods may share the same node, which is the default behavior of K8s. 
+    # - DedicatedNode: Each Pod runs on a dedicated node, ensuring that no two Pods share the same node. 
+    tenancy: SharedNode
+  # An array that specifies tolerations attached to the Cluster's Pods, allowing them to be scheduled onto nodes with matching taints.
+  tolerations:
+    - key: kb-data
+      operator: Equal
+      value: "true"
+      effect: NoSchedule
+  # 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: mysql
+    componentDefRef: mysql
+    enabledLogs:
+    - error
+    - general
+    - slow
+    monitorEnabled: false
+    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
+  - componentDefRef: vtcontroller
+    enabledLogs:
+    - error
+    - warning
+    - info
+    monitorEnabled: false
+    name: vtcontroller
+    replicas: 1
+    resources:
+      limits:
+        cpu: '0.5'
+        memory: 0.5Gi
+    volumeClaimTemplates:
+    - name: data
+      spec:
+        accessModes:
+        - ReadWriteOnce
+        resources:
+          requests:
+            storage: 20Gi
+  - componentDefRef: vtgate
+    enabledLogs:
+    - error
+    - warning
+    - info
+    - queryLog
+    monitorEnabled: false
+    name: vtgate
+    replicas: 1
+    resources:
+      limits:
+        cpu: '0.5'
+        memory: 0.5Gi
+      requests:
+        cpu: '0.5'
+        memory: 0.5Gi