diff --git a/apis/apps/v1/cluster_types.go b/apis/apps/v1/cluster_types.go index fe8b5eb5236..93b70ba7074 100644 --- a/apis/apps/v1/cluster_types.go +++ b/apis/apps/v1/cluster_types.go @@ -33,8 +33,7 @@ import ( // +kubebuilder:subresource:status // +kubebuilder:storageversion // +kubebuilder:resource:categories={kubeblocks,all} -// +kubebuilder:printcolumn:name="CLUSTER-DEFINITION",type="string",JSONPath=".spec.clusterDefinitionRef",description="ClusterDefinition referenced by cluster." -// +kubebuilder:printcolumn:name="VERSION",type="string",JSONPath=".spec.clusterVersionRef",description="Cluster Application Version." +// +kubebuilder:printcolumn:name="CLUSTER-DEFINITION",type="string",JSONPath=".spec.clusterDef",description="ClusterDefinition referenced by cluster." // +kubebuilder:printcolumn:name="TERMINATION-POLICY",type="string",JSONPath=".spec.terminationPolicy",description="Cluster termination policy." // +kubebuilder:printcolumn:name="STATUS",type="string",JSONPath=".status.phase",description="Cluster Status." // +kubebuilder:printcolumn:name="AGE",type="date",JSONPath=".metadata.creationTimestamp" diff --git a/config/crd/bases/apps.kubeblocks.io_clusters.yaml b/config/crd/bases/apps.kubeblocks.io_clusters.yaml index f6ff2897e8e..a0078250195 100644 --- a/config/crd/bases/apps.kubeblocks.io_clusters.yaml +++ b/config/crd/bases/apps.kubeblocks.io_clusters.yaml @@ -20,13 +20,9 @@ spec: versions: - additionalPrinterColumns: - description: ClusterDefinition referenced by cluster. - jsonPath: .spec.clusterDefinitionRef + jsonPath: .spec.clusterDef name: CLUSTER-DEFINITION type: string - - description: Cluster Application Version. - jsonPath: .spec.clusterVersionRef - name: VERSION - type: string - description: Cluster termination policy. jsonPath: .spec.terminationPolicy name: TERMINATION-POLICY diff --git a/controllers/apps/clusterdefinition_controller.go b/controllers/apps/clusterdefinition_controller.go index d01c55b85e2..c44b7bdce7c 100644 --- a/controllers/apps/clusterdefinition_controller.go +++ b/controllers/apps/clusterdefinition_controller.go @@ -34,7 +34,6 @@ import ( "sigs.k8s.io/controller-runtime/pkg/log" appsv1 "github.com/apecloud/kubeblocks/apis/apps/v1" - appsconfig "github.com/apecloud/kubeblocks/controllers/apps/configuration" "github.com/apecloud/kubeblocks/pkg/constant" "github.com/apecloud/kubeblocks/pkg/controller/component" intctrlutil "github.com/apecloud/kubeblocks/pkg/controllerutil" @@ -117,11 +116,8 @@ func (r *ClusterDefinitionReconciler) deletionHandler(rctx intctrlutil.RequestCt } func (r *ClusterDefinitionReconciler) deleteExternalResources(rctx intctrlutil.RequestCtx, clusterDef *appsv1.ClusterDefinition) error { - // delete any external resources associated with the cronJob - // - // Ensure that delete implementation is idempotent and safe to invoke - // multiple times for same object. - return appsconfig.DeleteConfigMapFinalizer(r.Client, rctx, clusterDef) + // delete any external resources associated with the cluster definition CR. + return nil } func (r *ClusterDefinitionReconciler) available(rctx intctrlutil.RequestCtx, clusterDef *appsv1.ClusterDefinition) error { diff --git a/deploy/helm/crds/apps.kubeblocks.io_clusters.yaml b/deploy/helm/crds/apps.kubeblocks.io_clusters.yaml index f6ff2897e8e..a0078250195 100644 --- a/deploy/helm/crds/apps.kubeblocks.io_clusters.yaml +++ b/deploy/helm/crds/apps.kubeblocks.io_clusters.yaml @@ -20,13 +20,9 @@ spec: versions: - additionalPrinterColumns: - description: ClusterDefinition referenced by cluster. - jsonPath: .spec.clusterDefinitionRef + jsonPath: .spec.clusterDef name: CLUSTER-DEFINITION type: string - - description: Cluster Application Version. - jsonPath: .spec.clusterVersionRef - name: VERSION - type: string - description: Cluster termination policy. jsonPath: .spec.terminationPolicy name: TERMINATION-POLICY diff --git a/deploy/helm/templates/_dataprotection.tpl b/deploy/helm/templates/_dataprotection.tpl index d468dd1d2a1..60749b9ce82 100644 --- a/deploy/helm/templates/_dataprotection.tpl +++ b/deploy/helm/templates/_dataprotection.tpl @@ -39,11 +39,13 @@ Render the secret key reference of the encryptionKey. name: {{ include "kubeblocks.fullname" . }}-secret key: dataProtectionEncryptionKey {{- else -}} - {{- $secret := lookup "v1" "Secret" .Release.Namespace $ref.name -}} - {{- if not $secret -}} - {{- fail (printf "Invalid value \".Values.dataProtection.encryptionKeySecretKeyRef\", secret %q is not found from the namespace %q." $ref.name .Release.Namespace) -}} - {{- else if not (hasKey $secret.data $ref.key) -}} - {{- fail (printf "Invalid value \".Values.dataProtection.encryptionKeySecretKeyRef\", secret %q doesn't have key %q." $ref.name $ref.key) -}} + {{- if not .Values.dataProtection.encryptionKeySecretKeyRef.skipValidation -}} + {{- $secret := lookup "v1" "Secret" .Release.Namespace $ref.name -}} + {{- if not $secret -}} + {{- fail (printf "Invalid value \".Values.dataProtection.encryptionKeySecretKeyRef\", secret %q is not found from the namespace %q." $ref.name .Release.Namespace) -}} + {{- else if not (hasKey $secret.data $ref.key) -}} + {{- fail (printf "Invalid value \".Values.dataProtection.encryptionKeySecretKeyRef\", secret %q doesn't have key %q." $ref.name $ref.key) -}} + {{- end -}} {{- end -}} name: {{ $ref.name }} key: {{ $ref.key }} diff --git a/deploy/helm/values.yaml b/deploy/helm/values.yaml index e33791e5db1..d7e2b7f92d5 100644 --- a/deploy/helm/values.yaml +++ b/deploy/helm/values.yaml @@ -342,6 +342,7 @@ dataProtection: encryptionKeySecretKeyRef: name: "" key: "" + skipValidation: false enableBackupEncryption: false backupEncryptionAlgorithm: "" gcFrequencySeconds: 3600 @@ -2011,4 +2012,4 @@ vmagent: crd: enabled: true -userAgent: kubeblocks \ No newline at end of file +userAgent: kubeblocks diff --git a/docs/user_docs/installation/install-with-helm/_category_.yml b/docs/user_docs/installation/install-with-helm/_category_.yml index f721a4a8977..4803e6977f9 100644 --- a/docs/user_docs/installation/install-with-helm/_category_.yml +++ b/docs/user_docs/installation/install-with-helm/_category_.yml @@ -1,4 +1,4 @@ -position: 2 +position: 3 label: Install with helm collapsible: true collapsed: true \ No newline at end of file diff --git a/docs/user_docs/installation/install-with-helm/install-addons.md b/docs/user_docs/installation/install-with-helm/install-addons.md index 790058b85d5..a42f9851ce8 100644 --- a/docs/user_docs/installation/install-with-helm/install-addons.md +++ b/docs/user_docs/installation/install-with-helm/install-addons.md @@ -6,7 +6,13 @@ sidebar_position: 3 sidebar_label: Install Addons --- -# Install addons +# Install Addons + +With the release of KubeBlocks v0.8.0, Addons are decoupled from KubeBlocks and some Addons are not installed by default. If you want to use these Addons, install Addons first by index. Or if you uninstalled some Addons, you can follow the steps in this tutorial to install them again. + +This tutorial takes etcd as an example. You can replace etcd with the Addon you need. + +The official index repo is [KubeBlocks index](https://github.com/apecloud/block-index). The code of all Addons is maintained in the [KubeBlocks Addon repo](https://github.com/apecloud/kubeblocks-addons). 1. (Optional) Add the KubeBlocks repo. If you install KubeBlocks with Helm, just run `helm repo update`. @@ -15,32 +21,32 @@ sidebar_label: Install Addons helm repo update ``` -2. View the addon versions. +2. View the Addon versions. ```bash - helm search repo kubeblocks/mariadb --devel --versions + helm search repo kubeblocks/etcd --devel --versions ``` -3. Install the addon (take mariadb as example). +3. Install the Addon (take etcd as example). Specify a version with `--version`. ```bash - helm install mariadb kubeblocks/mariadb --namespace kb-system --create-namespace --version 0.9.0 + helm install etcd kubeblocks/etcd --namespace kb-system --create-namespace --version x.y.z ``` -4. Verify whether this addon is installed. +4. Verify whether this Addon is installed. - The STATUS is `deployed` and this addon is installed successfully. + The STATUS is `deployed` and this Addon is installed successfully. ```bash helm list -A > - NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION + NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION ...... - mariadb kb-system 1 2024-05-08 17:41:29.112721 +0800 CST deployed mariadb-0.9.0 10.6.15 + etcd kb-system 1 2024-10-25 07:18:35.294326176 +0000 UTC deployed etcd-0.9.0 v3.5.6 ``` -5. (Optional) You can run the command below to disable the addon. +5. (Optional) You can run the command below to disable the Addon. ```bash - helm uninstall mariadb --namespace kb-system + helm uninstall etcd --namespace kb-system ``` diff --git a/docs/user_docs/installation/install-with-helm/install-kubeblocks.md b/docs/user_docs/installation/install-with-helm/install-kubeblocks.md index 2accd4c7ec4..e76fc51b674 100644 --- a/docs/user_docs/installation/install-with-helm/install-kubeblocks.md +++ b/docs/user_docs/installation/install-with-helm/install-kubeblocks.md @@ -13,6 +13,8 @@ import TabItem from '@theme/TabItem'; KubeBlocks is Kubernetes-native, you can use Helm or kubectl with a YAML file to install it. +To try out KubeBlocks on your local host, you can use the [Playground](./../../try-out-on-playground/try-kubeblocks-on-your-laptop.md) or [create a local Kubernetes test cluster first](./../prerequisite/prepare-a-local-k8s-cluster.md) and then follow the steps in this tutorial to install KubeBlocks. + :::note If you install KubeBlocks with Helm, to uninstall it, you have to use Helm too. @@ -60,15 +62,14 @@ Use Helm and follow the steps below to install KubeBlocks. 1. Create dependent CRDs. Specify the version you want to install. ```bash - kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/vx.x.x/kubeblocks_crds.yaml + kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/vx.y.z/kubeblocks_crds.yaml ``` You can view all versions of kubeblocks, including alpha and beta releases, on the [kubeblocks releases list](https://github.com/apecloud/kubeblocks/releases). To get stable releases, use this command: ```bash - curl -s "https://api.github.com/repos/apecloud/kubeblocks/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V + curl -s "https://api.github.com/repos/apecloud/kubeblocks/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V -r ``` - 2. Add the KubeBlocks Helm repo. @@ -97,7 +98,7 @@ Use Helm and follow the steps below to install KubeBlocks. 2. Specify a version with `--version` and run the command below. ```bash - helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version="x.x.x" + helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version="x.y.z" ``` :::note @@ -110,13 +111,14 @@ Use Helm and follow the steps below to install KubeBlocks. -KubeBlocks can be installed like any other resource in Kubernetes, through a YAML manifest applied via `kubectl`. +Like any other resource in Kubernetes, KubeBlocks can be installed through a YAML manifest applied via `kubectl`. -Run the following command to install the latest operator manifest for this minor release: +1. Copy the URL of the `kubeblocks.yaml file` for the version you need from the Assets on the [KubeBlocks Release page](https://github.com/apecloud/kubeblocks/releases). +2. Replace the YAML file URL in the command below and run this command to install KubeBlocks. - ```bash - kubectl create -f \address.yaml - ``` + ```bash + kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/vx.y.x/kubeblocks.yaml + ``` @@ -135,14 +137,15 @@ kubectl -n kb-system get pods If the KubeBlocks Workloads are all ready, KubeBlocks has been installed successfully. ```bash -NAME READY STATUS AGE -kb-addon-snapshot-controller-7b447684d4-q86zf 1/1 Running 33d -kb-addon-csi-hostpath-driver-0 8/8 Running 33d -kb-addon-grafana-54b9cbf65d-k8522 3/3 Running 33d -kb-addon-apecloud-otel-collector-j4thb 1/1 Running 33d -kubeblocks-5b5648bfd9-8jpvv 1/1 Running 33d -kubeblocks-dataprotection-f54c9486c-2nfmr 1/1 Running 33d -kb-addon-alertmanager-webhook-adaptor-76b87f9df8-xb74g 2/2 Running 33d -kb-addon-prometheus-server-0 2/2 Running 33d -kb-addon-prometheus-alertmanager-0 2/2 Running 33d +NAME READY STATUS RESTARTS AGE +alertmanager-webhook-adaptor-8dfc4878d-svzrc 2/2 Running 0 3m56s +grafana-77dfd6959-4gnhp 1/1 Running 0 3m56s +kb-addon-snapshot-controller-546f84b78d-8rjs4 1/1 Running 0 3m56s +kubeblocks-7cf7745685-ddlwk 1/1 Running 0 4m39s +kubeblocks-dataprotection-95fbc79cc-b544l 1/1 Running 0 4m39s +prometheus-alertmanager-5c9fc88996-qltrk 2/2 Running 0 3m56s +prometheus-kube-state-metrics-5dbbf757f5-db9v6 1/1 Running 0 3m56s +prometheus-node-exporter-r6kvl 1/1 Running 0 3m56s +prometheus-pushgateway-8555888c7d-xkgfc 1/1 Running 0 3m56s +prometheus-server-5759b94fc8-686xp 2/2 Running 0 3m56s ``` diff --git a/docs/user_docs/installation/install-with-helm/uninstall-kubeblocks.md b/docs/user_docs/installation/install-with-helm/uninstall-kubeblocks.md index f4994831933..78ff4f42ee0 100644 --- a/docs/user_docs/installation/install-with-helm/uninstall-kubeblocks.md +++ b/docs/user_docs/installation/install-with-helm/uninstall-kubeblocks.md @@ -43,10 +43,10 @@ kubectl get crd -o name | grep kubeblocks.io | xargs kubectl delete -You can generate YAMLs from the KubeBlocks chart and uninstall using `kubectl`. +You can generate YAMLs from the KubeBlocks chart and uninstall using `kubectl`. Use `--version x.y.z` to specify a version and make sure the uninstalled version is the same as the installed one. ```bash -helm template kubeblocks kubeblocks/kubeblocks --namespace kb-system | kubectl delete -f - +helm template kubeblocks kubeblocks/kubeblocks --namespace kb-system --version x.y.z | kubectl delete -f - ``` diff --git a/docs/user_docs/installation/install-with-kbcli/_category_.yml b/docs/user_docs/installation/install-with-kbcli/_category_.yml index cabf4a6c503..4e70f760f93 100644 --- a/docs/user_docs/installation/install-with-kbcli/_category_.yml +++ b/docs/user_docs/installation/install-with-kbcli/_category_.yml @@ -1,4 +1,4 @@ -position: 1 +position: 2 label: Install with kbcli collapsible: true collapsed: true \ No newline at end of file diff --git a/docs/user_docs/installation/install-with-kbcli/install-addons.md b/docs/user_docs/installation/install-with-kbcli/install-addons.md index 5770735cc21..ad70dafa4ab 100644 --- a/docs/user_docs/installation/install-with-kbcli/install-addons.md +++ b/docs/user_docs/installation/install-with-kbcli/install-addons.md @@ -8,11 +8,13 @@ sidebar_label: Install Addons # Install Addons -## Use the index to install an addon +## Use the index to install an Addon -With the release of KubeBlocks v0.8.0, addons are decoupled from KubeBlocks and some addons are not installed by default. If you want to use these addons, add addons first by index. +With the release of KubeBlocks v0.8.0, Addons are decoupled from KubeBlocks and some Addons are not installed by default. If you want to use these Addons, install Addons first by index. Or if you uninstalled some Addons, you can follow the steps in this tutorial to install them again. -The official index repo is [KubeBlocks index](https://github.com/apecloud/block-index). The code of all addons is maintained in the [KubeBlocks addon repo](https://github.com/apecloud/kubeblocks-addons). +This tutorial takes etcd as an example. You can replace etcd with the Addon you need. + +The official index repo is [KubeBlocks index](https://github.com/apecloud/block-index). The code of all Addons is maintained in the [KubeBlocks Addon repo](https://github.com/apecloud/kubeblocks-addons). 1. View the index. @@ -37,49 +39,65 @@ The official index repo is [KubeBlocks index](https://github.com/apecloud/block- kbcli addon index update kubeblocks ``` -2. (Optional) Search whether the addon exists in the index. +2. (Optional) Search whether the Addon exists in the index. ```bash - kbcli addon search mariadb + kbcli addon search etcd > - ADDON VERSION INDEX - mariadb 0.7.0 kubeblocks + ADDON VERSION INDEX + etcd 0.7.0 kubeblocks + etcd 0.8.0 kubeblocks + etcd 0.9.0 kubeblocks ``` -3. Install the addon. +3. Install the Addon. - If there are multiple index sources and versions for an addon, you can specify them by adding flags. The system installs the latest version in the `kubeblocks` index by default. + If there are multiple index sources and versions for an Addon, you can specify an index by `--index` and a version by `--version`. The system installs the latest version in the `kubeblocks` index by default. ```bash - kbcli addon install mariadb --index kubeblocks --version 0.7.0 + kbcli addon install etcd --index kubeblocks --version x.y.z ``` **What's next** - After the addon is installed, you can list and enable it. + After the Addon is installed, you can list and enable it. -## List addons +## List Addons -To list supported addons, run `kbcli addon list` command. +To list supported Addons, run `kbcli addon list` command. -## Enable/Disable addons +## Enable/Disable Addons -To manually enable or disable addons, follow the steps below. +To manually enable or disable Addons, follow the steps below. ***Steps:*** -1. To enable an addon, use `kbcli addon enable`. +1. To enable an Addon, use `kbcli addon enable`. ***Example*** ```bash - kbcli addon enable snapshot-controller + kbcli addon enable etcd ``` - To disable an addon, use `kbcli addon disable`. + To disable an Addon, use `kbcli addon disable`. -2. List the addons again to check whether it is enabled. +2. List the Addons again to check whether it is enabled. ```bash kbcli addon list ``` + +## Uninstall Addons + +You can also uninstall the Addons. If you have created a related cluster, delete the cluster first. + +```bash +kbcli cluster delete +``` + +Uninstall an Addon. + +```bash +kbcli addon uninstall etcd +``` diff --git a/docs/user_docs/installation/install-with-kbcli/install-kbcli.md b/docs/user_docs/installation/install-with-kbcli/install-kbcli.md index f32ffb76976..ffda34b30b6 100644 --- a/docs/user_docs/installation/install-with-kbcli/install-kbcli.md +++ b/docs/user_docs/installation/install-with-kbcli/install-kbcli.md @@ -40,13 +40,13 @@ You can install kbcli with `curl` or `brew`. 2. Specify a version with `-s` and run the command below. ```bash - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.x.x + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.y.z ``` You can view all versions of kbcli, including alpha and beta releases, on the [kbcli releases list](https://github.com/apecloud/kbcli/releases). To get stable releases, use this command: ```bash - curl -s "https://api.github.com/repos/apecloud/kbcli/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V + curl -s "https://api.github.com/repos/apecloud/kbcli/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V -r ``` :::note @@ -86,7 +86,7 @@ You can install kbcli with `curl` or `brew`. brew search kbcli # Specify a version - brew install kbcli@x.x.x + brew install kbcli@x.y.z ``` 3. Verify that kbcli is successfully installed. diff --git a/docs/user_docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md b/docs/user_docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md index 0022b8f596b..9e42f356ddd 100644 --- a/docs/user_docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md +++ b/docs/user_docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md @@ -10,6 +10,8 @@ sidebar_label: Install KubeBlocks The quickest way to try out KubeBlocks is to create a new Kubernetes cluster and install KubeBlocks using the playground. However, production environments are more complex, with applications running in different namespaces and with resource or permission limitations. This document explains how to deploy KubeBlocks on an existing Kubernetes cluster. +To try out KubeBlocks on your local host, you can use the [Playground](./../../try-out-on-playground/try-kubeblocks-on-your-laptop.md) or [create a local Kubernetes test cluster first](./../prerequisite/prepare-a-local-k8s-cluster.md) and then follow the steps in this tutorial to install KubeBlocks. + ## Environment preparation Prepare an accessible Kubernetes cluster with the version 1.22 or above, and this cluster should meet the following requirements. @@ -66,7 +68,7 @@ If you want to install KubeBlocks with a specified version, follow the steps bel 2. Specify a version with `--version` and run the command below. ```bash - kbcli kubeblocks install --version=x.x.x + kbcli kubeblocks install --version=x.y.z ``` :::note @@ -89,7 +91,7 @@ kbcli kubeblocks status If the KubeBlocks Workloads are all ready, KubeBlocks has been installed successfully. ```bash -KubeBlocks is deployed in namespace: kb-system,version: x.x.x +KubeBlocks is deployed in namespace: kb-system,version: x.y.z > KubeBlocks Workloads: NAMESPACE KIND NAME READY PODS CPU(CORES) MEMORY(BYTES) CREATED-AT diff --git a/docs/user_docs/installation/prerequisite/_category_.yml b/docs/user_docs/installation/prerequisite/_category_.yml new file mode 100644 index 00000000000..1b92619b1c5 --- /dev/null +++ b/docs/user_docs/installation/prerequisite/_category_.yml @@ -0,0 +1,4 @@ +position: 1 +label: Prerequisite for Local Env +collapsible: true +collapsed: true \ No newline at end of file diff --git a/docs/user_docs/installation/prerequisite/prepare-a-local-k8s-cluster.md b/docs/user_docs/installation/prerequisite/prepare-a-local-k8s-cluster.md new file mode 100644 index 00000000000..5c0193ce9b5 --- /dev/null +++ b/docs/user_docs/installation/prerequisite/prepare-a-local-k8s-cluster.md @@ -0,0 +1,257 @@ +--- +title: Create a local Kubernetes test cluster +description: Create a local Kubernetes test cluster +keywords: [kbcli, kubeblocks, addons, installation] +sidebar_position: 3 +sidebar_label: Prerequisite for Local Env +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Create a local Kubernetes test cluster + +This tutorial introduces how to create a local Kubernetes test cluster using Minikube, K3d, and Kind. These tools make it easy to try out KubeBlocks on your local host, offering a great solution for development, testing, and experimentation without the complexity of creating a full production-grade cluster. + +## Before you start + +Make sure you have the following tools installed on your local host: + +- Docker: All three tools rely on Docker to create containerized Kubernetes clusters. +- kubectl: The Kubernetes command-line tool for interacting with clusters. Refer to the [kubectl installation guide](https://kubernetes.io/docs/tasks/tools/) + + + + + +## Create a Kubernetes cluster using Kind + +Kind stands for Kubernetes IN Docker. It runs Kubernetes clusters within Docker containers, making it an ideal tool for local Kubernetes testing. + +1. Install Kind. For details, you can refer to [Kind Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/). + + + + + + ```bash + brew install kind + ``` + + + + + + ```bash + # For AMD64 / x86_64 + [ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-amd64 + # For ARM64 + [ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-arm64 + chmod +x ./kind + sudo cp ./kind /usr/local/bin/kind + rm -rf kind + ``` + + + + + + You can use chocolatey to install Kind. + + ```bash + choco install kind + ``` + + + + + +2. Create a Kind cluster. + + ```bash + kind create cluster --name mykindcluster + ``` + + This command creates a single-node Kubernetes cluster running in a Docker container. + +3. Check whether the cluster is started and running. + + ```bash + kubectl get nodes + > + NAME STATUS ROLES AGE VERSION + mykindcluster-control-plane Ready control-plane 25s v1.31.0 + ``` + + You can see a node named `mykindcluster-control-plane` from the output, which means the cluster is created successfully. + +4. (Optional) Configure a cluster with multiple nodes. + + Kind also supports clusters with multiple nodes. You can create a multi-node cluster by a configuration file. + + ```yaml + kind: Cluster + apiVersion: kind.x-k8s.io/v1alpha4 + nodes: + role: control-plane + role: worker + role: worker + ``` + + Use the configuration file to create a multi-node cluster. + + ```bash + kind create cluster --name multinode-cluster --config kind-config.yaml + ``` + +5. If you want to delete the Kind cluster, run the command below. + + ```bash + kind delete cluster --name mykindcluster + ``` + + + + + +## Create a Kubernetes cluster using Minikube + +Minikube runs a single-node Kubernetes cluster on your local machine, either in a virtual machine or a container. + +1. Install Minikube. For details, you can refer to [Minikube Quck Start](https://minikube.sigs.k8s.io/docs/start/). + + + + + + ```bash + brew install minikube + ``` + + + + + + ```bash + curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm + sudo rpm -Uvh minikube-latest.x86_64.rpm + ``` + + + + + + You can use chocolatey to install Minikube. + + ```bash + choco install minikube + ``` + + + + + +2. Start Minikube. This command will create a local Kubernetes cluster. + + ```bash + minikube start + ``` + + You can also specify other drivers (such as Docker, Hyperkit, KVM) to start it. + + ```bash + minikube start --driver=docker + ``` + +3. Verify whether Minikube and the K8s cluster is running normally. + + Check whether Minikube is running. + + ```bash + minikube status + > + minikube + type: Control Plane + host: Running + kubelet: Running + apiserver: Running + kubeconfig: Configured + ``` + + Check whether the K8s cluster is running. + + ```bash + kubectl get nodes + > + NAME STATUS ROLES AGE VERSION + minikube Ready control-plane 1d v1.26.3 + ``` + + From the output, we can see that the Minikube node is ready. + + + + + +## Create a Kubernetes cluster using k3d + +k3d is a lightweight tool that runs k3s (a lightweight Kubernetes distribution) in Docker containers. + +1. Install k3d. For details, refer to [k3d Quick Start](https://k3d.io/v5.7.4/#releases). + + + + + + ```bash + brew install k3d + ``` + + + + + + ```bash + curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash + ``` + + + + + + You can use chocolatey to install k3d. + + ```bash + choco install k3d + ``` + + + + + +2. Create a k3s cluster. + + ```bash + k3d cluster create myk3s + ``` + + This command will create a Kubernetes cluster named as `myk3s` with a single node. + +3. Verify whether this cluster is running normally. + + ```bash + kubectl get nodes + > + NAME STATUS ROLES AGE VERSION + k3d-myk3s-server-0 Ready control-plane,master 31s v1.30.4+k3s1 + ``` + +4. If you want to delete the k3s cluster, run the command below. + + ```bash + k3d cluster delete myk3s + ``` + + + + diff --git a/docs/user_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md b/docs/user_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md index 4480dcecf72..c2fd95d6cb2 100644 --- a/docs/user_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md +++ b/docs/user_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md @@ -23,7 +23,7 @@ import TabItem from '@theme/TabItem'; kbcli playground init # Use --version to specify a version - kbcli playground init --version='x.x.x' + kbcli playground init --version='x.y.z' ``` Or if you already have a Kubernetes cluster, you can install KubeBlocks [by kbcli](./../../installation/install-with-kbcli/install-kubeblocks-with-kbcli.md) or [by Helm](./../../installation/install-with-helm/install-kubeblocks.md) directly. diff --git a/docs/user_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md b/docs/user_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md index 09a7887c28b..b4fe2ddd1b8 100644 --- a/docs/user_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md +++ b/docs/user_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md @@ -136,7 +136,7 @@ Refer to the [Pulsar official document](https://pulsar.apache.org/docs/3.1.x/) f - zookeeper: 3 replicas ```bash - helm install mycluster kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set monitor.enabled=true --namespace=demo + helm install mycluster kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set monitor.enabled=true --namespace=demo ``` - **Option 2**: Create pulsar cluster with proxy. @@ -148,7 +148,7 @@ Refer to the [Pulsar official document](https://pulsar.apache.org/docs/3.1.x/) f - zookeeper: 3 replicas ```bash - helm install mycluster kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set proxy.enable=true --set monitor.enabled=true --namespace=demo + helm install mycluster kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set proxy.enable=true --set monitor.enabled=true --namespace=demo ``` - **Option 3**: Create pulsar cluster with proxy and deploy `bookies-recovery` component. @@ -161,7 +161,7 @@ Refer to the [Pulsar official document](https://pulsar.apache.org/docs/3.1.x/) f - bookies-recovery: 3 replicas ```bash - helm install mycluster kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set proxy.enable=true --set bookiesRecovery.enable=true --set monitor.enabled=true --namespace=demo + helm install mycluster kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set proxy.enable=true --set bookiesRecovery.enable=true --set monitor.enabled=true --namespace=demo ``` - **Option 4**: Create pulsar cluster and specify bookies and zookeeper storage parameters. @@ -172,7 +172,7 @@ Refer to the [Pulsar official document](https://pulsar.apache.org/docs/3.1.x/) f - zookeeper: 3 replicas ```bash - helm install mycluster kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set bookies.persistence.data.storageClassName=,bookies.persistence.log.storageClassName=,zookeeper.persistence.data.storageClassName=,zookeeper.persistence.log.storageClassName= --set monitor.enabled=true --namespace=demo + helm install mycluster kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set bookies.persistence.data.storageClassName=,bookies.persistence.log.storageClassName=,zookeeper.persistence.data.storageClassName=,zookeeper.persistence.log.storageClassName= --set monitor.enabled=true --namespace=demo ``` You can specify the storage name ``. diff --git a/docs/user_docs/overview/supported-addons.md b/docs/user_docs/overview/supported-addons.md index d6c23076e2d..8b302f70fbd 100644 --- a/docs/user_docs/overview/supported-addons.md +++ b/docs/user_docs/overview/supported-addons.md @@ -1,12 +1,12 @@ --- -title: Supported addons +title: Supported Addons description: Addons supported by KubeBlocks keywords: [addons, enable, KubeBlocks, prometheus, s3, alertmanager,] sidebar_position: 4 sidebar_label: Supported addons --- -# Supported addons +# Supported Addons KubeBlocks uses Addons to extend support for various database engines, And there are currently over 30 Addons available in the KubeBlocks repository. diff --git a/docs/user_docs/upgrade/faq.md b/docs/user_docs/upgrade/faq.md index 403b7148767..6cf887447d5 100644 --- a/docs/user_docs/upgrade/faq.md +++ b/docs/user_docs/upgrade/faq.md @@ -15,7 +15,7 @@ This guide addresses common questions and issues that may arise when upgrading K ## Manually mark Addons -To prevent an Addon from being deleted during a KubeBlocks upgrade via `kbcli` or Helm, add the `"helm.sh/resource-policy": "keep"` annotation. +In earlier versions, KubeBlocks pre-installed some Addons in the Helm chart, but some of these Addons have been removed in the new version. Consequently, if you upgrade ddirectly from an older version to the latest, Helm will remove the CRs of these removed Addons, affecting the clusters created by these Addons. To prevent this, it is recommended to add the `"helm.sh/resource-policy": "keep"` annotation for Addons to ensure they remain during upgraing. ### View the Addon annotation diff --git a/i18n/zh-cn/img/kubeblocks-api-layers.png b/i18n/zh-cn/img/kubeblocks-api-layers.png new file mode 100644 index 00000000000..f263ec7d6b2 Binary files /dev/null and b/i18n/zh-cn/img/kubeblocks-api-layers.png differ diff --git a/i18n/zh-cn/img/kubeblocks-architecture-ha.png b/i18n/zh-cn/img/kubeblocks-architecture-ha.png new file mode 100644 index 00000000000..c63e839d291 Binary files /dev/null and b/i18n/zh-cn/img/kubeblocks-architecture-ha.png differ diff --git a/i18n/zh-cn/img/kubeblocks-general-purpose-arch.png b/i18n/zh-cn/img/kubeblocks-general-purpose-arch.png new file mode 100644 index 00000000000..b5dbb933115 Binary files /dev/null and b/i18n/zh-cn/img/kubeblocks-general-purpose-arch.png differ diff --git a/i18n/zh-cn/user-docs/create_database/_category_.yml b/i18n/zh-cn/user-docs/create_database/_category_.yml new file mode 100644 index 00000000000..5476392286c --- /dev/null +++ b/i18n/zh-cn/user-docs/create_database/_category_.yml @@ -0,0 +1,4 @@ +position: 5 +label: Create Database +collapsible: true +collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/create_database/overview-of-create-database.md b/i18n/zh-cn/user-docs/create_database/overview-of-create-database.md new file mode 100644 index 00000000000..d4175a46bae --- /dev/null +++ b/i18n/zh-cn/user-docs/create_database/overview-of-create-database.md @@ -0,0 +1,24 @@ +--- +title: 如何创建数据库集群 +description: 如何创建数据库集群 +keywords: [创建数据库, KubeBlocks] +sidebar_position: 1 +sidebar_label: Overview +--- + +# 创建数据库集群 + +KubeBlocks 通过插件（Addon）机制支持多种数据库引擎。部署 KubeBlocks 后，您可以使用 KubeBlocks 创建各种数据库集群，例如 MySQL、PostgreSQL、Redis、MongoDB、Kafka、Pulsar、RabbitMQ、Elasticsearch、Qdrant 等。具体创建步骤可参考相应的文档。 + +- [ApeCloud MySQL](./../kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md) +- [MySQL 社区版](./../kubeblocks-for-mysql-community-edition/cluster-management/create-and-connect-a-mysql-cluster.md) +- [PostgreSQL](./../kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster.md) +- [Redis](./../kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster.md) +- [MongoDB](./../kubeblocks-for-mongodb/cluster-management/create-and-connect-to-a-mongodb-cluster.md) +- [Kafka](./../kubeblocks-for-kafka/cluster-management/create-a-kafka-cluster.md) +- [Pulsar](./../kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md) +- [RabbitMQ](./../kubeblocks-for-rabbitmq/manage-rabbitmq.md) +- [Elasticsearch](./../kubeblocks-for-elasticsearch/manage-elasticsearch.md) +- [StarRocks](./../kubeblocks-for-starrocks/manage-starrocks.md) +- [Milvus](./../kubeblocks-for-milvus/manage-milvus.md) +- [Qdrant](./../kubeblocks-for-qdrant/manage-qdrant.md) diff --git a/i18n/zh-cn/user-docs/installation/upgrade/_category_.yml b/i18n/zh-cn/user-docs/installation/install-with-helm/_category_.yml similarity index 63% rename from i18n/zh-cn/user-docs/installation/upgrade/_category_.yml rename to i18n/zh-cn/user-docs/installation/install-with-helm/_category_.yml index 215ba75757a..1444f832e04 100644 --- a/i18n/zh-cn/user-docs/installation/upgrade/_category_.yml +++ b/i18n/zh-cn/user-docs/installation/install-with-helm/_category_.yml @@ -1,4 +1,4 @@ position: 3 -label: 升级 +label: 使用 Helm 安装 collapsible: true collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/installation/install-with-helm/install-addons.md b/i18n/zh-cn/user-docs/installation/install-with-helm/install-addons.md new file mode 100644 index 00000000000..3d4fafeebf1 --- /dev/null +++ b/i18n/zh-cn/user-docs/installation/install-with-helm/install-addons.md @@ -0,0 +1,52 @@ +--- +title: 安装引擎 +description: 使用 Helm 安装 KubeBlocks 支持的引擎 +keywords: [引擎, helm, KubeBlocks] +sidebar_position: 3 +sidebar_label: 安装引擎 +--- + +# 安装引擎 + +KubeBlocks v0.8.0 发布后，数据库引擎插件（Addon）与 KubeBlocks 解耦，KubeBlocks 默认安装了部分引擎，如需体验其它引擎，需通过索引安装。如果您卸载了部分引擎，也可通过本文步骤，重新安装。 + +本文以 etcd 为例，可根据实际情况替换引擎名称。 + +官网引擎索引仓库为 [KubeBlocks 索引](https://github.com/apecloud/block-index)。引擎代码维护在 [KubeBlocks 引擎插件仓库](https://github.com/apecloud/kubeblocks-addons)。 + +1. （可选）添加 KubeBlocks 仓库。如果您使用 Helm 安装了 KubeBlocks 或此前已添加过该仓库，只需执行 `helm repo update`。 + + ```bash + helm repo add kubeblocks https://apecloud.github.io/helm-charts + helm repo update + ``` + +2. 查看引擎版本。 + + ```bash + helm search repo kubeblocks/etcd --devel --versions + ``` + +3. 以 ectd 为例，安装引擎。使用 `--version` 指定版本。 + + ```bash + helm install etcd kubeblocks/etcd --namespace kb-system --create-namespace --version x.y.z + ``` + +4. 验证该引擎是否安装成功。 + + 如果状态显示为 `deployed`，则表明该引擎已成功安装。 + + ```bash + helm list -A + > + NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION + ...... + etcd kb-system 1 2024-10-25 07:18:35.294326176 +0000 UTC deployed etcd-0.9.0 v3.5.6 + ``` + +5. （可选）您可以执行以下命令禁用引擎。 + + ```bash + helm uninstall etcd --namespace kb-system + ``` diff --git a/i18n/zh-cn/user-docs/installation/install-with-helm/install-kubeblocks.md b/i18n/zh-cn/user-docs/installation/install-with-helm/install-kubeblocks.md new file mode 100644 index 00000000000..895e93561ab --- /dev/null +++ b/i18n/zh-cn/user-docs/installation/install-with-helm/install-kubeblocks.md @@ -0,0 +1,157 @@ +--- +title: 安装 KubeBlocks +description: 在现有的 Kubernetes 集群上使用 Helm 安装 KubeBlocks +keywords: [污点, 亲和性, 容忍, 安装, kbcli, KubeBlocks] +sidebar_position: 1 +sidebar_label: 安装 KubeBlocks +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 安装 KubeBlocks + +KubeBlocks 是 Kubernetes 原生 operator，可通过 Helm 或者 kubectl 应用 YAML 文件安装 KubeBlocks。本文将介绍如何在现有的 Kubernetes 集群上部署 KubeBlocks。 + +如果您想要在本地环境试用 KubeBlocks，可通过 [Playground](./../../try-out-on-playground/try-kubeblocks-on-local-host.md) 试用，或者[先在本地创建 Kubernetes 测试集群](./../prerequisite/prepare-a-local-k8s-cluster.md)，然后按照本文操作步骤安装 KubeBlocks。 + +:::note + +如果您使用 Helm 安装 KubeBlocks，卸载时也需使用 Helm。 + +请确保您已安装 [kubectl](https://kubernetes.io/docs/tasks/tools/) 和 [Helm](https://helm.sh/docs/intro/install/)。 + +::: + +## 环境准备 + +准备一个可访问的 Kubernetes 集群，版本要求 1.22 及以上。该集群应满足如下要求。 + + + + + + + + + + + + + + + + + + + + + + + + + + +
资源要求
控制面建议创建 1 个具有 4 核 CPU、4 GB 内存和 50 GB 存储空间的节点。
数据面 MySQL 建议至少创建 3 个具有 2 核 CPU、4 GB 内存和 50 GB 存储空间的节点。
PostgreSQL 建议至少创建 2 个具有 2 核 CPU、4 GB 内存和 50 GB 存储空间的节点。
Redis 建议至少创建 2 个具有 2 核 CPU、4 GB 内存和 50 GB 存储空间的节点。
MongoDB 建议至少创建 3 个具有 2 核 CPU、4 GB 内存和 50 GB 存储空间的节点。
+ +## 安装步骤 + + + + + +按照以下步骤使用 Helm 安装 KubeBlocks。 + +1. 创建安装所依赖的 CRDs，并指定您想要安装的版本。 + + ```bash + kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/vx.y.z/kubeblocks_crds.yaml + ``` + + 您可以通过 [KubeBlocks 发布列表](https://github.com/apecloud/kubeblocks/releases) 查看 KubeBlocks 的所有版本，包括 alpha 及 beta 版本。 + + 也可通过执行以下命令，获取稳定版本： + + ```bash + curl -s "https://api.github.com/repos/apecloud/kubeblocks/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V -r + ``` + +2. 添加 KubeBlocks 的 Helm 仓库。 + + ```bash + helm repo add kubeblocks https://apecloud.github.io/helm-charts + helm repo update + ``` + +3. 安装 KubeBlocks。 + + ```bash + helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace + ``` + + 如果您想要在安装 KubeBlocks 添加自定义容忍度，可使用以下命令： + + ```bash + helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace \ + --set-json 'tolerations=[ { "key": "control-plane-taint", "operator": "Equal", "effect": "NoSchedule", "value": "true" } ]' \ + --set-json 'dataPlane.tolerations=[{ "key": "data-plane-taint", "operator": "Equal", "effect": "NoSchedule", "value": "true" }]' + ``` + + 如果您想要安装指定版本的 KubeBlocks，可执行如下步骤： + + 1. 在 [KubeBlocks 发布列表](https://github.com/apecloud/kubeblocks/releases/) 中查看可用版本。 + 2. 使用 `--version` 指定版本，并执行以下命令。 + + ```bash + helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace --version="x.y.z" + ``` + + :::note + + 如果不指定版本，默认安装最新版本。 + + ::: + + + + + +与 Kubernetes 中的其他资源相同，KubeBlocks 也可以通过 YAML 文件和 kubectl 命令进行安装。 + +1. 从对应版本的 [KubeBlocks 发布列表](https://github.com/apecloud/kubeblocks/releases) 中的资产部分获取 `kubeblocks.yaml` 文件地址。 + +2. 替换 YAML 文件地址，执行以下命令，安装 KubeBlocks。 + + ```bash + kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/vx.y.x/kubeblocks.yaml + ``` + + + + + +## 验证 KubeBlocks 安装 + +执行以下命令，检查 KubeBlocks 是否已成功安装。 + +```bash +kubectl -n kb-system get pods +``` + +***结果*** + +如果工作负载都显示已处于 Running 状态，则表明已成功安装 KubeBlocks。 + +```bash +NAME READY STATUS RESTARTS AGE +alertmanager-webhook-adaptor-8dfc4878d-svzrc 2/2 Running 0 3m56s +grafana-77dfd6959-4gnhp 1/1 Running 0 3m56s +kb-addon-snapshot-controller-546f84b78d-8rjs4 1/1 Running 0 3m56s +kubeblocks-7cf7745685-ddlwk 1/1 Running 0 4m39s +kubeblocks-dataprotection-95fbc79cc-b544l 1/1 Running 0 4m39s +prometheus-alertmanager-5c9fc88996-qltrk 2/2 Running 0 3m56s +prometheus-kube-state-metrics-5dbbf757f5-db9v6 1/1 Running 0 3m56s +prometheus-node-exporter-r6kvl 1/1 Running 0 3m56s +prometheus-pushgateway-8555888c7d-xkgfc 1/1 Running 0 3m56s +prometheus-server-5759b94fc8-686xp 2/2 Running 0 3m56s +``` diff --git a/i18n/zh-cn/user-docs/installation/install-with-helm/uninstall-kubeblocks.md b/i18n/zh-cn/user-docs/installation/install-with-helm/uninstall-kubeblocks.md new file mode 100644 index 00000000000..2f8289fbe06 --- /dev/null +++ b/i18n/zh-cn/user-docs/installation/install-with-helm/uninstall-kubeblocks.md @@ -0,0 +1,54 @@ +--- +title: 卸载 KubeBlocks +description: 卸载 KubeBlocks +keywords: [kubeblocks, 卸载] +sidebar_position: 5 +sidebar_label: 卸载 KubeBlocks +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Uninstall KubeBlocks + +卸载顺序： + +1. 如果已经创建了集群，请先删除集群。 + + ```bash + kubebctl delete cluster -n namespace + ``` + +2. 卸载 KubeBlocks。 + +## 卸载 KubeBlocks + + + + + +在执行以下命令前，请删除之前创建的所有集群和资源，否则卸载可能无法成功。 + +```bash +helm uninstall kubeblocks --namespace kb-system +``` + +Helm 不会删除 CRD 对象。请使用以下命令删除 KubeBlocks 创建的对象。 + +```bash +kubectl get crd -o name | grep kubeblocks.io | xargs kubectl delete +``` + + + + + +从 KubeBlocks chart 生成 YAML 文件，并使用 `kubectl` 进行卸载。使用 `--version x.y.z` 指定版本，确保卸载的版本与安装的版本相同。 + +```bash +helm template kubeblocks kubeblocks/kubeblocks --version x.y.z --namespace kb-system | kubectl delete -f - +``` + + + + diff --git a/i18n/zh-cn/user-docs/installation/install-with-kbcli/_category_.yml b/i18n/zh-cn/user-docs/installation/install-with-kbcli/_category_.yml index 61d361435c5..45c03fec690 100644 --- a/i18n/zh-cn/user-docs/installation/install-with-kbcli/_category_.yml +++ b/i18n/zh-cn/user-docs/installation/install-with-kbcli/_category_.yml @@ -1,4 +1,4 @@ -position: 1 +position: 2 label: 使用 kbcli 安装 collapsible: true collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-addons.md b/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-addons.md new file mode 100644 index 00000000000..0db1b02f682 --- /dev/null +++ b/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-addons.md @@ -0,0 +1,103 @@ +--- +title: 安装引擎 +description: 安装 KubeBlocks 引擎 +keywords: [kbcli, kubeblocks, addons, 安装，引擎] +sidebar_position: 3 +sidebar_label: 安装引擎 +--- + +# 安装引擎 + +KubeBlocks v0.8.0 发布后，引擎（Addon）与 KubeBlocks 解耦，KubeBlocks 默认安装了部分引擎，如需体验其它引擎，需通过索引安装相关引擎。如果您卸载了部分引擎，也可通过本文步骤，重新安装。 + +本文以 etcd 为例，可根据实际情况替换引擎名称。 + +官网引擎索引仓库为 [KubeBlocks index](https://github.com/apecloud/block-index)。引擎代码维护在 [KubeBlocks addon repo](https://github.com/apecloud/kubeblocks-addons)。 + +## 使用索引安装引擎 + +1. 查看引擎仓库索引。 + + kbcli 默认创建名为 `kubeblocks` 的索引，可使用 `kbcli addon index list` 查看该索引。 + + ```bash + kbcli addon index list + > + INDEX URL + kubeblocks https://github.com/apecloud/block-index.git + ``` + + 如果命令执行结果未显示或者你想要添加自定义索引仓库，则表明索引未建立，可使用 `kbcli addon index add ` 命令手动添加索引。例如， + + ```bash + kbcli addon index add kubeblocks https://github.com/apecloud/block-index.git + ``` + + 如果不确定索引是否为最新版本，可使用如下命令更新索引。 + + ```bash + kbcli addon index update kubeblocks + ``` + +2. （可选）索引建立后，可以通过 `addon search` 命令检查想要安装的引擎是否在索引信息中存在。 + + ```bash + kbcli addon search etcd + > + ADDON VERSION INDEX + etcd 0.7.0 kubeblocks + etcd 0.8.0 kubeblocks + etcd 0.9.0 kubeblocks + ``` + +3. 安装引擎。 + + 当引擎有多个版本和索引源时，可使用 `--index` 指定索引源，`--version` 指定安装版本。系统默认以 `kubeblocks` 索引仓库 为索引源，安装最新版本。 + + ```bash + kbcli addon install etcd --index kubeblocks --version x.y.z + ``` + + **后续操作** + + 引擎安装完成后，可查看引擎列表、启用引擎。 + +## 查看引擎列表 + +执行 `kbcli addon list` 命令查看已经支持的引擎。 + +## 启用/禁用引擎 + +请按照以下步骤手动启用或禁用引擎。 + +***步骤：*** + +1. 执行 `kbcli addon enable` 启用引擎。 + + ***示例*** + + ```bash + kbcli addon enable etcd + ``` + + 执行 `kbcli addon disable` 禁用引擎。 + +2. 再次查看引擎列表，检查是否已启用引擎。 + + ```bash + kbcli addon list + ``` + +## 卸载引擎 + +您也可卸载已安装的引擎。如果已经创建了相关集群，请先删除集群。 + +```bash +kbcli cluster delete +``` + +卸载已安装的引擎。 + +```bash +kbcli addon uninstall etcd +``` diff --git a/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kbcli.md b/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kbcli.md index 4ece9e44cb9..1cb321a8187 100644 --- a/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kbcli.md +++ b/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kbcli.md @@ -36,18 +36,26 @@ kbcli 目前支持 macOS、Windows 和 Linux 系统。 如果想安装 kbcli 的指定版本，请按照以下步骤进行操作： - 1. 在 [kbcli Release 页面](https://github.com/apecloud/kbcli/releases/)中查看可用版本。 + 1. 在 [kbcli 发布页面](https://github.com/apecloud/kbcli/releases/)中查看可用版本。 2. 使用 `-s` 指定版本，并执行以下命令。 ```bash - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.x.x + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s x.y.z ``` - + + 您可以通过 [kbcli 发布列表](https://github.com/apecloud/kbcli/releases) 查看 kbcli 的所有版本，包括 alpha 及 beta 版本。 + + 也可通过执行以下命令，获取稳定版本： + + ```bash + curl -s "https://api.github.com/repos/apecloud/kbcli/releases?per_page=100&page=1" | jq -r '.[] | select(.prerelease == false) | .tag_name' | sort -V -r + ``` + :::note - kbcli 默认安装最新版本。在安装 KubeBlocks 时，kbcli 会安装与之匹配的版本。请确保 kbcli 和 KubeBlocks 的主版本号相匹配。 + kbcli 默认安装最新版本。如果您的环境中已有正在运行的 KubeBlocks 实例，则需要安装与之匹配的 kbcli 版本。 - 例如，你可以安装 kbcli v0.6.1 和 KubeBlocks v0.6.3。但是，如果安装的是 kbcli v0.5.0 和 KubeBlocks v0.6.0，就可能会报错，因为版本不匹配。 + 例如，如果您当前使用的 KubeBlocks 版本是 v0.8.3，kbcli 应安装对应的 v0.8.3，而不是更高版本（如 v0.9.0），否则系统将因版本不匹配产生报错。 ::: @@ -80,7 +88,7 @@ kbcli 目前支持 macOS、Windows 和 Linux 系统。 brew search kbcli # 安装指定版本 - brew install kbcli@x.x.x + brew install kbcli@x.y.z ``` 3. 确认 kbcli 是否已成功安装。 diff --git a/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md b/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md index 35fd80e0c13..6cc48b87e5f 100644 --- a/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md +++ b/i18n/zh-cn/user-docs/installation/install-with-kbcli/install-kubeblocks-with-kbcli.md @@ -10,6 +10,8 @@ sidebar_label: 用 kbcli 安装 KubeBlocks 使用 Playground 创建一个新的 Kubernetes 集群并安装 KubeBlocks，是快速上手的一种方法。然而，在实际生产环境中，情况会复杂得多，应用程序在不同的命名空间中运行，还存在资源或权限限制。本文档将介绍如何在现有的 Kubernetes 集群上部署 KubeBlocks。 +如果您想要在本地环境试用 KubeBlocks，可通过 [Playground](./../../try-out-on-playground/try-kubeblocks-on-local-host.md) 试用，或者[先在本地创建 Kubernetes 测试集群](./../prerequisite/prepare-a-local-k8s-cluster.md)，然后按照本文操作步骤安装 KubeBlocks。 + ## 环境准备 准备一个可访问的 Kubernetes 集群，版本要求 1.22 及以上。该集群应满足如下要求。 @@ -57,6 +59,12 @@ kbcli kubeblocks install kbcli kubeblocks list-versions ``` + 如需查看包含 alpha 和 beta 在内的版本，可执行以下命令。 + + ```bash + kbcli kb list-versions --devel --limit=100 + ``` + 或者，你可以在 [KubeBlocks Release 页面](https://github.com/apecloud/kubeblocks/releases/)中查看可用的版本。 2. 使用 `--version` 指定版本。 @@ -67,9 +75,9 @@ kbcli kubeblocks install :::note - kbcli 默认安装最新版本。在安装 KubeBlocks 时，kbcli 会安装与之匹配的版本。请确保 kbcli 和 KubeBlocks 的主版本号相匹配。 + kbcli 默认安装最新版本。如果您的环境中已有正在运行的 KubeBlocks 实例，则需要安装与之匹配的 kbcli 版本。 - 例如，你可以安装 kbcli v0.6.1 和 KubeBlocks v0.6.3。但是，如果安装的是 kbcli v0.5.0 和 KubeBlocks v0.6.0，就可能会报错，因为版本不匹配。 + 例如，如果您当前使用的 KubeBlocks 版本是 v0.8.3，kbcli 应安装对应的 v0.8.3，而不是更高版本（如 v0.9.0），否则系统将因版本不匹配产生报错。 ::: @@ -93,4 +101,4 @@ NAMESPACE KIND NAME READY PODS CPU(CORES) kb-system Deployment kb-addon-snapshot-controller 1/1 N/A N/A Oct 13,2023 14:27 UTC+0800 kb-system Deployment kubeblocks 1/1 N/A N/A Oct 13,2023 14:26 UTC+0800 kb-system Deployment kubeblocks-dataprotection 1/1 N/A N/A Oct 13,2023 14:26 UTC+0800 -``` \ No newline at end of file +``` diff --git a/i18n/zh-cn/user-docs/installation/uninstall-kubeblocks-and-kbcli.md b/i18n/zh-cn/user-docs/installation/install-with-kbcli/uninstall-kbcli-and-kubeblocks.md similarity index 80% rename from i18n/zh-cn/user-docs/installation/uninstall-kubeblocks-and-kbcli.md rename to i18n/zh-cn/user-docs/installation/install-with-kbcli/uninstall-kbcli-and-kubeblocks.md index c1c7907953a..7bb0fa52593 100644 --- a/i18n/zh-cn/user-docs/installation/uninstall-kubeblocks-and-kbcli.md +++ b/i18n/zh-cn/user-docs/installation/install-with-kbcli/uninstall-kbcli-and-kubeblocks.md @@ -1,7 +1,7 @@ --- title: 卸载 kbcli 和 KubeBlocks -description: 处理异常并卸载 kbcli 和 KubeBlocks -keywords: [kbcli, kubeblocks, 异常, 卸载] +description: 卸载 kbcli 和 KubeBlocks +keywords: [kbcli, kubeblocks, 卸载] sidebar_position: 4 sidebar_label: 卸载 KubeBlocks 和 kbcli --- @@ -14,9 +14,11 @@ import TabItem from '@theme/TabItem'; 卸载顺序： 1. 如果已经创建了集群，请先删除集群。 + ```bash kbcli cluster delete ``` + 2. 卸载 KubeBlocks。 3. 卸载 kbcli。 @@ -34,6 +36,7 @@ kbcli kubeblocks uninstall 如果想在试用结束后删除 kbcli，请选择与安装 kbcli 时所使用的相同选项。 + 如果你使用的是 `curl`，执行以下命令： @@ -56,16 +59,16 @@ kbcli 会在 HOME 目录下创建一个名为 `~/.kbcli` 的隐藏文件夹， 1. 进入 `kbcli` 的安装路径，并删除安装文件夹。 - - 如果你通过脚本安装了 `kbcli`，请前往 `C:\Program Files` 并删除 `kbcli-windows-amd64` 文件夹。 - - 如果你自定义了安装路径，请前往指定路径，并删除安装文件夹。 + - 如果你通过脚本安装了 `kbcli`，请前往 `C:\Program Files` 并删除 `kbcli-windows-amd64` 文件夹。 + - 如果你自定义了安装路径，请前往指定路径，并删除安装文件夹。 2. 删除环境变量。 1. 点击 Windows 图标，然后点击 **系统**。 2. 进入 **设置** -> **相关设置** -> **高级系统设置**。 3. 在 **高级** 标签页，点击 **环境变量**。 4. 在 **用户变量** 或 **系统变量** 列表中，双击 **Path**。 - - 如果你通过脚本安装了 `kbcli`，双击 **用户变量** 中的 Path。 - - 如果你自定义了安装路径，请根据之前创建变量的位置，双击相应的 **Path**。 + - 如果你通过脚本安装了 `kbcli`，双击 **用户变量** 中的 Path。 + - 如果你自定义了安装路径，请根据之前创建变量的位置，双击相应的 **Path**。 5. 选择 `C:\Program Files\kbcli-windows-amd64` 或自定义的路径，并删除它。此操作需要二次确认。 3. 删除名为 `.kbcli` 的文件夹。 diff --git a/i18n/zh-cn/user-docs/installation/prerequisite/_category_.yml b/i18n/zh-cn/user-docs/installation/prerequisite/_category_.yml new file mode 100644 index 00000000000..91327bbc98a --- /dev/null +++ b/i18n/zh-cn/user-docs/installation/prerequisite/_category_.yml @@ -0,0 +1,4 @@ +position: 1 +label: 本地测试环境准备 +collapsible: true +collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/installation/prerequisite/prepare-a-local-k8s-cluster.md b/i18n/zh-cn/user-docs/installation/prerequisite/prepare-a-local-k8s-cluster.md new file mode 100644 index 00000000000..dd8ce907ba5 --- /dev/null +++ b/i18n/zh-cn/user-docs/installation/prerequisite/prepare-a-local-k8s-cluster.md @@ -0,0 +1,228 @@ +--- +title: 创建本地 Kubernetes 测试集群 +description: 创建本地 Kubernetes 测试集群 +keywords: [kbcli, kubeblocks, addons, 安装，引擎] +sidebar_position: 3 +sidebar_label: 本地测试环境准备 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 创建本地 Kubernetes 测试集群 + +本文将说明如何使用三种流行的轻量级工具：Minikube、K3d 和 Kind，在本地创建 Kubernetes 测试集群，可用于在本地环境试用 KubeBlocks。这些工具非常适合开发、测试和实验，而无需搭建完整的生产级 Kubernetes 集群。 + +## 前置条件 + +在开始之前，请确保您已经在本地安装了以下工具： + +- Docker：所有三个工具都使用 Docker 来创建容器化的 Kubernetes 集群。 +- kubectl：Kubernetes 的命令行工具，用于与集群交互。参考 [kubectl 安装文档](https://kubernetes.io/docs/tasks/tools/)。 + +## 使用 Kind 创建 Kubernetes 集群 + +Kind 是 Kubernetes IN Docker 的缩写。它在 Docker 容器中运行 Kubernetes 集群，非常适合在本地进行 Kubernetes 测试。 + +1. 安装 Kind。详情可参考 [Kind Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start/)。 + + + + + + ```bash + brew install kind + ``` + + + + + + ```bash + # For AMD64 / x86_64 + [ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-amd64 + # For ARM64 + [ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-arm64 + chmod +x ./kind + sudo cp ./kind /usr/local/bin/kind + rm -rf kind + ``` + + + + + + 可使用 chocolatey 安装 Kind。 + + ```bash + choco install kind + ``` + + + + + +2. 通过 Kind 创建 Kubernetes 集群： + + ```bash + kind create cluster --name mykindcluster + ``` + + 该命令将创建一个单节点的 Kubernetes 集群，运行在 Docker 容器中。 + +3. 检查集群是否已启动并运行。 + + ```bash + kubectl get nodes + ``` + + 从输出结果中可以看到一个名为 `mykindcluster-control-plane` 的节点。 + +4. （可选）配置多节点集群。 + + Kind 也支持创建多节点的集群。可通过配置文件来创建多节点集群： + + ```yaml + kind: Cluster + apiVersion: kind.x-k8s.io/v1alpha4 + nodes: + role: control-plane + role: worker + role: worker + ``` + + 使用该配置文件创建集群： + + ```bash + kind create cluster --name multinode-cluster --config kind-config.yaml + ``` + +5. 如需删除 Kind 集群，可以使用以下命令。 + + ```bash + kind delete cluster --name mykindcluster + ``` + +## 使用 Minikube 创建 Kubernetes 集群 + +Minikube 支持在本地机器的虚拟机或容器中运行单节点的 Kubernetes 集群。 + +1. 安装 Minikube。详情可参考 [Minikube Quck Start](https://minikube.sigs.k8s.io/docs/start/)。 + + + + + + ```bash + brew install minikube + ``` + + + + + + ```bash + curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm + sudo rpm -Uvh minikube-latest.x86_64.rpm + ``` + + + + + + 可使用 chocolatey 安装 Minikube。 + + ```bash + choco install minikube + ``` + + + + + +2. 启动 Minikube。该命令将创建一个本地的 Kubernetes 集群： + + ```bash + minikube start + ``` + + 您也可以指定其他驱动（例如 Docker、Hyperkit、KVM 等）启动。 + + ```bash + minikube start --driver=docker + ``` + +3. 验证安装。 + + 检查 Minikube 是否正在运行： + + ```bash + minikube status + ``` + + 检查 Kubernetes 集群是否已启动： + + ```bash + kubectl get nodes + > + NAME STATUS ROLES AGE VERSION + minikube Ready control-plane 197d v1.26.3 + ``` + + 从输出结果中可以看到 Minikube 节点处于 Ready 状态。 + +## 使用 k3d 创建 Kubernetes 集群 + +k3d 是一个轻量级工具，它在 Docker 容器中运行 k3s（一个轻量的 Kubernetes 发行版）。 + +1. 安装 k3d。详情可参考 [k3d Quick Start](https://k3d.io/v5.7.4/#releases)。 + + + + + + ```bash + brew install k3d + ``` + + + + + + ```bash + curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash + ``` + + + + + + 可使用 chocolatey 安装 k3d。 + + ```bash + choco install k3d + ``` + + + + + +2. 创建 k3s 集群。 + + ```bash + k3d cluster create myk3s + ``` + + 执行该命令后，将创建一个名为 `myk3s` 的 Kubernetes 集群，包含一个服务器节点。 + +3. 验证集群是否运行。 + + ```bash + kubectl get nodes + ``` + +4. 如需删除 k3s 集群，可使用以下命令。 + + ```bash + k3d cluster delete mycluster + ``` diff --git a/i18n/zh-cn/user-docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md b/i18n/zh-cn/user-docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md deleted file mode 100644 index 4b93aba1a07..00000000000 --- a/i18n/zh-cn/user-docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: 升级到 KubeBlocks v0.8 -description: 如何升级到 KubeBlocks v0.8 -keywords: [升级, 0.8] -sidebar_position: 2 -sidebar_label: 升级到 KubeBlocks v0.8 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# 升级到 KubeBlocks v0.8 - -本文档介绍如何从低版本 KubeBlocks 升级至 KubeBlocks 0.8 版本。 - -:::note - -在升级前，请先执行 `kbcli version` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 - -::: - -## 从 v0.6 版本升级 - -如果当前使用的是 KubeBlocks v0.6 版本，请先将 KubeBlocks 升级至 v0.7.2 版本，操作如下： - -1. 下载 kbcli v0.7.2 版本。 - - ```shell - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.7.2 - ``` - -2. 升级至 KubeBlocks v0.7.2。 - - ```shell - kbcli kb upgrade --version 0.7.2 - ``` - -## 从 v0.7 版本升级 - - - - - -1. 设置 keepAddons。 - - KubeBlocks v0.8 精简了默认安装的引擎，将 addon 从 KubeBlocks operator 分离到了 KubeBlocks Addons 代码仓库中，例如 greptime，influxdb，neon，oracle-mysql，orioledb，tdengine，mariadb，nebula，risingwave，starrocks，tidb，zookeeper。为避免升级时将已经在使用的 addon 资源删除，请先执行如下命令。 - -- 查看当前 KubeBlocks 版本。 - - ```shell - helm -n kb-system list | grep kubeblocks - ``` - -- 设置 keepAddons 参数为 true。 - - ```shell - helm repo add kubeblocks https://apecloud.github.io/helm-charts - helm repo update kubeblocks - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version {VERSION} --set keepAddons=true - ``` - - 请将以上 {VERSION} 替换为当前 KubeBlocks 的版本，比如 0.7.2。 - -- 查看 addon。 - - 执行如下命令，确保 addon annotations 中添加了 `"helm.sh/resource-policy": "keep"`。 - - ```shell - kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}' - ``` - -2. 安装 CRD。 - - 为避免 KubeBlocks 的 Helm chart 过大，v0.8 版本将 CRD 从 Helm chart 中移除了，升级前需要先安装 CRD。 - - ```shell - kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.8.1/kubeblocks_crds.yaml - ``` - -3. 升级 KubeBlocks。 - - ```shell - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 - ``` - - :::note - - 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.8 时，默认不会升级已经安装的 addon 的版本。如果要升级 addon 至 KubeBlocks v0.8 内置 addon 的版本，可以执行如下命令。注意，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 - - ```shell - - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set upgradeAddons=true - - ``` - ::: - - - - - -1. 下载 kbcli v0.8 版本。 - - ```shell - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.8.1 - ``` - -2. 升级 KubeBlocks。 - - ```shell - - kbcli kb upgrade --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 - - ``` - - kbcli 会默认为已有 addon 添加 annotation `"helm.sh/resource-policy": "keep"`，确保升级过程中已有的 addon 不会被删除。 - - - - diff --git a/i18n/zh-cn/user-docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md b/i18n/zh-cn/user-docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md deleted file mode 100644 index c69f034ed7a..00000000000 --- a/i18n/zh-cn/user-docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: 升级到 KubeBlocks v0.9 -description: 如何升级到 KubeBlocks v0.9 -keywords: [升级, 0.9] -sidebar_position: 1 -sidebar_label: 升级到 KubeBlocks v0.9 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# 升级到 KubeBlocks v0.9 - -本文档介绍如何将 KubeBlocks 升级至 KubeBlocks 0.9 版本。 - -:::note - -在升级前，请先执行 `kbcli version` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 - -::: - -## 兼容性说明 - -KubeBlocks 0.9 可以兼容 KubeBlocks 0.8 的 API，但不保证兼容 0.8 之前版本的 API，如果您正在使用 KubeBlocks 0.7 或者更老版本的 Addon（版本号为 0.7., *0.6.*），请务必参考 [0.8 升级文档](./upgrade-kubeblocks-to-0.8.md)将 KubeBlocks 升级至 0.8 并将所有引擎（addon）升级至 0.8，以确保升级至 0.9 版本后服务的可用性。 - -## 从 0.8 版本升级 - - - - - -1. 设置 keepAddons。 - - KubeBlocks v0.8 精简了默认安装的引擎。为避免升级时将已经在使用的引擎资源删除，请先执行如下命令。 - - - 查看当前 KubeBlocks 版本。 - - ```shell - helm -n kb-system list | grep kubeblocks - ``` - - - 设置 keepAddons 参数为 true。 - - ```shell - helm repo add kubeblocks https://apecloud.github.io/helm-charts - helm repo update kubeblocks - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version {VERSION} --set keepAddons=true - ``` - - 请将以上 `{VERSION}` 替换为当前 KubeBlocks 的版本，比如 0.8.3。 - - - 查看 addon。 - - 执行如下命令，确保 addon annotations 中添加了 `"helm.sh/resource-policy": "keep"`。 - - ```shell - kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}' - ``` - -2. 删除不兼容的 OpsDefinition。 - - ```bash - kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover - ``` - -3. 安装 CRD。 - - 为避免 KubeBlocks Helm Chart 过大，0.8 版本将 CRD 从 Helm Chart 中移除了，升级前需要先安装 CRD。 - - ```shell - kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.0/kubeblocks_crds.yaml - ``` - -4. 升级 KubeBlocks - - ```shell - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.0 --set upgradeAddons=false - ``` - - :::note - - 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9 时，默认不会升级已经安装的引擎版本，如果要升级 Addon 版本至 KubeBlocks v0.9 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 - - ```bash - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.0 --set upgradeAddons=true - ``` - - ::: - - - - - -1. 下载 0.9 版本 kbcli。 - - ```shell - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.9.0 - ``` - -2. 升级 KubeBlocks。 - - ```bash - kbcli kb upgrade --version 0.9.0 - ``` - - :::note - - 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9 时，默认不会升级已经安装的引擎版本，如果要升级引擎版本至 KubeBlocks v0.9 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 - - ```bash - kbcli kb upgrade --version 0.9.0 --set upgradeAddons=true - ``` - - ::: - - kbcli 会默认为已有 addon 添加 annotation `"helm.sh/resource-policy": "keep"`，确保升级过程中已有 addon 不会被删除。 - - - - - -## 升级引擎 - -如果您在上述步骤中，没有将 `upgradeAddons` 指定为 `true`，或者您想要使用的引擎不在默认 addon 列表中，但您想要使用 v0.9.0 API，可使用如下方式升级引擎。 - -:::note - -- 如果您想要升级的引擎是 `mysql`，您需要升级 addon 并重启集群。否则使用 KubeBlocks v0.8 创建的集群将无法在 v0.9 中使用。 - -- 如果您想要升级 `clickhouse/milvus/elasticsearch/llm`，您需要先升级 KubeBlocks，再升级 addon，否在将无法在 v0.9 中正常使用。 - -::: - - - - - -```bash -# 添加 Helm repo -helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts - -# 如果您无法访问 GitHub 或者网速过慢，可使用以下 repo -helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable - -# 更新 helm repo -helm repo update - -# 更新引擎版本 -helm upgrade -i xxx kubeblocks-addons/xxx --version x.x.x -n kb-system -``` - - - - - -```bash -kbcli addon index list - -kbcli addon index update kubeblocks - -kbcli addon upgrade xxx --force -``` - - - - diff --git a/i18n/zh-cn/user-docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md b/i18n/zh-cn/user-docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md index a397d96d76d..d640ebb9431 100644 --- a/i18n/zh-cn/user-docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md +++ b/i18n/zh-cn/user-docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md @@ -23,7 +23,7 @@ import TabItem from '@theme/TabItem'; kbcli playground init # 使用--version 指定版本 - kbcli playground init --version='x.x.x' + kbcli playground init --version='x.y.z' ``` 如果已经有 Kubernetes 集群，可以通过 [kbcli](./../../installation/install-with-kbcli/install-kubeblocks-with-kbcli.md) 安装 KubeBlocks。 diff --git a/i18n/zh-cn/user-docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kb.md b/i18n/zh-cn/user-docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kb.md index 2c8cdc464ec..d787c2eea9f 100644 --- a/i18n/zh-cn/user-docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kb.md +++ b/i18n/zh-cn/user-docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kb.md @@ -115,7 +115,7 @@ KubeBlocks 可以通过良好的抽象快速集成新引擎，并支持 Pulsar - 3 节点 zookeeper ```bash - helm install pulsar kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set monitor.enabled=true + helm install pulsar kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set monitor.enabled=true ``` - **选项 2.** 创建带 proxy 的 Pulsar 集群。 @@ -126,7 +126,7 @@ KubeBlocks 可以通过良好的抽象快速集成新引擎，并支持 Pulsar - 3 节点 zookeeper ```bash - helm install pulsar kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set proxy.enable=true --set monitor.enabled=true + helm install pulsar kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set proxy.enable=true --set monitor.enabled=true ``` - **选项 3.** 创建带 proxy 的 Pulsar 集群，并部署独立的 `bookies-recovery` 组件。 @@ -138,7 +138,7 @@ KubeBlocks 可以通过良好的抽象快速集成新引擎，并支持 Pulsar - 3 节点 bookies-recovery ```bash - helm install pulsar kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set proxy.enable=true --set bookiesRecovery.enable=true --set monitor.enabled=true + helm install pulsar kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set proxy.enable=true --set bookiesRecovery.enable=true --set monitor.enabled=true ``` - **选项 4.** 创建 Pulsar 集群并指定 bookies 和 zookeeper 的存储参数。 @@ -148,7 +148,7 @@ KubeBlocks 可以通过良好的抽象快速集成新引擎，并支持 Pulsar - 3 节点 zookeeper ```bash - helm install pulsar kubeblocks/pulsar-cluster --version "x.x.x" -f values-production.yaml --set bookies.persistence.data.storageClassName=,bookies.persistence.log.storageClassName=,zookeeper.persistence.data.storageClassName=,zookeeper.persistence.log.storageClassName= --set monitor.enabled=true + helm install pulsar kubeblocks/pulsar-cluster --version "x.y.z" -f values-production.yaml --set bookies.persistence.data.storageClassName=,bookies.persistence.log.storageClassName=,zookeeper.persistence.data.storageClassName=,zookeeper.persistence.log.storageClassName= --set monitor.enabled=true ``` 你可以指定存储名称 ``。 diff --git a/i18n/zh-cn/user-docs/overview/about-this-manual.md b/i18n/zh-cn/user-docs/overview/about-this-manual.md index a49d986e631..30f21062d2d 100644 --- a/i18n/zh-cn/user-docs/overview/about-this-manual.md +++ b/i18n/zh-cn/user-docs/overview/about-this-manual.md @@ -5,4 +5,4 @@ keywords: [kubeblocks, 概述, 简介] sidebar_position: 1 --- -本文档介绍了如何通过 `kbcli` 使用 KubeBlocks。 +本文档介绍了如何通过 `kbcli` 使用 KubeBlocks。本文档还包括通过 helm 和 kubectl 使用 KubeBlocks 的命令，为您提供多种操作选择。 diff --git a/i18n/zh-cn/user-docs/overview/concept.md b/i18n/zh-cn/user-docs/overview/concept.md index e48ed382604..86a7f68cec9 100644 --- a/i18n/zh-cn/user-docs/overview/concept.md +++ b/i18n/zh-cn/user-docs/overview/concept.md @@ -1,45 +1,166 @@ --- title: 概念 -description: KubeBlocks, kbcli, 多云 -keywords: [kubeblocks, 概念, 简介] -sidebar_position: 3 +description: KubeBlocks, CRD +keywords: [kubeblocks, 概念] +sidebar_position: 2 --- # 概念 -- 节点（Node）：在分布式数据库中，每台计算机被称为一个节点，每个节点都有其独立的存储和处理能力。通过添加新节点，可以轻松扩展分布式数据库的存储和处理能力，以应对日益增长的数据量和并发访问需求。分布式数据库可以将读写请求分配到不同的节点进行处理，从而实现负载均衡并提高系统的并发处理能力。 +["统一 API 如何降低学习曲线"](./introduction.md#统一的-api-如何降低学习门槛)一节介绍了使用统一 API 表达各种数据库的优势。如果仔细查看这些示例，您会发现示例 YAML 文件中包含两个关键概念：**Cluster（集群）** 和 **Component（组件）**。例如，`test-mysql` 是一个包含名为 `mysql` 组件的集群（组件定义为 `apecloud-mysql`）。`test-redis` 也是一个集群，包含两个组件：一个是 `redis`（组件定义为 `redis-7`），有两个副本；另一个是 `redis-sentinel`（组件定义为 `redis-sentinel`），有三个副本。 -- 数据分片（Data Sharding）：为了实现数据的分布式存储，需要将数据分成多个部分，每个部分称为一个数据分片。常见的数据分片策略包括： +本文档将解释这两个概念背后的原因，并简要介绍其背后的 API（即 CRD, Custom Resource Definition）。 - - 范围分片（Range Sharding）：根据键值范围将数据分成多个分片，每个分片负责一个连续的键值范围。 - - 哈希分片（Hash Sharding）：使用哈希函数将数据的键值映射到不同的分片，每个分片负责一个哈希值范围。 - - 复合分片（Composite Sharding）：结合多种分片策略，例如先根据范围进行分片，然后再根据哈希进行分片，以优化数据的分布和访问效率。 +## KubeBlocks 分层 API 的设计动机 -- Pod：Pod 是 K8s 中最小的可部署和可管理单元。它由一个或多个紧密关联的容器组成，这些容器共享网络和存储资源，并作为一个整体进行调度和管理。在 K8s 中，可以通过配置资源请求和限制来管理和控制 Pod 对节点资源（CPU、内存）的使用。 +在 KubeBlocks 中，为了通过统一 API 支持各种数据库的管理，我们需要抽象不同数据库的拓扑结构和特性。 - - 资源请求定义了 Pod 在运行时所需的最低资源量。K8s 调度器会选择能够满足 Pod 资源请求的节点，确保这些节点有足够的可用资源来满足 Pod 的需求。 - - 资源限制定义了 Pod 在运行时可以使用的最大资源量。它们用于防止 Pod 消耗过多的资源，从而保护节点和其他 Pod 不受影响。 +我们观察到，生产环境中部署的数据库系统通常采用由多个组件组成的拓扑结构。例如，一个生产环境中的 MySQL 集群可能包括多个代理节点（如 ProxySQL、MaxScale、Vitess、WeScale 等）和多个 MySQL 服务器节点（如 MySQL 社区版、Percona、MariaDB、ApeCloud MySQL 等），以实现高可用性和读写分离。类似地，Redis 部署通常由一个主节点和多个只读副本组成，并通过 Sentinel 管理以确保高可用性。一些用户甚至使用 twemproxy 进行水平分片，以实现更大的容量和吞吐量。 -- 数据复制（Replication） +这种模块化方法在分布式数据库系统中尤为常见，整个系统被划分为职责明确的独立组件，如数据存储、查询处理、事务管理、日志记录和元数据管理等。这些组件通过网络进行交互，确保系统能够像单节点数据库一样提供强一致性和事务保障，并实现负载均衡、分布式事务以及具备故障切换能力的灾难恢复等复杂操作。 - 为了提高数据的可用性和容错性，分布式数据库通常会将数据复制到多个节点上，每个节点拥有完整或部分数据的副本。通过数据复制和故障转移机制，分布式数据库即使在节点故障时也能继续提供服务，从而提高系统的可用性。常见的复制策略包括： +因此，KubeBlocks 采用了分层 API（即 CRD）的设计，由 **Cluster（集群）** 和 **Component（组件）** 组成，以适应数据库系统的多组件、高度可变的部署拓扑结构。这些抽象允许我们灵活地表达和管理部署在 Kubernetes 上的各种数据库系统拓扑，并根据所需拓扑轻松地将组件组装成集群。 - - 主从复制（Primary-Replica Replication）： - - 每个分区有一个主节点和多个从节点。 - - 写操作在主节点上执行，然后同步到从节点。 - - 常见的主从复制协议包括强同步、半同步、异步，以及基于 Raft/Paxos 的复制协议。 - - 多主复制（Multi-Primary Replication）： - - 每个分区有多个主节点。 - - 写操作可以在任意一个主节点上执行，然后同步到其他主节点和从节点。 - - 数据一致性通过复制协议以及全局锁、乐观锁等机制来维护。 +组件是组成集群的积木块。事实上，数据库引擎插件开发者可以在 ClusterDefinition 中定义如何将多个组件组装成不同的拓扑结构。如果您只是普通用户，则无需过度关注 ClusterDefinition 的细节；您只需要知道 KubeBlocks 的插件可以提供不同的拓扑结构选择。例如，Redis 引擎插件支持三种拓扑："standalone"（单机），"replication"（主从复制）和 "replication-twemproxy"（主从复制 + twemproxy）。您可以在创建集群时指定所需的拓扑。 -总的来说，数据复制是分布式数据库提高可用性和容错性的一项关键技术。不同的复制策略在一致性、可用性和性能之间涉及不同的权衡，应基于具体的应用需求来做出决策。 +以下是通过 `clusterDefinitionRef` 和 `topology` 创建 Redis 集群的示例： -KubeBlocks 对容器化分布式数据库的管理映射到四个层级的对象：Cluster（集群）、Component（组件）、InstanceSet（实例集）和 Instance（实例），形成了分层架构： +```yaml +apiVersion: apps.kubeblocks.io/v1alpha1 +kind: Cluster +metadata: + name: test-redis-use-topology + namespace: default +spec: + clusterDefinitionRef: redis + topology: replication + terminationPolicy: Delete + componentSpecs: + - name: redis + replicas: 2 + disableExporter: true + resources: + limits: + cpu: '0.5' + memory: 0.5Gi + requests: + cpu: '0.5' + memory: 0.5Gi + volumeClaimTemplates: + - name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + - name: redis-sentinel + 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: 10Gi +``` -- **集群层（Cluster layer）**：Cluster 对象表示一个完整的分布式数据库集群。Cluster 是最高级别的抽象，包括数据库的所有组件和服务。 -- **组件层（Component layer）**：Component 表示构成 Cluster 对象的逻辑组件，如元数据管理、数据存储、查询引擎等。每个 Component 对象都有其特定的任务和功能。一个 Cluster 对象包含一个或多个 Component 对象。 -- **实例集层（InstanceSet layer）**：InstanceSet 对象管理 Component 对象内多个副本所需的工作负载，感知这些副本的角色。一个 Component 对象包含一个 InstanceSet 对象。 -- **实例层（Instance layer）**：Instance 对象表示 InstanceSet 对象中的实际运行实例，对应于 Kubernetes 中的 Pod。一个 InstanceSet 对象可以管理零个到多个 Instance 对象。 -- **ComponentDefinition** 是用于定义分布式数据库组件的 API，描述了组件的实现细节和行为。通过 ComponentDefinition，可以定义组件的关键信息，如容器镜像、配置模板、启动脚本、存储卷等。它们还可以为组件在不同事件（如节点加入、节点离开、组件增加、组件移除、角色切换等）下设置行为和逻辑。每个组件可以拥有独立的 ComponentDefinition，或共享相同的 ComponentDefinition。 -- **ClusterDefinition** 是用于定义分布式数据库集群整体结构和拓扑的 API。在 ClusterDefinition 中，可以引用其包含组件的 ComponentDefinition，并定义组件之间的依赖关系和引用关系。 +仔细看上面这个 YAML 文件，可以发现，通过在集群中指定 `clusterDefinitionRef` 和 `topology`，则无需再为每个组件指定 `componentDef`。 + +借助 Component API，KubeBlocks 将数据库容器打包成标准化的积木块，这些积木块可以根据指定的拓扑组装成数据库集群，并运行在 Kubernetes 上。我们认为这个过程很像用乐高积木搭建东西，这也是 KubeBlocks 这一名字的来源。 + +## 深入了解 KubeBlocks API + +下图展示了 KubeBlocks 的主要 CRD，这里特别强调了 API 的分层结构。其他重要的 API，如 OpsRequest、Backup 和 Restore，并未包含在此图中。下图重点关注分层结构，图表展示更加清晰。我们将在其他文档中解释其他重要的 API。 + +![KubeBlocks API Layers](./../../img/kubeblocks-api-layers.png) + +KubeBlocks 的 CRD 可分为两大类：用户使用的 CRD 和 插件 CRD。 + +**用户使用的 CRD** + +用户使用的 CRD 包括 Cluster、Component 和 InstanceSet。使用 KubeBlocks 创建数据库集群时，将生成以下 CR： + +- Cluster 对象：由用户创建。 +- Component 对象：KubeBlocks 集群控制器（Cluster Controller）在检测到 Cluster 对象时递归创建的子资源。 +- InstanceSet 对象：KubeBlocks 组件控制器（Component Controller）在检测到 Component 对象时递归创建的子资源。InstanceSet 控制器（InstanceSet Controller）随后递归创建 Pod 和 PVC 对象。 + +**插件 CRD** + +插件使用的 CRD 包括 ClusterDefinition、ComponentDefinition 和 ComponentVersion。这些 CR 由数据库引擎插件开发者编写，并捆绑在插件的 Helm chart 中。 + +:::note + +您无需编写 ClusterDefinition 和 ComponentDefinition 的 CR，但仍需要使用这些 CR。如前面创建 Redis Cluster 所示，创建集群时，可以选择在每个组件的 `componentDef` 中指定相应的 ComponentDefinition CR 名称，或者在 `clusterDefinitionRef` 中指定相应的 ClusterDefinition CR 名称，并选择所需的拓扑结构。 + +::: + +### 用户使用的 KubeBlocks API + +#### Cluster + +Cluster 对象表示由 KubeBlocks 管理的整个数据库集群。一个集群可以包含多个 Component，用户在 Cluster API 中指定每个 Component 的配置，集群控制器将生成并调谐相应的 Component 对象。此外，集群控制器还管理在集群层暴露的所有服务地址。 + +对于像 Redis Cluster 这种采用无共享架构的分布式数据库，集群对象支持管理多个分片（shard），每个分片由一个单独的 Component 管理。这种架构还支持动态分片（dynamic resharding）：如果需要扩展并添加新分片，只需添加一个新的 Component；反之，如果需要缩减分片数量，则移除相应的 Component。 + +#### Component + +Component 是集群对象的基本模块。例如，一个 Redis 集群可以包含 redis、sentinel，也可能包含代理组件，如 twemproxy。 + +Component 对象负责管理 Component 内所有副本的生命周期，支持多种操作，包括实例的创建、停止、重启、终止、升级、配置变更、垂直和水平扩展、故障切换、主备切换、调度配置、服务暴露、系统账号管理等。 + +Component 是从用户提交的 Cluster 对象派生的内部子对象，主要供 KubeBlocks 控制器使用，不建议用户直接修改 Component 对象，应仅用于监控 Component 状态。 + +#### InstanceSet + +从 KubeBlocks v0.9 开始，KubeBlocks 用 InstanceSet 替代 StatefulSet。 + +一个数据库实例（或副本）由一个 Pod 和其他辅助对象（如 PVC、Service、ConfigMap、Secret）组成。InstanceSet 是一个负责管理实例组的工作负载 CRD。在 KubeBlocks 中，所有工作负载最终都由 InstanceSet 管理。与 Kubernetes 原生的工作负载 CRD（如 StatefulSet 和 Deployment）相比，InstanceSet 融入了更多针对数据库领域的设计和考量，例如每个副本的角色、高可用性需求，以及对特定节点进行下线等操作的支持。 + +### KubeBlocks Addon API + +:::note + +只有引擎插件开发者需要了解 ClusterDefinition 和 ComponentDefinition API，普通用户可以跳过这部分内容。 + +::: + +#### ClusterDefinition + +ClusterDefinition 是用于定义数据库集群所有可用拓扑的 API，提供了多种拓扑配置以满足不同的部署需求和场景。 + +每个拓扑都包含一个组件列表，每个组件都关联到一个 ComponentDefinition，提升了复用性并减少了冗余。例如，常用组件如 etcd 和 ZooKeeper 的 ComponentDefinition 可以只定义一次，实现在多个 ClusterDefinition 中复用，从而简化新系统的设置。 + +此外，ClusterDefinition 还指定了组件的启动、升级和关闭顺序，确保组件生命周期的可控管理。 + +#### ComponentDefinition + +ComponentDefinition 是用于创建组件的可复用蓝图或模板，封装了组件描述、Pod 模板、配置文件模板、脚本、参数列表、环境变量及其来源、事件处理程序等必要的静态设置。ComponentDefinition 与 Component 的动态设置结合，在创建集群时实例化组件。 + +ComponentDefinition 可以定义的关键内容包括： + +- PodSpec 模板：指定组件使用的 PodSpec 模板。 +- 配置模板：指定组件所需的配置文件模板。 +- 脚本：提供管理组件所需的脚本。 +- 存储卷：指定组件的存储卷及其配置。 +- Pod 角色：定义组件内 Pod 的各种角色及其能力。 +- 暴露的 Kubernetes 服务：指定组件需要暴露的服务。 +- 系统账户：定义组件所需的系统账户。 + +ComponentDefinition 还支持定义组件对事件的响应行为，例如成员加入/离开、组件添加/删除、角色变更、切换等。这使得可以自动处理事件，从而封装组件的复杂行为。 + +## 插件（Addon）是什么 + +KubeBlocks 使用插件（Addon）机制来扩展对不同数据库引擎的支持。插件是某个特定数据库引擎的扩展，例如 MySQL Addon、PostgreSQL Addon、Redis Addon、MongoDB Addon 和 Kafka Addon。目前 KubeBlocks 提供了超过 30 种数据库引擎插件。 + +一个引擎插件包含基于 ClusterDefinition、ComponentDefinition 和 ComponentVersion CRD 的自定义资源（CR），以及一些 ConfigMap（用作配置模板或脚本文件模板）、脚本文件、定义备份和恢复操作的自定义资源和 Grafana 仪表板 JSON 对象。 + +KubeBlocks 的引擎插件将以 Helm chart 的形式打包和安装。用户安装某个数据库引擎插件后，可以在创建集群时引用该插件中包含的 ClusterDefinition CR 和 ComponentDefinition CR，从而创建相应数据库引擎的集群。 diff --git a/i18n/zh-cn/user-docs/overview/database-engines-supported.md b/i18n/zh-cn/user-docs/overview/database-engines-supported.md index e00546e788e..e69bd1eca4c 100644 --- a/i18n/zh-cn/user-docs/overview/database-engines-supported.md +++ b/i18n/zh-cn/user-docs/overview/database-engines-supported.md @@ -5,179 +5,203 @@ keywords: [kubeblocks, 简介, prometheus, s3, alertmanager] sidebar_position: 4 sidebar_label: 支持的数据库类型 --- + # 支持的数据库类型 -KubeBlocks 是基于 Kubernetes 的云原生数据基础设施，可以帮助用户轻松构建关系型、NoSQL、流计算和向量型数据库服务。而这些数据库类型通常以引擎（addon）的形式添加到 KubeBlocks 中。除了支持数据库引擎外，KubeBlocks 引擎还支持适配云环境的插件及其他应用。 - -| 数据库引擎 | 简介 | -|:----------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| apecloud-mysql | ApeCloud MySQL 是一个与 MySQL 语法兼容的数据库，主要利用 RAFT 共识协议实现高可用性。 | -| apecloud-postgresql | ApeCloud PostgreSQL 是一款兼容 PostgreSQL 语法，通过 RAFT 共识协议实现高可用的数据库。 | -| camellia-redis-proxy | Camellia Redis Proxy是使用 Netty4 开发的高性能 Redis 代理。 | -| clickhouse | ClickHouse 是列式数据库，能够帮助用户使用 SQL 查询实时生成强大的分析功能。 | -| elasticsearch | Elasticsearch 是一个分布式、RESTful 风格的搜索引擎，专为生产规模的工作负载进行了速度和相关性能的优化。 | -| etcd | etcd 是一个高度一致的分布式键值存储，它提供了一种可靠的方式来存储需要由分布式系统或机器集群访问的数据。 | -| flink | Apache Flink 是一个框架和分布式处理引擎，用于在无边界和有边界数据流上进行有状态的计算。 | -| foxlake | ApeCloud FoxLake 是一个开源的云原生数据仓库。| -| ggml | GGML 是一个为机器学习设计的张量库，它的目标是使大型模型能够在高性能的消费级硬件上运行。 | -| greptimedb | GreptimeDB 是一个云原生时间序列数据库，具有分布式、可扩展和高效的特性。 | -| influxdb | InfluxDB 作为专用的时序数据库，可执行实时分析，优化大型时序数据工作负载的处理和扩展。 ｜ -| kafka | Apache Kafka 是一个开源的分布式事件流平台，广泛应用于高性能数据流水线、流式分析、数据集成和关键应用程序等场景，目前已经被数千家公司采用。 | -| mariadb | MariaDB 是一个高性能的开源关系型数据库管理系统，广泛用于 Web 和应用服务器。 | -| milvus | Milvus 是一个灵活、可靠且高性能的云原生开源向量数据库。 | -| minio | MinIO 是对象存储解决方案，它提供与 Amazon Web Services S3 兼容的 API 并支持 S3 所有核心功能。 | -| mogdb | MogDB 是基于 openGauss 开源数据库、稳定、易用的企业级关系型数据库。 | -| mongodb | MongoDB 是一个面向文档的 NoSQL 数据库，用于存储大量数据。 | -| mysql | MySQL 是一个广泛使用的开源关系型数据库管理系统（RDBMS）。 | -| nebula | NebulaGraph 是一个开源的分布式图数据库，擅长处理具有千亿个顶点和万亿条边的超大规模数据集。 | -| neon | Neon 是一家多云无服务器 Postgres 提供商。| -| oceanbase | OceanBase 是一个无限可扩展的分布式数据库，适用于数据密集型事务和实时运营分析工作负载，具有超快的性能，在 TPC-C 基准测试中曾一度创造了世界纪录。OceanBase 已经为全球超过 400 家客户提供了服务，并且一直在支持支付宝的所有关键业务系统。 | -| official-postgresql | Kubernetes 的官方 PostgreSQL 集群定义 Helm Chart。 | -| opengauss | openGauss 是一款开源关系型数据库管理系统，采用木兰宽松许可证 v2 发行。 | -| openldap | OpenLDAP 项目旨在协作开发一个强大、商业级、功能齐全、开源的 LDAP 应用套件和开发工具。其 Chart 为 KubeBlocks 提供了支持。 | -| opensearch | opensearch 是一个开源、分布式、 RESTful 风格的搜索引擎。| -| oriolebd | OrioleDB 是 PostgreSQL 的全新存储引擎，为该数据库平台带来了现代化的数据库容量、功能和性能。 | -| pika | Pika 是一个可持久化的大容量 Redis 存储服务，兼容 string、hash、list、zset、set 的绝大部分接口。 | -| polardb-x | PolarDB-X 是一个为高并发、大规模存储和复杂查询场景设计的云原生分布式 SQL 数据库。| -| postgresql | PostgreSQL 是一个先进的企业级开源关系型数据库，支持 SQL（关系型）和 JSON（非关系型）查询。 | -| pulsar | Apache® Pulsar™ 是一个开源的、分布式消息流平台。 | -| qdrant | Qdrant 是一个向量相似性搜索引擎和向量数据库。 | -| redis | Redis 是一个开源的、高性能的、键值对内存数据库。 | -| risingwave | RisingWave 是一个分布式 SQL 流处理数据库，旨在帮助用户降低实时应用的开发复杂性和成本。| -| solr | Solr 是基于 Apache Lucene 构建的流行、高速的开源企业搜索平台。 | -| starrocks | StarRocks 是一款高性能分析型数据仓库，支持多维、实时、高并发的数据分析。| -| tidb | TiDB 是一个开源、云原生、分布式、兼容 MySQL 的数据库，用于弹性扩展和实时分析。 | -| tdengine | TDengine™ 是一个专为工业物联网而搭建的工业大数据平台，结合了时序数据库和流处理、数据订阅和缓存等重要功能。 | -| vllm | vLLM 是一个快速且易于使用的 LLM 推理和服务库。 | -| weaviate | Weaviate 是一个开源的向量数据库。 | -| xinference | Xorbits Inference（Xinference）是一个性能强大且功能全面的分布式推理框架。 | -| zookeeper | Apache ZooKeeper 是集中式服务，用于维护配置信息、命名、提供分布式同步以及提供组服务。 | -| zookeeper | Apache ZooKeeper 是一个集中式服务,用于维护配置信息、命名、提供分布式同步和提供组服务。 | - -## 数据库功能 - -| 数据库引擎 (v0.9.0) | 版本 | 垂直扩缩容 | 水平扩缩容 | 存储扩容 | 停止/启动 | 重启 | 备份/恢复 | 日志 | 配置 | 升级（内核小版本） | 账户 | 故障切换 | 切换 | 监控 | -|---------------------------------------|-----------------------------------|--------|--------|--------------|------------|---------|----------------|------|--------|-----------------------------|---------|----------|------------|---------| -| apecloud-mysql | 8.0.30 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |✔️ | ✔️ | ✔️ | N/A | ✔️ | ✔️ | ✔️ | ✔️ | -| apecloud-postgresql | 14.11 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| camellia-redis-proxy | 1.2.26 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | -| clickhouse | 22.9.4 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| elasticsearch | 8.8.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| etcd | 3.5.6 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| foxlake | 0.8.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| flink | 1.16 | ✔️ | ✔️ (task manager) | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| ggml | N/A | N/A | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| greptimedb | 0.3.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| halo | 0.2.0 | ✔️ | ✔️ | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| influxdb | 2.7.4 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| kafka | 3.3.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | N/A | N/A | N/A | ✔️ | -| mariadb | 10.6.15 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| milvus | 2.2.4 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| minio | 8.0.17 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| mogdb | 5.0.5 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | -| mongodb |

4.0

4.2

4.4

5.0

5.0.20

6.0

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | ✔️ | ✔️ | ✔️ | -| mysql |

5.7.42

8.0.33

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | ✔️ | ✔️ | ✔️ | -| nebula | 3.5.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| neon | latest | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| oceanbase | 4.2.0.0-100010032023083021 | N/A | ✔️ | ✔️ | N/A | N/A | | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| oceanbase-cluster | 4.2.0.0-100010032023083021 | ✔️ (host network) | ✔️ | ✔️ | ✔️ (host network) | ✔️ (host network) | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| official-postgresql |

12.15

14.7

14.7-zhparser

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| opengauss | 5.0.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| openldap | 2.4.57 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| opensearch | 2.7.0 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| oracle | 19.3.0-ee | ✔️ | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| orioledb | beta1 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| pika | 3.5.1 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| polardb-x | 2.3 | ✔️ | ✔️ | N/A | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | ✔️ | -| postgresql |

12.14.0

12.14.1

12.15.0

14.7.2

14.8.0

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| pulsar | 2.11.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | N/A | N/A | N/A | ✔️ | -| qdrant | 1.5.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | ✔️ | -| redis | 7.0.6 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | ✔️ | N/A | ✔️ | -| risingwave | 1.0.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| starrocks | 3.1.1 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| solr | 8.11.2 | ✔️ | ✔️ | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| tdengine | 3.0.5.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| tidb | 7.1.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| vllm | | N/A | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| weaviate | 1.18.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | N/A | N/A | N/A | ✔️ | -| xinference | 1.16.0 | ✔️ | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -| yashan | personal-23.1.1.100 | ✔️ | ✔️ (Standalone) | ✔️ | ✔️ | ✔️ | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | -| zookeeper | 3.7.1 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | +KubeBlocks 是基于 Kubernetes 的云原生数据基础设施，可以帮助用户轻松构建关系型、NoSQL、流计算和向量型数据库服务。而这些数据库类型通常以插件（Addon）的形式添加到 KubeBlocks 中。除了支持数据库引擎外，KubeBlocks 还支持适配云环境的插件及其他应用。 + +KubeBlocks 使用插件机制扩展对各种数据库引擎的支持，目前 KubeBlocks 存储库中提供了超过 30 个数据引擎插件，分类如下。 + +KubeBlocks 默认安装并启用了部分引擎插件，对于其他未安装或未启用的引擎，您可通过 [kbcli](./../installation/install-with-kbcli/install-addons.md) 或者 [Helm](./../installation/install-with-helm/install-addons.md) 安装和启用。 :::note -升级功能是指 KubeBlocks 支持数据库内核小版本升级，例如，将 PostgreSQL 从 v12.14 升级至 v12.15。 +- 以下表格中列出的版本可能不是最新版本，可通过 [KubeBlocks 引擎插件仓库](https://github.com/apecloud/kubeblocks-addons) 查看最新版本。 +- 升级功能是指 KubeBlocks 支持数据库内核小版本升级，例如，将 PostgreSQL 从 v12.14 升级至 v12.15。 ::: -## 使用引擎 +## 关系型数据库 + +MySQL 和 PostgreSQL 是两大最受欢迎的开源关系型数据库，有诸多分支/变体。 + +### MySQL 及其变体 + +**引擎列表** + +| 引擎 | 简介 | +|:----------------|:---------------------------------| +| mysql | MySQL Addon 采用了 Oracle 官方发布的社区版 MySQL 镜像。 | +| apecloud-mysql | ApeCloud MySQL 是免费的、完全兼容的 MySQL Community Edition 替代，通过 RAFT 协议复制插件提供增强高可用性。该镜像由 ApeCloud 提供。ApeCloud MySQL 还包括名为 WeScale 的开源代理，提供读写分离和连接池等功能。 | +| mariadb | MariaDB 是高性能的开源关系型数据库管理系统，广泛用于 Web 和应用服务器。 | + +**功能列表** + +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:------------------:|:------------------------------:|:-------------:|:----------------:|:-------:|:-------------:|:------------:|:------:|:-------:|:----:|:------:|:---------------:|:------:|:------:|:----------:|:----:| +| mysql |

5.7.44

8.0.33

8.4.2

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | ✔️ | ✔️ | ✔️ | +| apecloud-mysql |

8.0.30

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |✔️ | ✔️ | ✔️ | N/A | ✔️ | ✔️ | ✔️ | ✔️ | +| mariadb | 10.6.15 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | + +### PostgreSQL 及其变体 + +**引擎列表** + +| 引擎 | 简介 | +|:----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| postgresql | PostgreSQL Addon 使用 Spilo 镜像和 Patroni 提供 PostgreSQL 服务，以实现高可用性（HA）。 | +| apecloud-postgresql | ApeCloud PostgreSQL 是免费的、完全兼容的 PostgreSQL 替代，通过 RAFT 协议复制插件提供增强的高可用性。 | +| official-postgresql | 该 Addon 包含原版 PostgreSQL，采用 PostgreSQL 社区的官方版本，未经任何第三方供应商的修改、优化或打包。| +| oriolebd | OrioleDB 是 PostgreSQL 的全新存储引擎，为该数据库平台带来了现代化的数据库容量、功能和性能。 | +| neon | Neon 是 Serverless 版的 Postgres。 | + +**功能列表** -### 使用索引安装引擎 +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:----------------------------:|:-------------:|:-----------------:|:-------:|:-----------:|:----------------:|:------:|:-------:|:----:|:----:|:----------------:|:-------:|:------:|:----------:|:----:| +| postgresql |

12.14.0

12.14.1

12.15.0

14.7.2

14.8.0

15.7.0

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | + apecloud-postgresql | 14.11.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| official-postgresql | 14.7 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| orioledb | 14.7.2-beta1 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| neon |

neon-broker-1.0.0

neon-compute-1.0.0

neon-pageserver-1.0.0

neon-safekeeper-1.0.0

| ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | -KubeBlocks v0.8.0 发布后，引擎（addon）与 KubeBlocks 解耦，KubeBlocks 仅默认安装了部分引擎，如需体验其它引擎，需通过索引安装相关引擎。 +## NoSQL -官网引擎索引仓库为 [KubeBlocks index](https://github.com/apecloud/block-index)。引擎代码维护在 [KubeBlocks addon repo](https://github.com/apecloud/kubeblocks-addons)。 +**引擎列表** -1. 查看引擎仓库索引。 +| 引擎 | 简介 | +|:----------------|:-------------------------------------| +| mongodb | MongoDB 是面向文档的 NoSQL 数据库，用于存储大量数据。 | +| redis | Redis 是开源的、高性能的、键值对内存数据库。 | +| etcd | etcd 是高度一致的分布式键值存储，它提供了一种可靠的方式，存储需要由分布式系统或机器集群访问的数据。 | +| zookeeper | Apache ZooKeeper 是集中式服务，用于维护配置信息、命名、提供分布式同步以及提供组服务。 | - kbcli 默认创建名为 `kubeblocks` 的索引，可使用 `kbcli addon index list` 查看该索引。 +**功能列表** - ```bash - kbcli addon index list - > - INDEX URL - kubeblocks https://github.com/apecloud/block-index.git - ``` +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| mongodb |

4.0.28

4.2.24

4.4.29

5.0.28

6.0.16

7.0.12

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | ✔️ | ✔️ | ✔️ | +| redis |

redis-7.0.6

redis-7.2.4

redis-cluster-7.0.6

redis-cluster-7.2.4

redis-sentinel-7.0.6

redis-sentinel-7.2.4

redis-twemproxy-0.5.0

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | ✔️ | N/A | ✔️ | +| etcd |

3.5.15

3.5.6

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| zookeeper |

3.4.14

3.6.4

3.7.2

3.8.4

3.9.2

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | - 如果命令执行结果未显示或者你想要添加自定义索引仓库，则表明索引未建立，可使用 `kbcli addon index add ` 命令手动添加索引。例如， +## OLAP 系统 - ```bash - kbcli addon index add kubeblocks https://github.com/apecloud/block-index.git - ``` +**引擎列表** -2. （可选）索引建立后，可以通过 `addon search` 命令检查想要安装的引擎是否在索引信息中存在 +| 引擎 | 简介 | +|:----------------|:-----------------------------------------| +| elasticsearch | Elasticsearch 是一个分布式、RESTful 风格的搜索引擎，专为生产规模的工作负载进行了速度和相关性能的优化。 | +| starrocks-ce | StarRocks 是一款高性能分析型数据仓库，支持多维、实时、高并发的数据分析。 | +| clickhouse | ClickHouse 是列式数据库，能够帮助用户使用 SQL 查询实时生成强大的分析功能。 | +| opensearch | opensearch 是一个开源、分布式、 RESTful 风格的搜索引擎。 | - ```bash - kbcli addon search mariadb - > - ADDON VERSION INDEX - mariadb 0.7.0 kubeblocks - ``` +**功能列表** -3. 安装引擎。 +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| elasticsearch |

7.10.1

7.7.1

7.8.1

8.1.3

8.8.2

8.8.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| starrocks-ce |

starrocks-ce-be-3.2.2

starrocks-ce-be-3.3.0

starrocks-ce-fe-3.2.2

starrocks-ce-fe-3.3.0

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| clickhouse | 22.9.4 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| opensearch | 2.7.0 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | - 当引擎有多个版本和索引源时，可使用 `--index` 指定索引源，`--version` 指定安装版本。系统默认以 `kubeblocks` 索引仓库 为索引源，安装最新版本。 +## Distributed SQL Databases - ```bash - kbcli addon install mariadb --index kubeblocks --version 0.7.0 - ``` +**引擎列表** - **后续操作** +| 引擎 | 简介 | +|:----------------|:--------------------------------------------------| +| tidb | TiDB 是一个与 MySQL 兼容的分布式数据库，SQL 层采用 Go 语言开发，存储层基于 RocksDB，事务模型使用 Percolator。由 PingCap 提供。| +| oceanbase-ce | OceanBase 社区版是与 MySQL 兼容的分布式数据库，使用 C++ 开发。 | +| polardb-x | PolarDB-X 社区版是与 MySQL 兼容的分布式数据库，支持基于 MySQL 的水平伸缩，由阿里云提供，是其开源版本。 | - 引擎安装完成后，可查看引擎列表、启用引擎。 +**功能列表** -### 查看引擎列表 +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| tidb |

6.5.10

7.1.5

7.5.2

tidb-pd-6.5.10

tidb-pd-7.1.5

tidb-pd-7.5.2

tikv-6.5.10

tikv-7.1.5

tikv-7.5.2

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| oceanbase | 4.3.0 | N/A | ✔️ | ✔️ | N/A | N/A | | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| polardb-x | 2.3 | ✔️ | ✔️ | N/A | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | ✔️ | -执行 `kbcli addon list` 命令查看已经支持的引擎。 +## 消息队列 -### 启用/禁用引擎 +**引擎列表** -请按照以下步骤手动启用或禁用引擎。 +| 引擎 | 简介 | +|:----------------|:---------------------------------------------------------------------------------------------| +| kafka | Apache Kafka 是开源的分布式事件流平台，广泛应用于高性能数据流水线、流式分析、数据集成和关键应用程序等场景，目前已经被数千家公司采用。 | +| rabbitmq | RabbitMQ 是可靠且成熟的消息和流处理代理。 | +| pulsar | Apache Pulsar 是开源的、分布式消息流平台。 | -***步骤：*** +**功能列表** -1. 执行 `kbcli addon enable` 启用引擎。 +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| kafka |

kafka-broker-3.3.2

kafka-combine-3.3.2

kafka-controller-3.3.2

kafka-exporter-1.6.0

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | N/A | N/A | N/A | ✔️ | +| rabbitmq |

3.13.2

3.12.14

3.11.28

3.10.25

3.9.29

3.8.14

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | 由 RabbitMQ 管理系统管理 | ✔️ | ✔️ |✔️ | +| pulsar |

pulsar-bkrecovery-2.11.2

pulsar-bkrecovery-3.0.2

pulsar-bookkeeper-2.11.2

pulsar-bookkeeper-3.0.2

pulsar-broker-2.11.2

pulsar-broker-3.0.2

pulsar-proxy-2.11.2

pulsar-proxy-3.0.2

pulsar-zookeeper-2.11.2

pulsar-zookeeper-3.0.2

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | N/A | N/A | N/A | ✔️ | - ***示例*** +## 向量数据库 - ```bash - kbcli addon enable snapshot-controller - ``` +**引擎列表** - 执行 `kbcli addon disable` 禁用引擎。 +| 引擎 | 简介 | +|:----------------|:------------------------------------------------| +| qdrant | Qdrant 是向量相似性搜索引擎和向量数据库。 | +| weaviate | Weaviate 是开源的向量数据库。 | +| milvus | Milvus 是灵活、可靠且高性能的云原生开源向量数据库。 | + +**功能列表** + +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:---------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| qdrant |

1.10.0

1.5.0

1.7.3

1.8.1

1.8.4

| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | ✔️ | +| weaviate | 1.23.1 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | ✔️ | N/A | N/A | N/A | N/A | ✔️ | +| milvus | 2.3.2 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | + +## 时序数据库 + +**引擎列表** + +| 引擎 | 简介 | +|:----------------|:--------------------------------------------------------------------------------------------| +| influxdb | InfluxDB 作为专用的时序数据库，可执行实时分析，优化大型时序数据工作负载的处理和扩展。 | +| victoria-metrics | VictoriaMetrics 是快速、经济高效且可扩展的监控解决方案和时间序列数据库。 | +| greptimedb | GreptimeDB 是云原生时间序列数据库，具有分布式、可扩展和高效的特性。 | +| tdengine | TDengine™ 是专为工业物联网而搭建的工业大数据平台，结合了时序数据库和流处理、数据订阅和缓存等重要功能。 | + +**功能列表** + +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| influxdb | 2.7.4 | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| victoria-metrics | 1.0.0 | | | | | | | | | | | | | | | +| greptimedb | 0.3.2 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | +| tdengine | 3.0.5 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | + +## 图数据库 + +**引擎列表** + +| 引擎 | 简介 | +|:----------------|:------------------------------------------------------------------------------| +| nebula | NebulaGraph 是开源的分布式图数据库，擅长处理具有千亿个顶点和万亿条边的超大规模数据集。 | + +**功能列表** + +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:-------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:|:----------------:|:------------:|:----------------:|:----------------:|:------:|:--------------:|:----:|:------:|:---------------------------:|:-------:|:--------:|:----------:|:-------:| +| nebula | 3.5.0 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | + +## 存储系统 + +**引擎列表** + +| 引擎 | 简介 | +|:----------------|:-------| +| minio | MinIO 是对象存储解决方案，它提供与 Amazon Web Services S3 兼容的 API 并支持 S3 所有核心功能。 | -2. 再次查看引擎列表，检查是否已启用引擎。 +**功能列表** - ```bash - kbcli addon list - ``` +| 引擎（v0.9.0） | 已支持的版本 | 变配 | 水平伸缩 | 磁盘扩容 | 停止/启动集群 | 重启集群 | 服务暴露 | 备份恢复 | 日志 | 配置 | 升级（数据库引擎版本） | 账号管理 | 故障恢复 | Switchover | 监控 | +|:------------------:|:------------------------------:|:-----:|:---------:|:------:|:-------------:|:--------:|:------:|:-------:|:----:|:------:|:------------------:|:-------:|:------:|:----------:|:-------:| +| minio | RELEASE.2024-06-29T01-20-47Z | ✔️ | N/A | ✔️ | ✔️ | ✔️ | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | diff --git a/i18n/zh-cn/user-docs/overview/introduction.md b/i18n/zh-cn/user-docs/overview/introduction.md index 78c9e0b991d..2504d2359ac 100644 --- a/i18n/zh-cn/user-docs/overview/introduction.md +++ b/i18n/zh-cn/user-docs/overview/introduction.md @@ -5,30 +5,237 @@ keywords: [kubeblocks, 简介] sidebar_position: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # KubeBlocks 简介 ## KubeBlocks 是什么？ -KubeBlocks 是基于 Kubernetes 的云原生数据基础设施，将顶级云服务提供商的大规模生产经验与增强的可用性和稳定性改进相结合，帮助用户轻松构建容器化、声明式的关系型、NoSQL、流计算和向量型数据库服务。 +KubeBlocks 是一个开源的 Kubernetes 数据库 operator，能够帮助用户在 Kubernetes 上运行和管理多种类型的数据库。据我们所知，大多数数据库 operator 通常只能管理某种特定类型的数据库，例如： + +- CloudNativePG、Zalando、CrunchyData、StackGres operator 用于管理 PostgreSQL。 +- Strimzi 用于管理 Kafka。 +- Oracle 和 Percona MySQL operator 用于管理 MySQL。 + +而 KubeBlocks 是一个通用的数据库 operator。这意味着在设计 KubeBlocks API 时，我们并没有将其与某种特定类型的数据库绑定。恰恰相反，我们抽象了各种数据库的通用特性，最终得到了一个通用的、与数据库引擎无关的 API。因此，围绕这个抽象 API 开发的 operator 实现也与具体的数据库引擎无关。 + +![](./../../img/kubeblocks-general-purpose-arch.png) + +在上图中，Cluster、Component 和 InstanceSet 都是 KubeBlocks 提供的 CRD（自定义资源定义，Custom Resource Definition）。可参阅 [KubeBlocks 概念文档](./concept.md)，了解更多细节。 + +KubeBlocks 提供了插件（Addon）API，支持集成各种数据库。例如，我们目前提供了以下 KubeBlocks 引擎插件，支持各类主流开源数据库引擎： + +- MySQL +- PostgreSQL +- Redis +- MongoDB +- Kafka +- RabbitMQ +- MinIO +- Elasticsearch +- StarRocks +- Qdrant +- Milvus +- ZooKeeper +- etcd +- ... + +您可参阅 [KubeBlocks 支持的数据库引擎插件表格](./database-engines-supported.md)，查看支持的引擎及其功能的详细信息。 + +凭借统一的 API，KubeBlocks 成为在 Kubernetes 上运行多种数据库的绝佳选择，可显著降低掌握多个 operator 所需的学习门槛。 + +## 统一的 API 如何降低学习门槛 + +以下是使用 KubeBlocks Cluster API 编写 YAML 文件并创建一个 MySQL 三副本集群的示例。 + +```yaml +apiVersion: apps.kubeblocks.io/v1alpha1 +kind: Cluster +metadata: + name: test-mysql + namespace: default +spec: + terminationPolicy: Delete + componentSpecs: + - name: mysql + componentDef: apecloud-mysql + 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: 10Gi +``` + +然后，见证奇迹的时刻到了：只需对某些字段进行少量修改，就可以创建一个 PostgreSQL 两副本集群。同样的方法也适用于 MongoDB 和 Redis。Redis YAML 文件稍长一些，因为它创建了两个组件：redis-server 和 sentinel。而且这种方法可以适用于多种引擎。 + + + + + +```yaml +apiVersion: apps.kubeblocks.io/v1alpha1 +kind: Cluster +metadata: + name: test-postgresql + namespace: default +spec: + terminationPolicy: Delete + componentSpecs: + - name: postgresql + componentDef: postgresql + replicas: 2 + resources: + limits: + cpu: '0.5' + memory: 0.5Gi + requests: + cpu: '0.5' + memory: 0.5Gi + volumeClaimTemplates: + - name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +``` + + + + + +```yaml +apiVersion: apps.kubeblocks.io/v1alpha1 +kind: Cluster +metadata: + name: test-mongodb + namespace: default +spec: + terminationPolicy: Delete + componentSpecs: + - name: mongodb + componentDef: mongodb + 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: 10Gi +``` + + + + + +```yaml +apiVersion: apps.kubeblocks.io/v1alpha1 +kind: Cluster +metadata: + name: test-redis + namespace: default +spec: + terminationPolicy: Delete + componentSpecs: + - name: redis + componentDef: redis-7 + replicas: 2 + resources: + limits: + cpu: '0.5' + memory: 0.5Gi + requests: + cpu: '0.5' + memory: 0.5Gi + volumeClaimTemplates: + - name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + - name: redis-sentinel + componentDef: redis-sentinel + 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: 10Gi +``` + + + + + +统一的 API 意味着在 Kubernetes 上管理多种数据库变得简单、高效且标准化，这为您节省了大量原本需要花在查找手册和 API 参考文档上的时间。 + +## 关键特性 -KubeBlocks 的名字源自 Kubernetes（K8s）和乐高积木，致力于让 K8s 上的数据基础设施管理就像搭乐高积木一样，既高效又有趣。 +- 创建和销毁数据库集群。 +- 启动、停止和重启数据库集群。 +- 创建集群时，支持选择引擎插件提供的部署拓扑结构，例如，Redis 提供了基于 Sentinel 的读写分离或 Redis 集群拓扑；MySQL 提供了 Proxy 拓扑，可实现读写分离和高可用解决方案，如内置的 Raft 共识插件、外部 etcd 作为协调器，或 Orchestrator。 +- 支持在单个数据库集群中为多个副本分别配置不同的资源。例如，在一个 MySQL 集群中，主实例使用 8 个 CPU，而读副本使用 4 个 CPU。反观 Kubernetes 的 StatefulSet 则不支持这一能力。 +- 灵活的网络管理： + - 以动态的方式将数据库访问端点暴露为服务（ClusterIP、LoadBalancer、NodePort）。 + - 支持 HostNetwork。 + - 部分数据库支持通过 Smart Client 进行访问，该客户端会根据服务器返回的节点地址，将请求重新定向到其他节点或支持处理读写分离。Redis、MongoDB 及 Kafka 支持 Smart Client 访问模式。此外，部分数据库还支持实现副本间自动故障转移的客户端，如 etcd。对于这些数据库，KubeBlocks 还支持为每个 Pod （Pod Service）分配服务地址。 +- 支持丰富的 Day-2 运维操作： + - 水平伸缩（增加和减少副本数量） + - 变配（调整每个副本的 CPU 和内存资源） + - PVC 卷容量扩展 + - 备份和恢复功能 + - 配置变更（如果技术上存在可能，也支持热加载） + - 参数修改 + - 主备切换 + - 滚动升级 + - 指定副本下线 + - 小版本升级 +- 除了声明式 API 之外，KubeBlocks 还提供了 Ops API，用于在数据库集群上执行一次性运维任务。Ops API 还支持其他功能，如排队、并发控制、进度跟踪和操作回滚。 +- 可观测性：支持与 Prometheus 和 Grafana 集成。 +- KubeBlocks 提供了功能强大且直观的命令行工具 `kbcli`，使得在 Kubernetes 上操作 KubeBlocks CRs 更加简单，减少输入命令行的次数。对于熟悉 Kubernetes 的用户，也可以搭配 `kubectl` 使用 `kbcli`，用更简单的方式执行运维操作。 -## 为什么需要 KubeBlocks？ +## 部署架构 -Kubernetes 已经成为容器编排的事实标准。它利用 ReplicaSet 提供的可扩展性和可用性以及 Deployment 提供的推出和回滚功能来管理日益增加的无状态工作负载。然而，管理有状态工作负载给 Kubernetes 带来了巨大的挑战。尽管 StatefulSet 提供了稳定的持久存储和唯一的网络标识符，但这些功能对于复杂的有状态工作负载来说远远不够。 +下图展示了在云环境中部署 KubeBlocks 的典型架构图。 -为了应对这些挑战，并解决复杂性问题，KubeBlocks 引入了 ReplicationSet 和 ConsensusSet，具备以下能力： -- 基于角色的更新顺序可减少因升级版本、缩放和重新启动而导致的停机时间。 -- 维护数据复制的状态，并自动修复复制错误或延迟。 +Kubernetes 应部署在节点间可以通过网络相互通信的环境中（例如，在一个 VPC 内）。KubeBlocks operator 部署在专用的命名空间（kb-system）中，而数据库实例则部署在用户指定的命名空间中。 -## 主要功能 +在生产环境中，我们建议将 KubeBlocks operator 与数据库部署在不同的节点上（如果您也安装了Prometheus 和 Grafana，建议同样操作）。默认情况下，KubeBlocks 使用反亲和性规则调度数据库集群的多个副本，实现副本在不同节点上运行，以确保高可用性。用户还可以配置可用区（AZ）级别的反亲和性，以便将数据库副本分布在不同的可用区中，从而增强灾难恢复能力。 -- 支持多云，与 AWS、GCP、Azure、阿里云等云平台兼容。 -- 支持 MySQL、PostgreSQL、Redis、MongoDB、Kafka 等 32 个主流数据库和流计算引擎。 -- 提供生产级性能、弹性、可扩展性和可观察性。 -- 简化 day-2 操作，例如升级、扩展、监控、备份和恢复。 -- 包含强大且直观的命令行工具。 -- 仅需几分钟，即可建立一个适用于生产环境的完整数据基础设施。 +每个数据库副本在各自的 Pod 中运行。除了运行数据库进程的容器外，Pod 还包括几个辅助容器：一个名为 `lorry` 的容器（从 KubeBlocks v1.0 开始将更名为 kbagent），用于执行 KubeBlocks 控制器（controller）的 Action 命令；另一个名为 `config-manager` 的容器（从 KubeBlocks v1.0 开始会合并到 kbagent 中），用于管理数据库配置文件并支持热更新。此外，数据库引擎插件也可能会有一个 exporter 容器，用于收集 Prometheus 监控所需的指标。 -## 架构 -![KubeBlocks 架构图](./../../img/kubeblocks-architecture.png) +![KubeBlocks 架构图](./../../img/kubeblocks-architecture-ha.png) diff --git a/i18n/zh-cn/user-docs/overview/kubernetes_and_operator_101.md b/i18n/zh-cn/user-docs/overview/kubernetes_and_operator_101.md new file mode 100644 index 00000000000..93865d3b8e7 --- /dev/null +++ b/i18n/zh-cn/user-docs/overview/kubernetes_and_operator_101.md @@ -0,0 +1,117 @@ +--- +title: Kubernetes and Operator 101 +description: things about K8s you need to know +keywords: [K8s, operator, concept] +sidebar_position: 3 +--- + +# Kubernetes 及 Operator 入门 + +# K8s + +什么是 Kubernetes？有人说它是一个容器编排系统，有人称它为分布式操作系统，有人认为它是一个多云的 PaaS（平台即服务）平台，还有人把它看作是构建 PaaS 解决方案的平台。 + +本文将介绍 Kubernetes 的关键概念和构建模块。 + +## K8s 控制平面（Control Plane） + +Kubernetes 控制平面是 Kubernetes 的大脑和心脏。它负责管理整个集群的运行，包括处理 API 请求、存储配置数据以及确保集群处于期望的状态。关键组件包括 API 服务器（API Server，负责通信）、etcd（存储所有集群数据）、控制器管理器（Controller Manager，确保集群处于期望的状态）、调度器（Scheduler，将工作负载分配给节点）以及云控制器管理器（Cloud Controller Manager，管理与云平台的集成，如负载均衡、存储和网络）。这些组件共同协调容器在集群中的部署、扩展和管理。 + +## 节点（Node） + +有人将 Kubernetes 描述为一个分布式操作系统，能够管理多个节点。节点是集群中的物理或虚拟机器，作为集群中的工作单元。每个节点都运行一些核心服务，包括容器运行时（如 Docker 或 containerd）、kubelet 和 kube-proxy。kubelet 确保容器按 Pod 中的配置运行，而 Pod 是 Kubernetes 中最小的可部署单元。kube-proxy 处理网络路由，维护网络规则，并允许 Pod 和服务之间的通信。节点提供运行容器化应用所需的计算资源，并由 Kubernetes 主节点管理，主节点负责分配任务、监控节点健康状况并保持集群的期望状态。 + +:::note + +在某些语境中，同时讨论 Kubernetes 和数据库时，“节点”一词可能会产生混淆。在 Kubernetes 中，“节点”指的是集群中作为工作单元的物理或虚拟机器，用于运行容器化应用。而在 Kubernetes 中运行数据库时，“数据库节点”一般是指承载数据库实例的 Pod。 + +在 KubeBlocks 文档中，“节点”通常指的是数据库节点。如果我们指的是 Kubernetes 节点，我们将明确说明为“K8s 节点”以避免混淆。 + +::: + +## kubelet + +kubelet 是 Kubernetes 控制平面用于管理集群中每个节点的代理。它确保 Pod 中的容器按 Kubernetes 控制平面定义的方式运行。kubelet 持续监控容器的状态，确保它们健康且按预期运行。如果容器失败，kubelet 会根据指定的策略尝试重启它。 + +## Pod + +在 Kubernetes 中，Pod 在某种程度上类似于虚拟机，但更轻量和专用。它是 Kubernetes 中最小的可部署单元。 + +Pod 代表一个或多个紧密耦合且需要协同工作的容器，以及共享存储（卷）、网络资源和运行容器的规范。这些容器可以使用本地地址（localhost）进行相互通信，并共享内存和存储等资源。 + +Kubernetes 动态管理 Pods，确保它们按指定的方式运行，并在失败时自动重启或替换 Pods。Pods 可以分布在多个节点上以实现冗余，因此在 Kubernetes 中部署和管理容器化应用（包括数据库）时，Pods 是基础构件。 + +## 存储类（Storage Class） + +在为 Pod 内的工作负载（例如数据库）创建磁盘时，您可能需要指定磁盘介质的类型，无论是 HDD 还是 SSD。在云环境中，通常会有更多的选项可供选择。例如，AWS EBS 提供多种卷类型，如通用 SSD（gp2/gp3）、预配置 IOPS SSD（io1/io2）和优化吞吐量的 HDD（st1）。在 Kubernetes 中，您可以通过存储类（StorageClass）选择所需的磁盘类型。 + +## 持久卷声明（PVC） + +在 Kubernetes 中，持久卷声明（PVC，Persisten Volume Claim）是用户对存储的请求。PVC 本质上是请求具有特定特性的存储的一种方式，例如存储类、大小和访问模式（如读写或只读）。PVC 使 Pods 能够使用存储，而无需了解底层基础设施的详细信息。 + +在 K8s 中，为了使用存储，用户会创建 PVC。创建 PVC 时，Kubernetes 会查找与请求匹配的 StorageClass。如果找到匹配的 StorageClass，Kubernetes 将根据定义的参数自动配置存储，无论是 SSD、HDD、EBS 还是 NAS。如果 PVC 未指定 StorageClass，Kubernetes 将使用默认的 StorageClass（如果已配置）来配置存储。 + +## 容器存储接口（CSI） + +在 Kubernetes 中，通过容器存储接口（CSI，Container Storage Interface）提供各种存储类，CSI 负责为应用程序配置所需的底层存储“磁盘”。CSI 在 Kubernetes 中的功能类似于“磁盘驱动程序”，使平台能够适应并集成多种存储系统，如本地磁盘、AWS EBS 和 Ceph。这些存储类及其相关的存储资源由特定的 CSI 驱动程序提供，这些驱动程序处理与底层存储基础设施的交互。 + +CSI 是标准 API，使 Kubernetes 能够以一致和可扩展的方式与各种存储系统进行交互。由存储供应商或 Kubernetes 社区创建的 CSI 驱动程序向 Kubernetes 暴露了动态配置、附加、挂载和快照等基本存储功能。 + +当您在 Kubernetes 中定义一个 StorageClass 时，它通常会指定一个 CSI 驱动程序作为其配置器。这个驱动程序会根据 StorageClass 和相关持久卷声明（PVC）中的参数自动配置持久卷（PV），确保为您的应用程序提供适当类型和配置的存储，无论是 SSD、HDD 还是其他类型。 + +## 持久卷（PV） + +在 Kubernetes 中，持久卷（PV，Persisten Volume）代表可以由多种系统（如本地磁盘、NFS 或基于云的存储，例如 AWS EBS、Google Cloud Persistent Disks）支持的存储资源，通常由不同的 CSI 驱动程序管理。 + +PV 有自己独立于 Pod 的生命周期，由 Kubernetes 控制平面进行管理。即使关联的 Pod 被删除，PV 也允许数据持续存在。PV 与持久卷声明（PVC）绑定，PVC 请求特定的存储特性，如大小和访问模式，确保应用程序获得所需的存储。 + +总之，PV 是实际的存储资源，而 PVC 是对存储的请求。通过 PVC 中的 StorageClass，PVC 可以绑定到由不同 CSI 驱动程序配置的 PV。 + +## 服务（Service） + +在 Kubernetes 中，服务（Service）充当负载均衡器。它定义了一组逻辑上的 Pods，并提供了访问这些 Pods 的策略。由于 Pods 是短暂的，可能会动态创建和销毁，因此它们的 IP 地址并不稳定。服务通过提供一个稳定的网络端点（虚拟 IP 地址，称为 ClusterIP）解决了这个问题，该地址保持不变，使其他 Pods 或外部客户端能够与服务后面的 Pods 通信，而无需知道它们的具体 IP 地址。 + +服务支持不同类型：ClusterIP（内部集群访问）、NodePort（通过 `:` 进行外部访问）、LoadBalancer（使用云提供商的负载均衡器公开服务）、ExternalName（将服务映射到外部 DNS）。 + +## ConfigMap + +ConfigMap 用于以键值对的形式存储配置信息，通过 ConfigMap，您能够将配置与应用程序代码解耦。通过这种方式，您可以单独管理应用程序设置，并在多个环境中复用它们。ConfigMaps 可用于将配置数据注入到 Pods 中，作为环境变量、命令行参数或配置文件。它们提供了一种灵活且方便的方式来管理应用程序配置，而无需将值直接硬编码到您的应用程序容器中。 + +## Secret + +Secret 用于存储敏感数据，例如密码、令牌或加密密钥。Secrets 将机密信息与应用程序代码分开管理，避免在容器镜像中暴露敏感数据。Kubernetes Secrets 可以作为环境变量注入到 Pods 中，或作为文件挂载，确保以安全和受控的方式处理敏感信息。 + +但 Secrets 默认情况下并不加密，它们只是进行 Base64 编码，并不能提供真正的加密。因此，仍需谨慎使用，确保适当的访问控制到位。 + +## Custom Resource Definition (CRD) + +如果您希望使用 Kubernetes 管理数据库对象，则需要扩展 Kubernetes API，以描述您正在管理的数据库对象。这就是 CRD（Custom Resource Definition）机制的用途所在，CRD 支持定义特定用例的自定义资源，如数据库集群或备份，并以 K8s 原生的方式管理资源。 + +## 自定义资源（CR） + +自定义资源（CR，Custom Resource）是 CRD 的实例。它表示扩展 Kubernetes API 的特定配置或对象。CR 允许您使用 Kubernetes 的原生工具定义和管理自定义资源，例如数据库或应用程序。一旦创建了 CR，Kubernetes 控制器或 Operator 会开始监控，并执行操作以保持所需状态。 + +CRD 和 CR 是开发 Kubernetes Operator 的基础。CRDs 通常用于实现自定义控制器或 Operator，允许持续监视 CR 的变化（例如，表示数据库集群的 CR），并自动执行相应的操作。 + +## 什么是 Kubernetes Operator? + +Kubernetes Operator 是一种软件，通常由一个或多个控制器组成，自动管理复杂应用程序，通过将对面向定义资源（CR）所做的更改转换为面向 Kubernetes 原生对象（如 Pods、Services、PVCs、ConfigMaps 和 Secrets）的操作。 + +- 输入：用户修改 CR。 +- 输出：根据管理应用程序的要求，对应修改底层 Kubernetes 资源或与外部系统（例如，写入数据库或调用 API）。 + +Operator 持续监视这些 Kubernetes 对象的状态。当发生变化（例如，Pod 崩溃）时，Operator 会自动采取纠正措施，例如重新创建 Pod 或调整流量（例如，更新 Service Endpoints）。 + +本质上，Kubernetes Operator 将复杂的操作知识封装到软件中，自动化任务，如部署、扩展、升级和备份，确保应用程序在无需人工干预的情况下持续保持所需状态。 + +## Helm 和 Helm Chart + +Helm 是流行的 Kubernetes 包管理工具，帮助管理和部署应用程序。Helm 将所有必要的 Kubernetes 资源打包到 Helm Chart 中，支持通过单个命令（helm install）安装应用程序。Helm 还支持处理配置管理和更新（helm upgrade），简化应用程序的生命周期管理。 + +Helm Chart 的关键组件： + +- 模板（Templates）：包含占位符的 YAML 文件，定义 Kubernetes 资源（如 Pods、Services 和 ConfigMaps）。 +- values.yaml：用户可通过该 YAML 文件指定模板的默认值，用于自定义参数值。Helm 支持使用现有的 chart，通过 values.yaml 或命令行标志覆盖默认值，在不修改底层模板的情况下实现某种环境特定的配置。 +- Chart.yaml：chart 的元数据，包括名称、版本和描述。 + +Helm 可与 CI/CD 工具（如 Jenkins、GitLab CI 和 GitHub Actions）集成。Helm 可以作为持续交付管道的一部分，用于自动化部署和回滚，确保应用程序在不同环境中部署的一致性。 diff --git a/i18n/zh-cn/user-docs/upgrade/_category_.yml b/i18n/zh-cn/user-docs/upgrade/_category_.yml new file mode 100644 index 00000000000..5f2564e9d18 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/_category_.yml @@ -0,0 +1,4 @@ +position: 4 +label: 升级 +collapsible: true +collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/upgrade/faq.md b/i18n/zh-cn/user-docs/upgrade/faq.md new file mode 100644 index 00000000000..9717c323554 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/faq.md @@ -0,0 +1,109 @@ +--- +title: FAQ +description: 升级, faq +keywords: [升级, FAQ] +sidebar_position: 3 +sidebar_label: FAQ +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# FAQ + +本文档罗列了 KubeBlocks 升级中常见的问题及解决方法。 + +## 手动标记引擎 + +KubeBlocks 早期版本在 Helm chart 中预装了一些引擎，但在新版本中，部分预装引擎可能被移除。此时，如果基于早期版本直接升级至最新版本，这些被移除引擎的 CR 也会被 Helm 移除，这些引擎创建的数据库集群也将受到影响。因此，升级 KubeBlocks 时，可通过为引擎添加 `"helm.sh/resource-policy": "keep"` 注解，确保相关引擎在升级过程中不会被移除。 + +### 查看引擎注解 + +执行以下命令，查看引擎注解。 + +```bash +kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}' +``` + +### 手动为引擎添加注解 + +可以将以下命令中的 `-l app.kubernetes.io/name=kubeblocks` 替换为所需的筛选项。 + +```bash +kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep +``` + +如果想为某个引擎单独添加注解，可执行以下命令，替换 `{addonName}` 为需要的引擎。 + +```bash +kubectl annotate addons.extensions.kubeblocks.io {addonName} helm.sh/resource-policy=keep +``` + +如果想查看某个引擎是否成功添加了注解，可以执行以下命令，将 `{addonName}` 替换为需要的引擎。 + +```bash +kubectl get addon {addonName} -o json | jq '{name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}' +``` + +## 解决 "cannot patch 'kubeblocks-dataprotection' with kind Deployment" 问题 + +升级到 KubeBlocks v0.8.x/v0.9.0时，可能会出现以下报错： + +```bash +Error: UPGRADE FAILED: cannot patch "kubeblocks-dataprotection" with kind Deployment: Deployment.apps "kubeblocks-dataprotection" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/component":"dataprotection", "app.kubernetes.io/instance":"kubeblocks", "app.kubernetes.io/name":"kubeblocks"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable && cannot patch "kubeblocks" with kind Deployment: Deployment.apps "kubeblocks" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map[string]string{"app.kubernetes.io/component":"apps", "app.kubernetes.io/instance":"kubeblocks", "app.kubernetes.io/name":"kubeblocks"}, MatchExpressions:[]v1.LabelSelectorRequirement(nil)}: field is immutable +``` + +这是因为 KubeBlocks v0.9.1 修改了 KubeBlocks 和 KubeBlocks-Dataprotection 的标签。 + +如果出现这种错误，可以先手动删除 `kubeblocks` 和 `kubeblocks-dataprotection` 这两个 deployment，然后再执行 `helm upgrade` 升级到 KubeBlocks v0.9.1。 + +```bash +# Scale to 0 replica +kubectl -n kb-system scale deployment kubeblocks --replicas 0 +kubectl -n kb-system scale deployment kubeblocks-dataprotection --replicas 0 + +# Delete deployments +kubectl delete -n kb-system deployments.apps kubeblocks kubeblocks-dataprotection +``` + +## 升级时如何指定镜像仓库 + +KubeBlocks v0.8.x 使用的镜像仓库为 `infracreate-registry.cn-zhangjiakou.cr.aliyuncs.com` 和 `docker.io`，KubeBlocks 从 v0.9.0 之后使用的镜像仓库为 `apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com` 和 `docker.io`。 + +升级 KubeBlocks 时，可以通过以下参数指定修改默认镜像。 + + + + + +```bash +kbcli kb upgrade --version 0.9.1 \ + --set admissionWebhooks.enabled=true \ + --set admissionWebhooks.ignoreReplicasCheck=true \ + --set image.registry=docker.io \ + --set dataProtection.image.registry=docker.io \ + --set addonChartsImage.registry=docker.io +``` + + + + + +```bash +helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.1 \ + --set admissionWebhooks.enabled=true \ + --set admissionWebhooks.ignoreReplicasCheck=true \ + --set image.registry=docker.io \ + --set dataProtection.image.registry=docker.io \ + --set addonChartsImage.registry=docker.io +``` + + + + + +以下为上述命令的参数说明： + +- `--set image.registry=docker.io` 设置KubeBlocks 镜像仓库。 +- `--set dataProtection.image.registry=docker.io` 设置 KubeBlocks-Dataprotection 镜像仓库。 +- `--set addonChartsImage.registry=docker.io` 设置 addon Charts 镜像仓库。 diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/_category_.yml b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/_category_.yml new file mode 100644 index 00000000000..b6e93d21a72 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/_category_.yml @@ -0,0 +1,4 @@ +position: 2 +label: 使用 Helm 升级 +collapsible: true +collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.8.md b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.8.md new file mode 100644 index 00000000000..67abd22dc72 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.8.md @@ -0,0 +1,74 @@ +--- +title: 升级到 KubeBlocks v0.8 +description: 升级到 KubeBlocks v0.8, 升级操作 +keywords: [升级, 0.8] +sidebar_position: 3 +sidebar_label: 升级到 KubeBlocks v0.8 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 升级到 KubeBlocks v0.8 + +本文档介绍如何从低版本 KubeBlocks 升级至 KubeBlocks 0.8 版本。 + +:::note + +在升级前，请先执行 `helm -n kb-system list | grep kubeblocks` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 + +::: + +## 从 v0.7 升级 + +1. 设置 keepAddons。 + + KubeBlocks v0.8 精简了默认安装的引擎，将引擎从 KubeBlocks operator 分离到了 KubeBlocks 引擎插件代码仓库中，例如 greptime，influxdb，neon，oracle-mysql，orioledb，tdengine，mariadb，nebula，risingwave，starrocks，tidb，zookeeper。为避免升级时将已经在使用的引擎资源删除，请先执行如下命令。 + + - 查看当前 KubeBlocks 版本。 + + ```bash + helm -n kb-system list | grep kubeblocks + ``` + + - 查看并添加引擎注解。 + + 执行如下命令，查看引擎注解中是否添加了 `"helm.sh/resource-policy": "keep"`。 + + ```bash + kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}' + ``` + + 如果没有该注解，可以手动执行以下命令，为引擎添加注解。可以将 `-l app.kubernetes.io/name=kubeblocks` 替换为您所需的过滤条件。 + + ```bash + kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep + ``` + +2. 安装 CRD。 + + 为避免 KubeBlocks 的 Helm chart 过大，v0.8 版本将 CRD 从 Helm chart 中移除了，升级前需要先安装 CRD。 + + ```bash + kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.8.1/kubeblocks_crds.yaml + ``` + +3. 升级 KubeBlocks。 + + ```bash + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 + ``` + +:::note + +为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.8 时，默认不会升级已经安装的引擎版本。如果要将引擎升级至 KubeBlocks v0.8 内置引擎的版本，可以执行如下命令。注意，该操作可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + +```bash +helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set upgradeAddons=true +``` + +::: + +## FAQ + +可查看 [FAQ](./../faq.md)，了解并解决升级 KubeBlocks 过程中的常见问题。如果您还遇到了其他问题，可以[提交 issue](https://github.com/apecloud/kubeblocks/issues/new/choose) 或者在 [GitHub 讨论区](https://github.com/apecloud/kubeblocks/discussions)提交您的问题。 diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.9.1.md b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.9.1.md new file mode 100644 index 00000000000..e506f0aa6f0 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.9.1.md @@ -0,0 +1,167 @@ +--- +title: 升级到 KubeBlocks v0.9.1 +description: KubeBlocks v0.9.1 升级文档 +keywords: [升级, 0.9.1, Helm] +sidebar_position: 1 +sidebar_label: 升级到 KubeBlocks v0.9.1 +--- + +# 升级到 KubeBlocks v0.9.1 + +本文档将介绍如何升级至 KubeBlocks v0.9.1。 + +:::note + +在升级前，请先执行 `helm -n kb-system list | grep kubeblocks` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 + +::: + +## 兼容性说明 + +KubeBlocks v0.9.1 可以兼容 KubeBlocks v0.8 的 API，但不保证兼容 v0.8 之前版本的 API，如果您正在使用 KubeBlocks v0.7 或者更老版本的引擎（版本号为 `0.7.x`, `0.6.x`），请务必参考 [v0.8 升级文档](./upgrade-kubeblocks-to-0.8.md)将 KubeBlocks 升级至 v0.8 并将所有引擎升级至 0.8，以确保升级至 v0.9 版本后服务的可用性。 + +如果您是从 v0.8 升级到 v0.9，需要打开 webhook，以确保可用性。 + +## 从 v0.9.0 升级 + +1. 查看引擎，确认引擎是否已添加 `"helm.sh/resource-policy": "keep"` 注解。 + + KubeBlocks 对默认安装的引擎做了精简。添加 `"helm.sh/resource-policy": "keep"` 注解可以避免升级时删除已经在使用的引擎资源。 + + 查看引擎中是否添加了 `"helm.sh/resource-policy": "keep"`。 + + ```bash + kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}' + ``` + + 如果没有该注解，可以手动执行以下命令，为引擎添加注解。可以把 `-l app.kubernetes.io/name=kubeblocks` 替换为您所需的过滤条件。 + + ```bash + kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep + ``` + +2. 安装 CRD。 + + 为避免 KubeBlocks Helm Chart 过大，0.8 版本将 CRD 从 Helm Chart 中移除了，升级前需要先安装 CRD。 + + ```bash + kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.1/kubeblocks_crds.yaml + ``` + +3. 升级 KubeBlocks。 + + ```bash + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.1 --set crd.enabled=false + ``` + + KubeBocks v0.9 到 v0.9.1 的升级不涉及 API 变更，可通过设置 `--set crd.enabled=false` 跳过 API 升级任务。 + + :::warning + + 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9.1 时，默认不会升级已经安装的引擎版本，如果要升级引擎版本至 KubeBlocks v0.9.1 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + + ```bash + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.1 \ + --set upgradeAddons=true \ + --set crd.enabled=false + ``` + + ::: + +## 从 v0.8.x 升级 + +1. 查看引擎，确认引擎是否已添加 `"helm.sh/resource-policy": "keep"` 注解。 + + KubeBlocks 对默认安装的引擎做了精简。添加 `"helm.sh/resource-policy": "keep"` 注解可以避免升级时删除已经在使用的引擎资源。 + + 查看引擎中是否添加了 `"helm.sh/resource-policy": "keep"`。 + + ```bash + kubectl get addon -o json | jq '.items[] | {name: .metadata.name, resource_policy: .metadata.annotations["helm.sh/resource-policy"]}' + ``` + + 如果没有该注解，可以手动执行以下命令，为引擎添加注解。可以将 `-l app.kubernetes.io/name=kubeblocks` 替换为您所需的过滤条件。 + + ```bash + kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep + ``` + +2. 删除不兼容的 OpsDefinition。 + + ```bash + kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover + ``` + +3. 安装 CRD。 + + 为避免 KubeBlocks Helm Chart 过大，0.8 版本将 CRD 从 Helm Chart 中移除了，变更了 StorageProvider 的 group。升级前，需要先安装 StorageProvider CRD。 + + 如果网络较慢，建议先下载 CRD YAML 文件到本地，再执行操作。 + + ```bash + kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.1/dataprotection.kubeblocks.io_storageproviders.yaml + ``` + +4. 升级 KubeBlocks。 + + 如果您当前运行的 KubeBlocks 使用的镜像仓库为 `infracreate-registry.cn-zhangjiakou.cr.aliyuncs.com`，升级时请显式设置镜像仓库。 + + 设置 `admissionWebhooks.enabled=true` 将启动 webhook，用于 ConfigConstraint API 多版本转换。 + + 设置 `admissionWebhooks.ignoreReplicasCheck=true` 默认只有在 3 副本部署 KubeBlocks 时才可开启 webhook。若只部署单副本 KubeBlocks，可配置该变量跳过检查。 + + ```bash + helm repo add kubeblocks https://apecloud.github.io/helm-charts + + helm repo update kubeblocks + + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.1 \ + --set admissionWebhooks.enabled=true \ + --set admissionWebhooks.ignoreReplicasCheck=true + ``` + + :::warning + + 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9.1 时，默认不会升级已经安装的引擎版本，如果要升级引擎版本至 KubeBlocks v0.9.1 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + + ```bash + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.1 \ + --set upgradeAddons=true \ + --set admissionWebhooks.enabled=true \ + --set admissionWebhooks.ignoreReplicasCheck=true + ``` + + ::: + +## 升级引擎 + +如果您在上述步骤中，没有将 `upgradeAddons` 指定为 `true`，或者您想要使用的引擎不在默认列表中，但您想要使用 v0.9.1 API，可使用如下方式升级引擎。 + +:::note + +- 如果您想要升级的引擎是 `mysql`，您需要升级引擎并重启集群。否则使用 KubeBlocks v0.8.x 创建的集群将无法在 v0.9.1 中使用。 + +- 如果您想要升级 `clickhouse/milvus/elasticsearch/llm`，您需要先升级 KubeBlocks，再升级引擎，否在将无法在 v0.9.1 中正常使用。 + +::: + +```bash +# 添加 Helm 仓库 +helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts + +# 如果无法访问 Github 或者访问速度过慢，可使用以下仓库地址 +helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable + +# 更新 Helm 仓库 +helm repo update + +# 检索可用的引擎版本 +helm search repo kubeblocks-addons/{addon-name} --versions --devel + +# 更新引擎版本 +helm upgrade -i {addon-release-name} kubeblocks-addons/{addon-name} --version x.y.z -n kb-system +``` + +## FAQ + +可查看 [FAQ](./../faq.md)，了解并解决升级 KubeBlocks 过程中的常见问题。如果您还遇到了其他问题，可以[提交 issue](https://github.com/apecloud/kubeblocks/issues/new/choose) 或者在 [GitHub 讨论区](https://github.com/apecloud/kubeblocks/discussions)提交您的问题。 diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.9.md b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.9.md new file mode 100644 index 00000000000..c6bd479792e --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-helm/upgrade-kubeblocks-to-0.9.md @@ -0,0 +1,100 @@ +--- +title: 升级到 KubeBlocks v0.9 +description: 升级到 KubeBlocks v0.9, 升级操作 +keywords: [升级, 0.9] +sidebar_position: 2 +sidebar_label: 升级到 KubeBlocks v0.9 +--- + +# 升级到 KubeBlocks v0.9 + +本文档将介绍如何升级至 KubeBlocks v0.9。 + +:::note + +在升级前，请先执行 `helm -n kb-system list | grep kubeblocks` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 + +::: + +## 兼容性说明 + +KubeBlocks 0.9 可以兼容 KubeBlocks 0.8 的 API，但不保证兼容 0.8 之前版本的 API，如果您正在使用 KubeBlocks 0.7 或者更老版本的引擎（版本号为 `0.7.x`, `0.6.x`），请务必参考 [0.8 升级文档](./upgrade-kubeblocks-to-0.8.md)将 KubeBlocks 升级至 0.8 并将所有引擎升级至 0.8，以确保升级至 0.9 版本后服务的可用性。 + +## 从 v0.8 版本升级 + +1. 为引擎添加 `"helm.sh/resource-policy": "keep"` 注解。 + + KubeBlocks v0.8 对默认安装的引擎做了精简。添加 `"helm.sh/resource-policy": "keep"` 注解可以避免升级时删除已经在使用的引擎资源。 + + 执行以下命令，为引擎添加 `"helm.sh/resource-policy": "keep"` 注解。可以将 `-l app.kubernetes.io/name=kubeblocks` 替换为您所需的过滤条件。 + + ```bash + kubectl annotate addons.extensions.kubeblocks.io -l app.kubernetes.io/name=kubeblocks helm.sh/resource-policy=keep + ``` + + 查看引擎中是否已包含 `"helm.sh/resource-policy": "keep"`。 + + ```bash + kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}' + ``` + +2. 删除不兼容的 OpsDefinition。 + + ```bash + kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover + ``` + +3. 安装 StorageProvider CRD。 + + 如果网络较慢，建议先下载 CRD YAML 文件到本地，再执行操作。 + + ```shell + kubectl create -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.0/dataprotection.kubeblocks.io_storageproviders.yaml + ``` + +4. 升级 KubeBlocks。 + + ```shell + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.0 + ``` + + :::note + + 避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9 时，默认不会升级已经安装的引擎版本，如果要将引擎版本至 KubeBlocks v0.9 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + + ```bash + helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.0 \ + --set upgradeAddons=true + ``` + + ::: + +## 升级引擎 + +为了使用 v0.9.0 的 API，如果在上述步骤中，没有指定 `upgradeAddons`，或者您的引擎不在默认引擎列表里，可使用如下方式升级引擎。 + +:::note + +- 如果您使用的引擎是 MySQL, 需要升级引擎并重启集群，否则 KubeBlocks v0.8 创建的集群将无法在 v0.9 中使用。 + +- 如果您要使用 `clickhouse/milvus/elasticsearch/llm` 等引擎，需要升级 KubeBlocks 之后，再升级引擎，否则无法在 v0.9 正常使用。 + +::: + +```bash +# 添加 Helm 仓库 +helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts + +# 如果无法访问 Github 或者访问速度过慢，可使用以下仓库地址 +helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable + +# 更新 Helm 仓库 +helm repo update + +# 升级引擎 +helm upgrade -i xxx kubeblocks-addons/xxx --version x.y.z -n kb-system +``` + +## FAQ + +可查看 [FAQ](./../faq.md)，了解并解决升级 KubeBlocks 过程中的常见问题。如果您还遇到了其他问题，可以[提交 issue](https://github.com/apecloud/kubeblocks/issues/new/choose) 或者在 [GitHub 讨论区](https://github.com/apecloud/kubeblocks/discussions)提交您的问题。 diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/_category_.yml b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/_category_.yml new file mode 100644 index 00000000000..350ccca36e6 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/_category_.yml @@ -0,0 +1,4 @@ +position: 1 +label: 使用 kbcli 升级 +collapsible: true +collapsed: true \ No newline at end of file diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.8.md b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.8.md new file mode 100644 index 00000000000..377c82cece1 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.8.md @@ -0,0 +1,58 @@ +--- +title: 升级到 KubeBlocks v0.8 +description: 如何升级到 KubeBlocks v0.8 +keywords: [升级, 0.8] +sidebar_position: 3 +sidebar_label: 升级到 KubeBlocks v0.8 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 升级到 KubeBlocks v0.8 + +本文档介绍如何从低版本 KubeBlocks 升级至 KubeBlocks 0.8 版本。 + +:::note + +在升级前，请先执行 `kbcli version` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 + +::: + +## 从 v0.6 版本升级 + +如果当前使用的是 KubeBlocks v0.6 版本，请先将 KubeBlocks 升级至 v0.7.2 版本，操作如下： + +1. 下载 kbcli v0.7.2 版本。 + + ```shell + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.7.2 + ``` + +2. 升级至 KubeBlocks v0.7.2。 + + ```shell + kbcli kb upgrade --version 0.7.2 + ``` + +## 从 v0.7 版本升级 + +1. 下载 kbcli v0.8 版本。 + + ```shell + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.8.1 + ``` + +2. 升级 KubeBlocks。 + + ```shell + + kbcli kb upgrade --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 + + ``` + + kbcli 会默认为已有 addon 添加 annotation `"helm.sh/resource-policy": "keep"`，确保升级过程中已有的 addon 不会被删除。 + +## FAQ + +可查看 [FAQ](./../faq.md)，了解并解决升级 KubeBlocks 过程中的常见问题。如果您还遇到了其他问题，可以[提交 issue](https://github.com/apecloud/kubeblocks/issues/new/choose) 或者在 [GitHub 讨论区](https://github.com/apecloud/kubeblocks/discussions)提交您的问题。 diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.9.1.md b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.9.1.md new file mode 100644 index 00000000000..c8d41960997 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.9.1.md @@ -0,0 +1,127 @@ +--- +title: 升级到 KubeBlocks v0.9.1 +description: KubeBlocks v0.9.1 升级文档 +keywords: [升级, 0.9.1, kbcli] +sidebar_position: 1 +sidebar_label: 升级到 KubeBlocks v0.9.1 +--- + +# 升级到 KubeBlocks v0.9.1 + +本文档将介绍如何升级至 KubeBlocks v0.9.1。 + +:::note + +在升级前，请先执行 `kbcli version` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 + +::: + +## 兼容性说明 + +KubeBlocks v0.9.1 可以兼容 KubeBlocks v0.8 的 API，但不保证兼容 v0.8 之前版本的 API，如果您正在使用 KubeBlocks v0.7 或者更老版本的引擎（版本号为 `0.7.x`, `0.6.x`），请务必参考 [v0.8 升级文档](./upgrade-kubeblocks-to-0.8.md)将 KubeBlocks 升级至 v0.8 并将所有引擎升级至 v0.8，以确保升级至 v0.9 版本后服务的可用性。 + +如果您是从 v0.8 升级到 v0.9，需要打开 webhook，以确保可用性。 + +## 从 v0.9.0 升级 + +1. 下载 kbcli v0.9.1。 + + ```bash + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.9.1 + ``` + +2. 升级 KubeBlocks。 + + ```bash + kbcli kb upgrade --version 0.9.1 + ``` + + :::warning + + 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9.1 时，默认不会升级已经安装的引擎版本，如果要升级引擎版本至 KubeBlocks v0.9.1 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + + ```bash + kbcli kb upgrade --version 0.9.1 --set upgradeAddons=true + ``` + + ::: + + kbcli 会默认为已有引擎添加 `"helm.sh/resource-policy": "keep"` 注解，确保升级过程中已有引擎不会被删除。 + +## 从 v0.8.x 升级 + +1. 下载 kbcli v0.9.1。 + + ```bash + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.9.1 + ``` + +2. 升级 KubeBlocks。 + + 查看 kbcli 版本，确保您使用的 kbcli 版本为 v0.9.1。 + + ```bash + kbcli version + ``` + + 如果您当前运行的 KubeBlocks 使用的镜像仓库为 `infracreate-registry.cn-zhangjiakou.cr.aliyuncs.com`，升级时请显式设置镜像仓库。 + + ```bash + kbcli kb upgrade --version 0.9.1 \ + --set admissionWebhooks.enabled=true \ + --set admissionWebhooks.ignoreReplicasCheck=true + ``` + + :::warning + + 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9.1 时，默认不会升级已经安装的引擎版本，如果要升级引擎版本至 KubeBlocks v0.9.1 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + + ```bash + kbcli kb upgrade --version 0.9.1 \ + --set upgradeAddons=true \ + --set admissionWebhooks.enabled=true \ + --set admissionWebhooks.ignoreReplicasCheck=true + ``` + + ::: + + kbcli 会默认为已有引擎添加 `"helm.sh/resource-policy": "keep"` 注解，确保升级过程中已有引擎不会被删除。 + +## 升级引擎 + +如果您在上述步骤中，没有将 `upgradeAddons` 指定为 `true`，或者您想要使用的引擎不在默认列表中，但您想要使用 v0.9.1 API，可使用如下方式升级引擎。 + +:::note + +- 如果您想要升级的引擎是 `mysql`，您需要升级引擎并重启集群。否则使用 KubeBlocks v0.8.x 创建的集群将无法在 v0.9.1 中使用。 + +- 如果您想要升级 `clickhouse/milvus/elasticsearch/llm`，您需要先升级 KubeBlocks，再升级引擎，否在将无法在 v0.9.1 中正常使用。 + +::: + +```bash +# 查看引擎索引列表 +kbcli addon index list + +# 更新某一个索引， 默认的是 kubeblocks +kbcli addon index update kubeblocks + +# 检索可用的引擎版本 +kbcli addon search {addon-name} + +# 安装引擎 +kbcli addon install {addon-name} --version x.y.z + +# 更新引擎到指定版本 +kbcli addon upgrade {addon-name} --version x.y.z + +# 强制更新引擎到指定版本 +kbcli addon upgrade {addon-name} --version x.y.z --force + +# 查看指定引擎版本 +kbcli addon list | grep {addon-name} +``` + +## FAQ + +可查看 [FAQ](./../faq.md)，了解并解决升级 KubeBlocks 过程中的常见问题。如果您还遇到了其他问题，可以[提交 issue](https://github.com/apecloud/kubeblocks/issues/new/choose) 或者在 [GitHub 讨论区](https://github.com/apecloud/kubeblocks/discussions)提交您的问题。 diff --git a/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.9.md b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.9.md new file mode 100644 index 00000000000..69df837e013 --- /dev/null +++ b/i18n/zh-cn/user-docs/upgrade/upgrade-with-kbcli/upgrade-kubeblocks-to-0.9.md @@ -0,0 +1,89 @@ +--- +title: 升级到 KubeBlocks v0.9 +description: 如何升级到 KubeBlocks v0.9 +keywords: [升级, 0.9] +sidebar_position: 2 +sidebar_label: 升级到 KubeBlocks v0.9 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 升级到 KubeBlocks v0.9 + +本文档介绍如何将 KubeBlocks 升级至 KubeBlocks 0.9 版本。 + +:::note + +在升级前，请先执行 `kbcli version` 查看正在使用的 KubeBlocks 版本，并根据不同版本，执行升级操作。 + +::: + +## 兼容性说明 + +KubeBlocks v0.9 可以兼容 KubeBlocks v0.8 的 API，但不保证兼容 v0.8 之前版本的 API，如果您正在使用 KubeBlocks v0.7 或者更老版本的引擎（版本号为 `0.7.x`, `0.6.x`），请务必参考 [v0.8 升级文档](./upgrade-kubeblocks-to-0.8.md)将 KubeBlocks 升级至 v0.8 并将所有引擎升级至 v0.8，以确保升级至 v0.9 后服务的可用性。 + +## 从 0.8 版本升级 + +1. 下载 kbcli v0.9.0。 + + ```shell + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.9.0 + ``` + +2. 升级 KubeBlocks。 + + ```bash + kbcli kb upgrade --version 0.9.0 + ``` + + :::note + + 为避免影响已有的数据库集群，升级 KubeBlocks 至 v0.9 时，默认不会升级已经安装的引擎版本，如果要升级引擎版本至 KubeBlocks v0.9 内置引擎的版本，可以执行如下命令，这可能导致已有集群发生重启，影响可用性，请务必谨慎操作。 + + ```bash + kbcli kb upgrade --version 0.9.0 --set upgradeAddons=true + ``` + + ::: + + kbcli 会默认为已有引擎添加 `"helm.sh/resource-policy": "keep"` 注解，确保升级过程中已有引擎不会被删除。 + +## 升级引擎 + +如果您在上述步骤中，没有将 `upgradeAddons` 指定为 `true`，或者您想要使用的引擎不在默认列表中，但您想要使用 v0.9.0 API，可使用如下方式升级引擎。 + +:::note + +- 如果您想要升级的引擎是 `mysql`，您需要升级引擎并重启集群。否则使用 KubeBlocks v0.8 创建的集群将无法在 v0.9 中使用。 + +- 如果您想要升级 `clickhouse/milvus/elasticsearch/llm`，您需要先升级 KubeBlocks，再升级引擎，否在将无法在 v0.9 中正常使用。 + +::: + +```bash +# 查看引擎索引列表 +kbcli addon index list + +# 更新某一个索引， 默认的是 kubeblocks +kbcli addon index update kubeblocks + +# 检索可用的引擎版本 +kbcli addon search {addon-name} + +# 安装引擎 +kbcli addon install {addon-name} --version x.y.z + +# 更新引擎到指定版本 +kbcli addon upgrade {addon-name} --version x.y.z + +# 强制更新引擎到指定版本 +kbcli addon upgrade {addon-name} --version x.y.z --force + +# 查看指定引擎版本 +kbcli addon list | grep {addon-name} +``` + +## FAQ + +可查看 [FAQ](./../faq.md)，了解并解决升级 KubeBlocks 过程中的常见问题。如果您还遇到了其他问题，可以[提交 issue](https://github.com/apecloud/kubeblocks/issues/new/choose) 或者在 [GitHub 讨论区](https://github.com/apecloud/kubeblocks/discussions)提交您的问题。 diff --git a/pkg/controller/plan/tls_utils.go b/pkg/controller/plan/tls_utils.go index dc54213dc97..63f60dee1e2 100644 --- a/pkg/controller/plan/tls_utils.go +++ b/pkg/controller/plan/tls_utils.go @@ -109,12 +109,12 @@ func CheckTLSSecretRef(ctx context.Context, cli client.Reader, namespace string, if err := cli.Get(ctx, types.NamespacedName{Namespace: namespace, Name: secretRef.Name}, secret); err != nil { return err } - if secret.StringData == nil { + if secret.Data == nil { return errors.New("tls secret's data field shouldn't be nil") } keys := []string{secretRef.CA, secretRef.Cert, secretRef.Key} for _, key := range keys { - if _, ok := secret.StringData[key]; !ok { + if len(secret.Data[key]) == 0 { return errors.Errorf("tls secret's data[%s] field shouldn't be empty", key) } } diff --git a/pkg/controller/plan/tls_utils_test.go b/pkg/controller/plan/tls_utils_test.go index db9cc87b2a9..1ddea11b3a8 100644 --- a/pkg/controller/plan/tls_utils_test.go +++ b/pkg/controller/plan/tls_utils_test.go @@ -85,29 +85,17 @@ var _ = Describe("TLSUtilsTest", func() { err := CheckTLSSecretRef(ctx, k8sMock, namespace, secretRef) Expect(apierrors.IsNotFound(err)).Should(BeTrue()) - By("set stringData to nil") + By("set empty CA in map Data") k8sMock.EXPECT(). Get(gomock.Any(), gomock.Any(), &corev1.Secret{}, gomock.Any()). DoAndReturn(func(_ context.Context, objKey client.ObjectKey, obj *corev1.Secret, _ ...client.GetOption) error { Expect(obj).ShouldNot(BeNil()) obj.Namespace = objKey.Namespace obj.Name = objKey.Name - return nil - }).Times(1) - err = CheckTLSSecretRef(ctx, k8sMock, namespace, secretRef) - Expect(err).ShouldNot(BeNil()) - Expect(err.Error()).Should(ContainSubstring("tls secret's data field shouldn't be nil")) - - By("set no CA key in map stringData") - k8sMock.EXPECT(). - Get(gomock.Any(), gomock.Any(), &corev1.Secret{}, gomock.Any()). - DoAndReturn(func(_ context.Context, objKey client.ObjectKey, obj *corev1.Secret, _ ...client.GetOption) error { - Expect(obj).ShouldNot(BeNil()) - obj.Namespace = objKey.Namespace - obj.Name = objKey.Name - obj.StringData = map[string]string{ - secretRef.Cert: "foo", - secretRef.Key: "bar", + obj.Data = map[string][]byte{ + secretRef.Cert: []byte("foo"), + secretRef.Key: []byte("bar"), + secretRef.CA: []byte(""), } return nil }).Times(1) @@ -122,10 +110,10 @@ var _ = Describe("TLSUtilsTest", func() { Expect(obj).ShouldNot(BeNil()) obj.Namespace = objKey.Namespace obj.Name = objKey.Name - obj.StringData = map[string]string{ - secretRef.Cert: "foo", - secretRef.Key: "bar", - secretRef.CA: "ca", + obj.Data = map[string][]byte{ + secretRef.Cert: []byte("foo"), + secretRef.Key: []byte("bar"), + secretRef.CA: []byte("ca"), } return nil }).Times(1) diff --git a/pkg/operations/custom.go b/pkg/operations/custom.go index ffc1e19af83..e8aab5e30a0 100644 --- a/pkg/operations/custom.go +++ b/pkg/operations/custom.go @@ -292,6 +292,21 @@ func resolveParameterValue(ctx context.Context, return "", nil } +func validateAndGetCompSpec(cluster *appsv1.Cluster, opsDef *opsv1alpha1.OpsDefinition, componentName string) (*appsv1.ClusterComponentSpec, error) { + compSpec := cluster.Spec.GetComponentByName(componentName) + if compSpec != nil { + return compSpec, nil + } + shardingSpec := cluster.Spec.GetShardingByName(componentName) + if shardingSpec == nil { + return nil, intctrlutil.NewFatalError(fmt.Sprintf(`cannot found the component "%s" in cluster "%s"`, componentName, cluster.Name)) + } + if len(opsDef.Spec.PodInfoExtractors) == 0 { + return nil, intctrlutil.NewFatalError(fmt.Sprintf(`podInfoExtractors cannot be empty in opsDef "%s" when the component "%s" is a shard component`, opsDef.Name, componentName)) + } + return &shardingSpec.Template, nil +} + // initOpsDefAndValidate inits the opsDefinition to OpsResource and validates if the opsRequest is valid. func initOpsDefAndValidate(reqCtx intctrlutil.RequestCtx, cli client.Client, @@ -305,31 +320,33 @@ func initOpsDefAndValidate(reqCtx intctrlutil.RequestCtx, return err } opsRes.OpsDef = opsDef - // 1. validate OpenApV3Schema + parametersSchema := opsDef.Spec.ParametersSchema - if parametersSchema == nil { - return nil - } for _, v := range customSpec.CustomOpsComponents { - paramsMap, err := covertParametersToMap(reqCtx.Ctx, cli, v.Parameters, opsRes.OpsRequest.Namespace) - if err != nil { - return err - } - // covert to type map[string]interface{} - params, err := common.CoverStringToInterfaceBySchemaType(parametersSchema.OpenAPIV3Schema, paramsMap) - if err != nil { - return intctrlutil.NewFatalError(err.Error()) - } - if parametersSchema != nil && parametersSchema.OpenAPIV3Schema != nil { - if err = common.ValidateDataWithSchema(parametersSchema.OpenAPIV3Schema, params); err != nil { + // 1. validate OpenApV3Schema + if parametersSchema != nil { + paramsMap, err := covertParametersToMap(reqCtx.Ctx, cli, v.Parameters, opsRes.OpsRequest.Namespace) + if err != nil { + return err + } + // covert to type map[string]interface{} + params, err := common.CoverStringToInterfaceBySchemaType(parametersSchema.OpenAPIV3Schema, paramsMap) + if err != nil { return intctrlutil.NewFatalError(err.Error()) } + if parametersSchema != nil && parametersSchema.OpenAPIV3Schema != nil { + if err = common.ValidateDataWithSchema(parametersSchema.OpenAPIV3Schema, params); err != nil { + return intctrlutil.NewFatalError(err.Error()) + } + } } - // 2. validate component and componentDef + compSpec, err := validateAndGetCompSpec(opsRes.Cluster, opsDef, v.ComponentName) + if err != nil { + return err + } if len(opsRes.OpsDef.Spec.ComponentInfos) > 0 { // get component definition - compSpec := getComponentSpecOrShardingTemplate(opsRes.Cluster, v.ComponentName) compDef, err := component.GetCompDefByName(reqCtx.Ctx, cli, compSpec.ComponentDef) if err != nil { return err diff --git a/pkg/operations/custom/utils.go b/pkg/operations/custom/utils.go index 22e4fadcca3..8b7e1fcdb32 100644 --- a/pkg/operations/custom/utils.go +++ b/pkg/operations/custom/utils.go @@ -58,15 +58,16 @@ func buildComponentEnvs(reqCtx intctrlutil.RequestCtx, cluster *appsv1.Cluster, opsDef *opsv1alpha1.OpsDefinition, env *[]corev1.EnvVar, - comp *appsv1.ClusterComponentSpec) error { + comp *appsv1.ClusterComponentSpec, + componentName string) error { // inject built-in component env - fullCompName := constant.GenerateClusterComponentName(cluster.Name, comp.Name) + fullCompName := constant.GenerateClusterComponentName(cluster.Name, componentName) *env = append(*env, []corev1.EnvVar{ {Name: constant.KBEnvClusterName, Value: cluster.Name}, - {Name: constant.KBEnvCompName, Value: comp.Name}, + {Name: constant.KBEnvCompName, Value: componentName}, {Name: constant.KBEnvClusterCompName, Value: fullCompName}, {Name: constant.KBEnvCompReplicas, Value: strconv.Itoa(int(comp.Replicas))}, - {Name: kbEnvCompHeadlessSVCName, Value: constant.GenerateDefaultComponentHeadlessServiceName(cluster.Name, comp.Name)}, + {Name: kbEnvCompHeadlessSVCName, Value: constant.GenerateDefaultComponentHeadlessServiceName(cluster.Name, componentName)}, }...) if len(opsDef.Spec.ComponentInfos) == 0 { return nil @@ -95,7 +96,7 @@ func buildComponentEnvs(reqCtx intctrlutil.RequestCtx, } // inject connect envs if componentInfo.AccountName != "" { - accountSecretName := constant.GenerateAccountSecretName(cluster.Name, comp.Name, componentInfo.AccountName) + accountSecretName := constant.GenerateAccountSecretName(cluster.Name, componentName, componentInfo.AccountName) *env = append(*env, corev1.EnvVar{Name: kbEnvAccountUserName, Value: componentInfo.AccountName}) *env = append(*env, corev1.EnvVar{Name: kbEnvAccountPassword, ValueFrom: buildSecretKeyRef(accountSecretName, constant.AccountPasswdForSecret)}) } @@ -106,7 +107,7 @@ func buildComponentEnvs(reqCtx intctrlutil.RequestCtx, if v.Name != componentInfo.ServiceName { continue } - *env = append(*env, corev1.EnvVar{Name: kbEnvCompSVCName, Value: constant.GenerateComponentServiceName(cluster.Name, comp.Name, v.ServiceName)}) + *env = append(*env, corev1.EnvVar{Name: kbEnvCompSVCName, Value: constant.GenerateComponentServiceName(cluster.Name, componentName, v.ServiceName)}) for _, port := range v.Spec.Ports { portName := strings.ReplaceAll(port.Name, "-", "_") *env = append(*env, corev1.EnvVar{Name: kbEnvCompSVCPortPrefix + strings.ToUpper(portName), Value: strconv.Itoa(int(port.Port))}) @@ -252,8 +253,16 @@ func buildActionPodEnv(reqCtx intctrlutil.RequestCtx, Value: ops.Namespace, }, } + + componentName := compCustomItem.ComponentName + if targetPod != nil { + // "component" might be a shard component and the name is logical. + // we should get the real component name from the pod labels. + componentName = targetPod.Labels[constant.KBAppComponentLabelKey] + } + // inject component and componentDef envs - if err := buildComponentEnvs(reqCtx, cli, cluster, opsDef, &env, comp); err != nil { + if err := buildComponentEnvs(reqCtx, cli, cluster, opsDef, &env, comp, componentName); err != nil { return nil, err } @@ -338,7 +347,7 @@ func getTargetPods( if cluster.Spec.GetShardingByName(compName) != nil { // get pods of the sharding components podList := &corev1.PodList{} - labels := constant.GetClusterLabels(cluster.Namespace) + labels := constant.GetClusterLabels(cluster.Name) labels[constant.KBAppShardingNameLabelKey] = compName if podSelector.Role != "" { labels[constant.RoleLabelKey] = podSelector.Role diff --git a/pkg/operations/custom_test.go b/pkg/operations/custom_test.go index 7a0be8b50cb..5fc6c7f837b 100644 --- a/pkg/operations/custom_test.go +++ b/pkg/operations/custom_test.go @@ -33,6 +33,7 @@ import ( appsv1 "github.com/apecloud/kubeblocks/apis/apps/v1" opsv1alpha1 "github.com/apecloud/kubeblocks/apis/operations/v1alpha1" + "github.com/apecloud/kubeblocks/pkg/common" "github.com/apecloud/kubeblocks/pkg/constant" intctrlutil "github.com/apecloud/kubeblocks/pkg/controllerutil" "github.com/apecloud/kubeblocks/pkg/generics" @@ -268,7 +269,7 @@ var _ = Describe("CustomOps", func() { Expect(ops.Status.Phase).Should(Equal(opsv1alpha1.OpsFailedPhase)) }) - It("Test custom ops when workload job completed ", func() { + testCustomOps := func() { By("create custom Ops") params := []opsv1alpha1.Parameter{ {Name: requiredParam, Value: "select 1"}, @@ -300,7 +301,66 @@ var _ = Describe("CustomOps", func() { _, err = GetOpsManager().Reconcile(reqCtx, k8sClient, opsResource) Expect(err).ShouldNot(HaveOccurred()) Expect(opsResource.OpsRequest.Status.Phase).Should(Equal(opsv1alpha1.OpsSucceedPhase)) + } + + It("Test custom ops when workload job completed ", func() { + testCustomOps() }) + It("Should failed when creating ops with a sharding component ahd the opsDef misses podInfoExtractors", func() { + cluster = testapps.NewClusterFactory(testCtx.DefaultNamespace, "", ""). + WithRandomName().AddSharding(defaultCompName, "", compDefName).Create(&testCtx).GetObject() + + params := []opsv1alpha1.Parameter{ + {Name: "sql", Value: "select 1"}, + } + ops := createCustomOps(defaultCompName, params) + opsResource.Cluster = cluster + By("validate pass for json schema") + _, err := GetOpsManager().Do(reqCtx, k8sClient, opsResource) + Expect(err).ShouldNot(HaveOccurred()) + Expect(ops.Status.Phase).Should(Equal(opsv1alpha1.OpsFailedPhase)) + }) + + It("Test custom ops with sharding cluster", func() { + By("init environment for sharding cluster") + cluster = testapps.NewClusterFactory(testCtx.DefaultNamespace, "", ""). + WithRandomName().AddSharding(defaultCompName, "", compDefName).Create(&testCtx).GetObject() + + opsResource.Cluster = cluster + + Expect(testapps.ChangeObj(&testCtx, opsDef, func(obj *opsv1alpha1.OpsDefinition) { + podExtraInfoName := "running-pod" + obj.Spec.PodInfoExtractors = []opsv1alpha1.PodInfoExtractor{ + { + Name: podExtraInfoName, + PodSelector: opsv1alpha1.PodSelector{ + MultiPodSelectionPolicy: opsv1alpha1.Any, + }, + }, + } + obj.Spec.Actions[0].Workload.PodInfoExtractorName = podExtraInfoName + })).Should(Succeed()) + + // create a sharding component + shardingNamePrefix := constant.GenerateClusterComponentName(cluster.Name, defaultCompName) + shardingCompName := common.SimpleNameGenerator.GenerateName(shardingNamePrefix) + compObj = testapps.NewComponentFactory(testCtx.DefaultNamespace, shardingCompName, compDefName). + AddLabels(constant.AppInstanceLabelKey, cluster.Name). + AddLabels(constant.KBAppClusterUIDKey, string(cluster.UID)). + AddLabels(constant.KBAppShardingNameLabelKey, defaultCompName). + AddLabels(constant.KBAppComponentLabelKey, shardingCompName). + SetReplicas(1). + Create(&testCtx). + GetObject() + + // create a pod which belongs to the sharding component + pod := testapps.MockInstanceSetPod(&testCtx, nil, cluster.Name, defaultCompName, fmt.Sprintf(shardingCompName+"-0"), "", "") + Expect(testapps.ChangeObj(&testCtx, pod, func(obj *corev1.Pod) { + pod.Labels[constant.KBAppShardingNameLabelKey] = defaultCompName + })).Should(Succeed()) + + testCustomOps() + }) }) }) diff --git a/pkg/operations/upgrade.go b/pkg/operations/upgrade.go index e157dba9dac..7fff7d771c0 100644 --- a/pkg/operations/upgrade.go +++ b/pkg/operations/upgrade.go @@ -52,7 +52,7 @@ func init() { // ActionStartedCondition the started condition when handle the upgrade request. func (u upgradeOpsHandler) ActionStartedCondition(reqCtx intctrlutil.RequestCtx, cli client.Client, opsRes *OpsResource) (*metav1.Condition, error) { - return opsv1alpha1.NewHorizontalScalingCondition(opsRes.OpsRequest), nil + return opsv1alpha1.NewUpgradingCondition(opsRes.OpsRequest), nil } func (u upgradeOpsHandler) Action(reqCtx intctrlutil.RequestCtx, cli client.Client, opsRes *OpsResource) error {