diff --git a/docs/api_docs/connect_database/connect-database-in-production-environment.md b/docs/api_docs/connect_database/connect-database-in-production-environment.md deleted file mode 100644 index ecf346b0186..00000000000 --- a/docs/api_docs/connect_database/connect-database-in-production-environment.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Connect database in production environment -description: How to connect to a database in production environment -keywords: [connect to a database, production environment] -sidebar_position: 3 -sidebar_label: Production environment ---- - -# Connect database in production environment - -In the production environment, it is normal to connect a database with CLI and SDK clients. There are three scenarios. - -- Scenario 1: Client1 and the database are in the same Kubernetes cluster. To connect client1 and the database, see [Procedure 3](#procedure-3-connect-database-in-the-same-kubernetes-cluster). -- Scenario 2: Client2 is outside the Kubernetes cluster, but it is in the same VPC as the database. To connect client2 and the database, see [Procedure 5](#procedure-5-client-outside-the-kubernetes-cluster-but-in-the-same-vpc-as-the-kubernetes-cluster). -- Scenario 3: Client3 and the database are in different VPCs, such as other VPCs or the public network. To connect client3 and the database, see [Procedure 4](#procedure-4-connect-database-with-clients-in-other-vpcs-or-public-networks). - -See the figure below to get a clear image of the network location. - -![Example](./../../img/connect_database_in_a_production_environment.png) - -## Procedure 3. Connect database in the same Kubernetes cluster - -You can connect with the database ClusterIP or domain name. To check the database endpoint, use `kbcli cluster describe ${cluster-name}`. - -```bash -kbcli cluster describe x -> -Name: x Created Time: Mar 01,2023 11:45 UTC+0800 -NAMESPACE CLUSTER-DEFINITION VERSION STATUS TERMINATION-POLICY -default apecloud-mysql ac-mysql-8.0.30 Running Delete - -Endpoints: -COMPONENT MODE INTERNAL EXTERNAL -x ReadWrite x-mysql.default.svc.cluster.local:3306 - -Topology: -COMPONENT INSTANCE ROLE STATUS AZ NODE CREATED-TIME -mysql x-mysql-0 leader Running cn-northwest-1b ip-10-0-2-184.cn-northwest-1.compute.internal/10.0.2.184 Mar 01,2023 11:45 UTC+0800 - -Resources Allocation: -COMPONENT DEDICATED CPU(REQUEST/LIMIT) MEMORY(REQUEST/LIMIT) STORAGE-SIZE STORAGE-CLASS -mysql false 1 / 1 1Gi / 1Gi data:10Gi - -Images: -COMPONENT TYPE IMAGE -mysql mysql registry.cn-hangzhou.aliyuncs.com/apecloud/apecloud-mysql-server:8.0.30-5.alpha2.20230105.gd6b8719.2 - -Events(last 5 warnings, see more:kbcli cluster list-events -n default x): -TIME TYPE REASON OBJECT MESSAGE -``` - -## Procedure 4. Connect database with clients in other VPCs or public networks - -You can enable the External LoadBalancer of the cloud vendor. - -:::note - -The following command creates a LoadBalancer instance for the database instance, which may incur expenses from your cloud vendor. - -::: - -```bash -kbcli cluster expose ${cluster-name} --type internet --enable=true -``` - -To disable the LoadBalancer instance, execute the following command. - -```bash -kbcli cluster expose ${cluster-name} --type internet --enable=false -``` - -:::note - -The instance is inaccessible after you disable the LoadBalancer instance. - -::: - -## Procedure 5. Client outside the Kubernetes cluster but in the same VPC as the Kubernetes cluster - -A stable domain name for long-term connections is required. An Internal LoadBalancer provided by the cloud vendor can be used for this purpose. - -:::note - -The following command creates a LoadBalancer instance for the database instance, which may incur expenses from your cloud vendor. - -::: - -```bash -kbcli cluster expose ${cluster-name} --type vpc --enable=true -``` - -To disable the LoadBalancer instance, execute the following command. - -:::note - -Once disabled, the instance is not accessible. - -::: - -```bash -kbcli cluster expose ${cluster-name} --type vpc --enable=false -``` diff --git a/docs/api_docs/connect_database/connect-database-in-testing-environment.md b/docs/api_docs/connect_database/connect-database-in-testing-environment.md deleted file mode 100644 index 8a201d772d9..00000000000 --- a/docs/api_docs/connect_database/connect-database-in-testing-environment.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Connect database in testing environment -description: How to connect to a database in testing environment -keywords: [connect to a database, testing environment, test environment] -sidebar_position: 2 -sidebar_label: Testing environment ---- - -# Connect database in the testing environment - -## Procedure 1. Use kubectl exec command - -If the database address is not required, run the command below to connect to the cluster via the default address. - -You can use the `kbcli cluster connect` command and specify the cluster name to be connected. - - ```bash - kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d - > - root - - kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d - > - 2gvztbvz - ``` - -2. Run the `kubectl exec` command and specify the pod to be connected. - - ```bash - kubectl exec -ti -n demo mycluster-mysql-0 -- bash - ``` - -3. Connect to the cluster. - - ```bash - mysql -u root -p2gvztbvz - ``` - -## Procedure 2. Connect database with CLI or SDK client - -For a pod without a client, you can follow the steps below to connect to the cluster. You can also connect to the cluster by other options, like CLI, SDK client, go connection, java connection, etc. - -Below is an example of using CLI to connect to the cluster on the local host. - -1. Get the `username` and `password` for the cluster. - - ```bash - kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d - > - root - - kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d - > - 2gvztbvz - ``` - -2. Run the command below to connect to the cluster. - - ```bash - kubectl port-forward svc/mycluster-mysql 3306:3306 -n demo - - mysql -h 127.0.0.1 -P 3306 -u root -p2gvztbvz - ``` diff --git a/docs/api_docs/connect_database/overview-of-database-connection.md b/docs/api_docs/connect_database/overview-of-database-connection.md deleted file mode 100644 index d0bbf610348..00000000000 --- a/docs/api_docs/connect_database/overview-of-database-connection.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Connect database from anywhere -description: How to connect to a database -keywords: [connect to a database] -sidebar_position: 1 -sidebar_label: Overview ---- - -# Overview of Database Connection - -After the deployment of KubeBlocks and creating clusters, the database runs on Kubernetes as a Pod. You can connect to the database via a client interface or `kbcli`. -As the figure below indicates, you must be clear with the purpose of connecting the database. - -- To take a trial of KubeBlocks, and test the database function, or benchmarking with low-flow testing, see [Connect database in a testing environment](connect-database-in-testing-environment.md). -- To connect a database in a production environment, or for a high-flow pressure test, see [Connect database in a production environment](connect-database-in-production-environment.md). - -![Connect database](./../../img/connect_database.png) diff --git a/docs/api_docs/installation/_category_.yml b/docs/api_docs/installation/_category_.yml index a2dc01f3ee7..e69de29bb2d 100644 --- a/docs/api_docs/installation/_category_.yml +++ b/docs/api_docs/installation/_category_.yml @@ -1,4 +0,0 @@ -position: 3 -label: Installation -collapsible: true -collapsed: true \ No newline at end of file diff --git a/docs/api_docs/kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md b/docs/api_docs/kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md index 453f0628694..eff9016b94e 100644 --- a/docs/api_docs/kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md +++ b/docs/api_docs/kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md @@ -14,8 +14,8 @@ This tutorial shows how to create and connect to an ApeCloud MySQL cluster. ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). -* Make sure the `apecloud-mysql` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). +* Make sure the `apecloud-mysql` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition apecloud-mysql diff --git a/docs/api_docs/kubeblocks-for-apecloud-mysql/configuration/configuration.md b/docs/api_docs/kubeblocks-for-apecloud-mysql/configuration/configuration.md index 19ac9b5b5f6..1654a8b4367 100644 --- a/docs/api_docs/kubeblocks-for-apecloud-mysql/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-apecloud-mysql/configuration/configuration.md @@ -18,7 +18,7 @@ But it's also important to note that the dynamic parameter configuration doesn't ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create an ApeCloud MySQL cluster](./../cluster-management/create-and-connect-an-apecloud-mysql-cluster.md). ## Configure cluster parameters by editing configuration file diff --git a/docs/api_docs/kubeblocks-for-apecloud-mysql/high-availability/high-availability.md b/docs/api_docs/kubeblocks-for-apecloud-mysql/high-availability/high-availability.md index bb2d6a20da7..0f85677ed1f 100644 --- a/docs/api_docs/kubeblocks-for-apecloud-mysql/high-availability/high-availability.md +++ b/docs/api_docs/kubeblocks-for-apecloud-mysql/high-availability/high-availability.md @@ -21,7 +21,7 @@ The faults here are all simulated by deleting pods. When there are sufficient re ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * [Create an ApeCloud MySQL RaftGroup Cluster](./../cluster-management/create-and-connect-an-apecloud-mysql-cluster.md). * Run `kubectl get cd apecloud-mysql -o yaml` to check whether _rolechangedprobe_ is enabled in the ApeCloud MySQL RaftGroup Cluster (it is enabled by default). If the following configuration exists, it indicates that it is enabled: diff --git a/docs/api_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md b/docs/api_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md index 829412d137c..d143318627a 100644 --- a/docs/api_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md +++ b/docs/api_docs/kubeblocks-for-apecloud-mysql/proxy/apecloud-mysql-proxy.md @@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem'; ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. Prepare an ApeCloud MySQL RaftGroup named `mycluster` for demonstrating how to enable the proxy function for an existing cluster. Refer to [Create a MySQL cluster](./../cluster-management/create-and-connect-an-apecloud-mysql-cluster.md) for details. ## Create a Proxy Cluster diff --git a/docs/api_docs/kubeblocks-for-elasticsearch/manage-elasticsearch.md b/docs/api_docs/kubeblocks-for-elasticsearch/manage-elasticsearch.md index 6d5924d4570..0d27a3b3d29 100644 --- a/docs/api_docs/kubeblocks-for-elasticsearch/manage-elasticsearch.md +++ b/docs/api_docs/kubeblocks-for-elasticsearch/manage-elasticsearch.md @@ -17,10 +17,10 @@ KubeBlocks supports the management of Elasticsearch. This tutorial illustrates h ## Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `elasticsearch` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../installation/install-addons.md) to enable it first. + Make sure the `elasticsearch` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition elasticsearch diff --git a/docs/api_docs/kubeblocks-for-kafka/cluster-management/create-a-kafka-cluster.md b/docs/api_docs/kubeblocks-for-kafka/cluster-management/create-a-kafka-cluster.md index 3fe3819a0c0..61e93642b96 100644 --- a/docs/api_docs/kubeblocks-for-kafka/cluster-management/create-a-kafka-cluster.md +++ b/docs/api_docs/kubeblocks-for-kafka/cluster-management/create-a-kafka-cluster.md @@ -15,10 +15,10 @@ This document shows how to create a Kafka cluster by `kubectl` or a YAML file. ## Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `kafka` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. + Make sure the `kafka` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition kafka diff --git a/docs/api_docs/kubeblocks-for-kafka/configuration/configuration.md b/docs/api_docs/kubeblocks-for-kafka/configuration/configuration.md index 4c8bbf3f077..fdddbfbee11 100644 --- a/docs/api_docs/kubeblocks-for-kafka/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-kafka/configuration/configuration.md @@ -11,7 +11,7 @@ This guide shows how to configure cluster parameters. ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create a Kafka cluster](./../cluster-management/create-a-kafka-cluster.md). ## Configure cluster parameters by editing configuration file diff --git a/docs/api_docs/kubeblocks-for-milvus/manage-milvus.md b/docs/api_docs/kubeblocks-for-milvus/manage-milvus.md index ae22e2dd530..98fdc9934b6 100644 --- a/docs/api_docs/kubeblocks-for-milvus/manage-milvus.md +++ b/docs/api_docs/kubeblocks-for-milvus/manage-milvus.md @@ -19,10 +19,10 @@ This tutorial illustrates how to create and manage a Milvus cluster by `kubectl` ## Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `milvus` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../installation/install-addons.md) to enable it first. + Make sure the `milvus` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition milvus diff --git a/docs/api_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-to-a-mongodb-cluster.md b/docs/api_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-to-a-mongodb-cluster.md index 70008222bf6..8a7fa1ee1d4 100644 --- a/docs/api_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-to-a-mongodb-cluster.md +++ b/docs/api_docs/kubeblocks-for-mongodb/cluster-management/create-and-connect-to-a-mongodb-cluster.md @@ -17,11 +17,11 @@ This tutorial shows how to create and connect to a MongoDB cluster. ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `mongodb` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. + Make sure the `mongodb` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition mongodb diff --git a/docs/api_docs/kubeblocks-for-mongodb/configuration/configuration.md b/docs/api_docs/kubeblocks-for-mongodb/configuration/configuration.md index 5e0a6ad680e..e88db70cb95 100644 --- a/docs/api_docs/kubeblocks-for-mongodb/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-mongodb/configuration/configuration.md @@ -11,7 +11,7 @@ This guide shows how to configure cluster parameters. ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create a MongoDB cluster](./../cluster-management/create-and-connect-to-a-mongodb-cluster.md). ## Configure cluster parameters by configuration file diff --git a/docs/api_docs/kubeblocks-for-mysql-community-edition/cluster-management/create-and-connect-a-mysql-cluster.md b/docs/api_docs/kubeblocks-for-mysql-community-edition/cluster-management/create-and-connect-a-mysql-cluster.md index 8dc527f7fc5..1d1bc51f204 100644 --- a/docs/api_docs/kubeblocks-for-mysql-community-edition/cluster-management/create-and-connect-a-mysql-cluster.md +++ b/docs/api_docs/kubeblocks-for-mysql-community-edition/cluster-management/create-and-connect-a-mysql-cluster.md @@ -14,10 +14,10 @@ This tutorial shows how to create and connect to a MySQL cluster. ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. -* Make sure the `mysql` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. +* Make sure the `mysql` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition mysql diff --git a/docs/api_docs/kubeblocks-for-mysql-community-edition/configuration/configuration.md b/docs/api_docs/kubeblocks-for-mysql-community-edition/configuration/configuration.md index 5a07d49c68c..b1c96283c0c 100644 --- a/docs/api_docs/kubeblocks-for-mysql-community-edition/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-mysql-community-edition/configuration/configuration.md @@ -18,7 +18,7 @@ But it's also important to note that the dynamic parameter configuration doesn't ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create a MySQL cluster](./../cluster-management/create-and-connect-a-mysql-cluster.md). ## Configure cluster parameters by editing configuration file diff --git a/docs/api_docs/kubeblocks-for-mysql-community-edition/high-availability/high-availability.md b/docs/api_docs/kubeblocks-for-mysql-community-edition/high-availability/high-availability.md index 563a8d04f73..3ae26e20f2e 100644 --- a/docs/api_docs/kubeblocks-for-mysql-community-edition/high-availability/high-availability.md +++ b/docs/api_docs/kubeblocks-for-mysql-community-edition/high-availability/high-availability.md @@ -21,7 +21,7 @@ The faults here are all simulated by deleting pods. When there are sufficient re ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * [Create a MySQL Replication Cluster](./../cluster-management/create-and-connect-a-mysql-cluster.md). * Run `kubectl get cd mysql -o yaml` to check whether _rolechangedprobe_ is enabled in the MySQL Replication Cluster (it is enabled by default). If the following configuration exists, it indicates that it is enabled: diff --git a/docs/api_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster.md b/docs/api_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster.md index 16571b630c8..2843c6bca2d 100644 --- a/docs/api_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster.md +++ b/docs/api_docs/kubeblocks-for-postgresql/cluster-management/create-and-connect-a-postgresql-cluster.md @@ -14,10 +14,10 @@ This tutorial shows how to create and connect to a PostgreSQL cluster. ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `postgresql` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. + Make sure the `postgresql` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition postgresql diff --git a/docs/api_docs/kubeblocks-for-postgresql/configuration/configuration.md b/docs/api_docs/kubeblocks-for-postgresql/configuration/configuration.md index acc9dc08b51..3a7611975b5 100644 --- a/docs/api_docs/kubeblocks-for-postgresql/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-postgresql/configuration/configuration.md @@ -17,7 +17,7 @@ But it's also important to note that the dynamic parameter configuration doesn't ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create a PostgreSQL cluster](./../cluster-management/create-and-connect-a-postgresql-cluster.md). ## Configure cluster parameters by editing configuration file diff --git a/docs/api_docs/kubeblocks-for-postgresql/high-availability/high-availability.md b/docs/api_docs/kubeblocks-for-postgresql/high-availability/high-availability.md index be0630808a0..caecbbf7cad 100644 --- a/docs/api_docs/kubeblocks-for-postgresql/high-availability/high-availability.md +++ b/docs/api_docs/kubeblocks-for-postgresql/high-availability/high-availability.md @@ -11,7 +11,7 @@ KubeBlocks integrates [the open-source Patroni solution](https://patroni.readthe ## Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * [Create a PostgreSQL Replication Cluster](./../cluster-management/create-and-connect-a-postgresql-cluster.md#create-a-postgresql-cluster). * Check whether the following role probe parameters exist to verify the role probe is enabled. diff --git a/docs/api_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md b/docs/api_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md index 2bc06346512..3648cee7647 100644 --- a/docs/api_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md +++ b/docs/api_docs/kubeblocks-for-pulsar/cluster-management/create-pulsar-cluster-on-kubeblocks.md @@ -26,11 +26,11 @@ Refer to the [Pulsar official document](https://pulsar.apache.org/docs/3.1.x/) f ## Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `pulsar` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. + Make sure the `pulsar` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition redis diff --git a/docs/api_docs/kubeblocks-for-pulsar/configuration/configuration.md b/docs/api_docs/kubeblocks-for-pulsar/configuration/configuration.md index 547a4f03626..e1866017414 100644 --- a/docs/api_docs/kubeblocks-for-pulsar/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-pulsar/configuration/configuration.md @@ -26,7 +26,7 @@ For Pulsar, there are 3 types of parameters: ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create a Pulsar cluster](./../cluster-management/create-pulsar-cluster-on-kubeblocks.md). ## Configure cluster parameters by configuration file diff --git a/docs/api_docs/kubeblocks-for-qdrant/manage-qdrant.md b/docs/api_docs/kubeblocks-for-qdrant/manage-qdrant.md index 577034afe28..dee70ea486b 100644 --- a/docs/api_docs/kubeblocks-for-qdrant/manage-qdrant.md +++ b/docs/api_docs/kubeblocks-for-qdrant/manage-qdrant.md @@ -17,10 +17,10 @@ In this chapter, we take Qdrant as an example to show how to manage vector datab ## Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `qdrant` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../installation/install-addons.md) to enable it first. + Make sure the `qdrant` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition qdrant diff --git a/docs/api_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster.md b/docs/api_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster.md index 78075eb9ed6..91483c1b61a 100644 --- a/docs/api_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster.md +++ b/docs/api_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster.md @@ -17,11 +17,11 @@ This tutorial shows how to create and connect to a Redis cluster. ### Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `redis` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../../installation/install-addons.md) to enable it first. + Make sure the `redis` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition redis diff --git a/docs/api_docs/kubeblocks-for-redis/configuration/configuration.md b/docs/api_docs/kubeblocks-for-redis/configuration/configuration.md index 50216222179..dda0bc9dcd6 100644 --- a/docs/api_docs/kubeblocks-for-redis/configuration/configuration.md +++ b/docs/api_docs/kubeblocks-for-redis/configuration/configuration.md @@ -12,7 +12,7 @@ This guide shows how to configure cluster parameters. ## Before you start -1. [Install KubeBlocks](./../../installation/install-kubeblocks.md). +1. [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). 2. [Create a Redis cluster](./../cluster-management/create-and-connect-a-redis-cluster.md). ## Configure cluster parameters by editing configuration file diff --git a/docs/api_docs/kubeblocks-for-redis/high-availability/high-availability.md b/docs/api_docs/kubeblocks-for-redis/high-availability/high-availability.md index ef78483be51..d82cbae2fd5 100644 --- a/docs/api_docs/kubeblocks-for-redis/high-availability/high-availability.md +++ b/docs/api_docs/kubeblocks-for-redis/high-availability/high-availability.md @@ -15,7 +15,7 @@ In the RedisReplication Cluster provided by KubeBlocks, Sentinel is deployed as ## Before you start -* [Install KubeBlocks](./../../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../../user_docs/installation/install-with-helm/install-kubeblocks.md). * [Create a Redis Replication Cluster](./../cluster-management/create-and-connect-a-redis-cluster.md#create-a-redis-cluster). * Check the role probe. * Check whether the following role probe parameters exist to verify the role probe is enabled. diff --git a/docs/api_docs/kubeblocks-for-redis/redis-cluster-mode.md b/docs/api_docs/kubeblocks-for-redis/redis-cluster-mode.md index 3e67f19fda4..069f54f99fd 100644 --- a/docs/api_docs/kubeblocks-for-redis/redis-cluster-mode.md +++ b/docs/api_docs/kubeblocks-for-redis/redis-cluster-mode.md @@ -30,7 +30,7 @@ Below is a brief introduction to the basic operations of Redis Cluster Mode. ### Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). Make sure your KubeBlocks and addon are version 0.9 or above. * Make sure the Redis addon is enabled. * View all the database types and versions available for creating a cluster. diff --git a/docs/api_docs/kubeblocks-for-starrocks/manage-starrocks.md b/docs/api_docs/kubeblocks-for-starrocks/manage-starrocks.md index f08c7c0b363..42755e1e672 100644 --- a/docs/api_docs/kubeblocks-for-starrocks/manage-starrocks.md +++ b/docs/api_docs/kubeblocks-for-starrocks/manage-starrocks.md @@ -17,10 +17,10 @@ This tutorial illustrates how to create and manage a StarRocks cluster by `kubec ## Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `starrocks` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../installation/install-addons.md) to enable it first. + Make sure the `starrocks` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition starrocks diff --git a/docs/api_docs/kubeblocks-for-weaviate/manage-weaviate.md b/docs/api_docs/kubeblocks-for-weaviate/manage-weaviate.md index 8d5554daac3..917759a0acf 100644 --- a/docs/api_docs/kubeblocks-for-weaviate/manage-weaviate.md +++ b/docs/api_docs/kubeblocks-for-weaviate/manage-weaviate.md @@ -17,10 +17,10 @@ This tutorial illustrates how to create and manage a Weaviate cluster by `kubect ## Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `weaviate` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../installation/install-addons.md) to enable it first. + Make sure the `weaviate` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition weaviate diff --git a/docs/api_docs/kubeblocks-for-xinference/manage-xinference.md b/docs/api_docs/kubeblocks-for-xinference/manage-xinference.md index 24148d284d6..a4aa51d54fd 100644 --- a/docs/api_docs/kubeblocks-for-xinference/manage-xinference.md +++ b/docs/api_docs/kubeblocks-for-xinference/manage-xinference.md @@ -17,10 +17,10 @@ This tutorial illustrates how to create and manage a Xinference cluster by `kube ## Before you start -* [Install KubeBlocks](./../installation/install-kubeblocks.md). +* [Install KubeBlocks](../../user_docs/installation/install-with-helm/install-kubeblocks.md). * View all the database types and versions available for creating a cluster. - Make sure the `xinference` cluster definition is installed. If the cluster definition is not available, refer to [this doc](./../installation/install-addons.md) to enable it first. + Make sure the `xinference` cluster definition is installed. If the cluster definition is not available, refer to [this doc](../../user_docs/installation/install-with-helm/install-addons.md) to enable it first. ```bash kubectl get clusterdefinition xinference diff --git a/docs/api_docs/maintenance/backup-and-restore/backup/backup-repo.md b/docs/api_docs/maintenance/backup-and-restore/backup/backup-repo.md index cd345f76dda..6687d1706d3 100644 --- a/docs/api_docs/maintenance/backup-and-restore/backup/backup-repo.md +++ b/docs/api_docs/maintenance/backup-and-restore/backup/backup-repo.md @@ -21,7 +21,7 @@ Make sure you have all the following prepared. * [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) * [Install Helm](https://helm.sh/docs/intro/install/) -* [Install KubeBlocks](./../../../installation/install-kubeblocks.md) +* [Install KubeBlocks](../../../../user_docs/installation/install-with-helm/install-kubeblocks.md) ## Install MinIO diff --git a/docs/img/kubeblocks-architecture.png b/docs/img/kubeblocks-architecture.png index 0015e0951e3..f60f2da1061 100644 Binary files a/docs/img/kubeblocks-architecture.png and b/docs/img/kubeblocks-architecture.png differ diff --git a/docs/user_docs/connect_database/_category_.yml b/docs/user_docs/connect_database/_category_.yml index c84c1e9c2d8..431c89b4cfe 100644 --- a/docs/user_docs/connect_database/_category_.yml +++ b/docs/user_docs/connect_database/_category_.yml @@ -1,4 +1,4 @@ -position: 4 +position: 6 label: Connect Database collapsible: true collapsed: true \ No newline at end of file diff --git a/docs/user_docs/connect_database/connect-database-in-production-environment.md b/docs/user_docs/connect_database/connect-database-in-production-environment.md index 00aba1a89a4..6d0f112ad64 100644 --- a/docs/user_docs/connect_database/connect-database-in-production-environment.md +++ b/docs/user_docs/connect_database/connect-database-in-production-environment.md @@ -6,20 +6,28 @@ sidebar_position: 3 sidebar_label: Production environment --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Connect database in production environment In the production environment, it is normal to connect a database with CLI and SDK clients. There are three scenarios. -- Scenario 1: Client1 and the database are in the same Kubernetes cluster. To connect client1 and the database, see [Option 3](#option-3-connect-database-in-the-same-kubernetes-cluster). -- Scenario 2: Client2 is outside the Kubernetes cluster, but it is in the same VPC as the database. To connect client2 and the database, see [Option 5](#option-5-client-outside-the-kubernetes-cluster-but-in-the-same-vpc-as-the-kubernetes-cluster). -- Scenario 3: Client3 and the database are in different VPCs, such as other VPCs or the public network. To connect client3 and the database, see [Option 4](#option-4-connect-database-with-clients-in-other-vpcs-or-public-networks). +- Scenario 1: Client1 and the database are in the same Kubernetes cluster. To connect client1 and the database, see [Use ClusterIP](#scenario-1-connect-database-in-the-same-kubernetes-cluster). +- Scenario 2: Client2 is outside the Kubernetes cluster, but it is in the same VPC as the database. To connect client2 and the database, see [Expose VPC Private Address](#scenario-2-client-outside-the-kubernetes-cluster-but-in-the-same-vpc-as-the-kubernetes-cluster). +- Scenario 3: Client3 and the database are in different VPCs, such as other VPCs or the public network. To connect client3 and the database, see [Expose VPC Public Address](#scenario-3-connect-database-with-clients-in-other-vpcs-or-public-networks). See the figure below to get a clear image of the network location. ![Example](./../../img/connect_database_in_a_production_environment.png) -## Option 3. Connect database in the same Kubernetes cluster +## Scenario 1. Connect database in the same Kubernetes cluster + +You can connect with the database ClusterIP or domain name. -You can connect with the database ClusterIP or domain name. To check the database endpoint, use `kbcli cluster describe ${cluster-name}`. + + + +To check the database endpoint, use `kbcli cluster describe ${cluster-name}`. ```bash kbcli cluster describe x @@ -48,9 +56,21 @@ Events(last 5 warnings, see more:kbcli cluster list-events -n default x): TIME TYPE REASON OBJECT MESSAGE ``` -## Option 4. Connect database with clients in other VPCs or public networks + + -You can enable the External LoadBalancer of the cloud vendor. +To check the database endpoint, use `kubectl get service -`. + +```bash +kubectl get service mycluster-mysql +``` + + + + +## Scenario 2. Client outside the Kubernetes cluster but in the same VPC as the Kubernetes cluster + +A stable domain name for long-term connections is required. An Internal LoadBalancer provided by the cloud vendor can be used for this purpose. :::note @@ -58,25 +78,90 @@ The following command creates a LoadBalancer instance for the database instance, ::: +::: + + + + ```bash -kbcli cluster expose ${cluster-name} --type internet --enable=true +kbcli cluster expose ${cluster-name} --type vpc --enable=true +``` + + + + +```yaml +kubectl apply -f - < + + To disable the LoadBalancer instance, execute the following command. +:::note + +Once disabled, the instance is not accessible. + +::: + + + + ```bash -kbcli cluster expose ${cluster-name} --type internet --enable=false +kbcli cluster expose ${cluster-name} --type vpc --enable=false ``` -:::note + + + +```yaml +kubectl apply -f - < + -::: -## Option 5. Client outside the Kubernetes cluster but in the same VPC as the Kubernetes cluster +## Scenario 3. Connect database with clients in other VPCs or public networks -A stable domain name for long-term connections is required. An Internal LoadBalancer provided by the cloud vendor can be used for this purpose. +You can enable the External LoadBalancer of the cloud vendor. :::note @@ -84,18 +169,81 @@ The following command creates a LoadBalancer instance for the database instance, ::: + + + ```bash -kbcli cluster expose ${cluster-name} --type vpc --enable=true +kbcli cluster expose ${cluster-name} --type internet --enable=true ``` -To disable the LoadBalancer instance, execute the following command. + + + +```yaml +kubectl apply -f - < + -Once disabled, the instance is not accessible. -::: +To disable the LoadBalancer instance, execute the following command. + + + ```bash -kbcli cluster expose ${cluster-name} --type vpc --enable=false +kbcli cluster expose ${cluster-name} --type internet --enable=false +``` + + + + +```yaml +kubectl apply -f - < + + +:::note + +The instance is inaccessible after you disable the LoadBalancer instance. + +::: \ No newline at end of file diff --git a/docs/user_docs/connect_database/connect-database-in-testing-environment.md b/docs/user_docs/connect_database/connect-database-in-testing-environment.md index 4b1e33429fb..c48e15fec11 100644 --- a/docs/user_docs/connect_database/connect-database-in-testing-environment.md +++ b/docs/user_docs/connect_database/connect-database-in-testing-environment.md @@ -6,8 +6,14 @@ sidebar_position: 2 sidebar_label: Testing environment --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Connect database in testing environment + + + ## Option 1. Use kbcli cluster connect command You can use the `kbcli cluster connect` command and specify the cluster name to be connected. @@ -40,3 +46,108 @@ The password does not include -p. ::: ![Example](./../../img/connect_database_with_CLI_or_SDK_client.png) + + + + +## Step 1. Retrieve Database Credentials + +Before connecting to the MySQL database running inside your Kubernetes cluster, you may need to retrieve the username and password from a Kubernetes Secret. Secrets in Kubernetes are typically base64-encoded, so you will need to decode them to obtain the actual credentials. Here’s how you can do this with kubectl. + +1. Retrieve the `username`: + + Use the kubectl get secrets command to extract the username from the secret named `mycluster-conn-credential` in the demo namespace. + + ```bash + kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\username}' | base64 -d + > + root + ``` + + - Replace "mycluster" with the actual name of your database cluster. + - Replace "demo" with the actual namespace of your database cluster. + +2. Retrieve the `password`: + + ```bash + kubectl get secrets -n demo mycluster-conn-credential -o jsonpath='{.data.\password}' | base64 -d + > + 2gvztbvz + ``` + + - Replace "mycluster" with the actual name of your database cluster. + - Replace "demo" with the actual namespace of your database cluster. + +:::note + +In most KubeBlocks v0.9 addons, the secret that contains the connection credentials follows the naming pattern `{cluster.name}-conn-credential`. However, in some newer versions of KubeBlocks addons, the naming of the secret may have changed to `{cluster.name}-{component.name}-account-{account.name}`. To ensure you are using the correct secret name, run the following command to list all secrets in the namespace and search for the ones related to your database cluster. + +Example: + +```bash +kubectl get secrets -n demo | grep mycluster +``` + +::: + +## Step 2. Connect to the cluster + +After retrieving the credentials, you can connect to the MySQL database running in your Kubernetes cluster using one of two methods: + +- Using `kubectl exec` to connect directly within the Pod. +- Using `kubectl port-forward` to access the database from your local machine. + +### Option 1: Use kubectl exec command in pod + +In some cases, you may need to connect directly to a MySQL database running inside a Kubernetes Pod without relying on external access. Using kubectl exec, you can enter the Pod and interact with the MySQL instance directly from within the cluster, avoiding the need for an external database address. + +1. Run the `kubectl exec` command and specify the pod to be connected. + + Use the kubectl exec command to open an interactive shell session inside the MySQL Pod. This allows you to run commands directly within the Pod's environment. + + ```bash + kubectl exec -ti -n demo mycluster-mysql-0 -- bash + ``` + + - `-ti`: Opens an interactive terminal session (-t allocates a pseudo-TTY, and -i keeps the session open). + - `-n demo`: Specifies the demo namespace where your Pod is running. + - `mycluster-mysql-0`: The name of the MySQL Pod. Make sure to replace this with the actual Pod name if it's different. + - `-- bash`: Opens a Bash shell inside the Pod. You can also use sh if Bash is not available in the container. + +2. Connect to the cluster. + + Once inside the Pod, you can use the MySQL client to connect to the database service running within the same Pod or cluster. Since you're already inside the Pod, you don't need to specify an external host or address. + + ```bash + mysql -u root -p2gvztbvz + ``` + +### Option 2: Connect to database with kubectl port-forward + +When working with databases deployed in a Kubernetes cluster, you can use kubectl port-forward to securely connect to the database from your local machine. This command forwards traffic from your local port to a port in the Kubernetes cluster, allowing you to access the database service as if it were running locally. + +Here is an example of using CLI to connect to the cluster on the local host. + +1. Forward the Port Using `kubectl port-forward`. + + First, you'll need to forward a port from your local machine to the MySQL service running in Kubernetes. This command forwards your local port 3306 (the default MySQL port) to the same port on the MySQL service inside the cluster. + + ```bash + kubectl port-forward svc/mycluster-mysql 3306:3306 -n demo + ``` + + - `svc/mycluster-mysql`: Refers to the MySQL service in your Kubernetes cluster. + - `3306:3306`: Binds the local port 3306 to the service's port 3306. + - `-n demo`: Specifies the namespace demo where the MySQL service is running. + +2. Connect to the Database Locally. + + Once the port is forwarded, you can connect to the MySQL database using a standard MySQL client as if it were running locally on 127.0.0.1 (localhost). The connection will be securely tunneled to the service inside the cluster. + + ```bash + mysql -h 127.0.0.1 -P 3306 -u root -p2gvztbvz + ``` + + + + diff --git a/docs/user_docs/connect_database/overview-of-database-connection.md b/docs/user_docs/connect_database/overview-of-database-connection.md index d0bbf610348..27411ead59f 100644 --- a/docs/user_docs/connect_database/overview-of-database-connection.md +++ b/docs/user_docs/connect_database/overview-of-database-connection.md @@ -8,10 +8,6 @@ sidebar_label: Overview # Overview of Database Connection -After the deployment of KubeBlocks and creating clusters, the database runs on Kubernetes as a Pod. You can connect to the database via a client interface or `kbcli`. -As the figure below indicates, you must be clear with the purpose of connecting the database. +After deploying KubeBlocks and creating clusters, the databases run on Kubernetes, with each replica running in a Pod and managed by the InstanceSet. You can connect to the database using client tools or SDKs through the exposed database Service addresses (ClusterIP, LoadBalancer, or NodePort). See [Connect database in a production environment](connect-database-in-production-environment.md). -- To take a trial of KubeBlocks, and test the database function, or benchmarking with low-flow testing, see [Connect database in a testing environment](connect-database-in-testing-environment.md). -- To connect a database in a production environment, or for a high-flow pressure test, see [Connect database in a production environment](connect-database-in-production-environment.md). - -![Connect database](./../../img/connect_database.png) +If you’ve created a database using KubeBlocks in a playground or test environment, you can also use `kubectl port-forward` to map the database service address to a local port on your machine. Then, you can connect to the database using a client tool or the common database clients integrated inside `kbcli`. However, please note that this is a temporary way to access services within the cluster and is intended for testing and debugging purposes only; it should not be used in a production environment. See [Connect database in a testing environment](connect-database-in-testing-environment.md). diff --git a/docs/user_docs/create_database/_category_.yml b/docs/user_docs/create_database/_category_.yml new file mode 100644 index 00000000000..5476392286c --- /dev/null +++ b/docs/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/docs/user_docs/create_database/overview-of-create-database.md b/docs/user_docs/create_database/overview-of-create-database.md new file mode 100644 index 00000000000..d828d6da2e9 --- /dev/null +++ b/docs/user_docs/create_database/overview-of-create-database.md @@ -0,0 +1,24 @@ +--- +title: How to create a database +description: How to create a database +keywords: [create a database] +sidebar_position: 1 +sidebar_label: Overview +--- + +# Create Various Types of Databases + +After deploying KubeBlocks, you can use it to create various databases such as MySQL, PostgreSQL, Redis, MongoDB, Kafka, Pulsar, RabbitMQ, ElasticSearch, Qdrant, and more. KubeBlocks supports these databases through addons. Refer to the documentation for each database addon to create them. + +- [ApeCloud MySQL](../kubeblocks-for-apecloud-mysql/cluster-management/create-and-connect-an-apecloud-mysql-cluster.md) +- [MySQL Community Edition](../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-kafka/cluster-management/create-a-pulsar-cluster.md) +- RabbitMQ +- [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/docs/api_docs/installation/upgrade/_category_.yml b/docs/user_docs/installation/install-with-helm/_category_.yml similarity index 64% rename from docs/api_docs/installation/upgrade/_category_.yml rename to docs/user_docs/installation/install-with-helm/_category_.yml index 54836b09434..f721a4a8977 100644 --- a/docs/api_docs/installation/upgrade/_category_.yml +++ b/docs/user_docs/installation/install-with-helm/_category_.yml @@ -1,4 +1,4 @@ position: 2 -label: Upgrade +label: Install with helm collapsible: true collapsed: true \ No newline at end of file diff --git a/docs/api_docs/installation/install-addons.md b/docs/user_docs/installation/install-with-helm/install-addons.md similarity index 100% rename from docs/api_docs/installation/install-addons.md rename to docs/user_docs/installation/install-with-helm/install-addons.md diff --git a/docs/api_docs/installation/install-kubeblocks.md b/docs/user_docs/installation/install-with-helm/install-kubeblocks.md similarity index 100% rename from docs/api_docs/installation/install-kubeblocks.md rename to docs/user_docs/installation/install-with-helm/install-kubeblocks.md diff --git a/docs/api_docs/installation/uninstall-kubeblocks.md b/docs/user_docs/installation/install-with-helm/uninstall-kubeblocks.md similarity index 100% rename from docs/api_docs/installation/uninstall-kubeblocks.md rename to docs/user_docs/installation/install-with-helm/uninstall-kubeblocks.md diff --git a/docs/user_docs/installation/upgrade/_category_.yml b/docs/user_docs/installation/upgrade/_category_.yml deleted file mode 100644 index fc7c3e42373..00000000000 --- a/docs/user_docs/installation/upgrade/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -position: 3 -label: Upgrade -collapsible: true -collapsed: true \ No newline at end of file diff --git a/docs/user_docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md b/docs/user_docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md deleted file mode 100644 index 94405a787d7..00000000000 --- a/docs/user_docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Upgrade to KubeBlocks v0.8 -description: Upgrade to KubeBlocks v0.8, operation, tips and notes -keywords: [upgrade, 0.8] -sidebar_position: 2 -sidebar_label: Upgrade to KubeBlocks v0.8 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - -# Upgrade to KubeBlocks v0.8 - -In this tutorial, you will learn how to upgrade to KubeBlocks v0.8. - -:::note - -Execute `kbcli version` to check the current KubeBlocks version you are running, and then upgrade. - -::: - -## Upgrade from KubeBlocks v0.6 - -If you are currently running KubeBlocks v0.6, please upgrade to v0.7.2 first. - -1. Download kbcli v0.7.2. - - ```shell - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.7.2 - ``` - -2. Upgrade to KubeBlocks v0.7.2. - - ```shell - kbcli kb upgrade --version 0.7.2 - ``` - -## Upgrade from KubeBlocks v0.7 - - - - - -1. Set keepAddons. - - KubeBlocks v0.8 streamlines the default installed engines and separates the addons from KubeBlocks operators to KubeBlocks-Addons repo, such as greptime, influxdb, neon, oracle-mysql, orioledb, tdengine, mariadb, nebula, risingwave, starrocks, tidb, and zookeeper. To avoid deleting addon resources that are already in use during the upgrade, execute the following commands: - -- Check the current KubeBlocks version. - - ```shell - helm -n kb-system list | grep kubeblocks - ``` - -- Set the value of keepAddons as 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 - ``` - - Replace `{VERSION}` with your current KubeBlocks version, such as 0.7.2. - -- Check addons. - - Execute the following command to ensure that the addon annotations contain `"helm.sh/resource-policy": "keep"`. - - ```shell - kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}' - ``` - -2. Install CRD. - - To reduce the size of Helm chart, KubeBlocks v0.8 removes CRD from the Helm chart. Before upgrading, you need to install CRD. - - ```shell - kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.8.1/kubeblocks_crds.yaml - ``` - -3. Upgrade KubeBlocks. - - ```shell - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 - ``` - - :::note - - To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.8, the versions of already-installed addons will not be upgraded by default. If you want to upgrade the addons to the versions built into KubeBlocks v0.8, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution. - - ```shell - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.8.1 --set upgradeAddons=true - ``` - - ::: - - - - - -1. Download kbcli v0.8. - - ```shell - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.8.1 - ``` - -2. Upgrade KubeBlocks. - - ```shell - - kbcli kb upgrade --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 - - ``` - - kbcli will automatically add the annotation `"helm.sh/resource-policy": "keep"` to ensure that existing addons are not deleted during the upgrade. - - - - \ No newline at end of file diff --git a/docs/user_docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md b/docs/user_docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md deleted file mode 100644 index b320d2b4fa9..00000000000 --- a/docs/user_docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Upgrade to KubeBlocks v0.9 -description: Upgrade to KubeBlocks v0.9, operation, tips and notes -keywords: [upgrade, 0.9] -sidebar_position: 1 -sidebar_label: Upgrade to KubeBlocks v0.9 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Upgrade to KubeBlocks v0.9 - -In this tutorial, you will learn how to upgrade to KubeBlocks v0.9. - -:::note - -Execute `kbcli version` to check the current KubeBlocks version you are running, and then upgrade. - -::: - -## Compatibility - -KubeBlocks 0.9 is compatible with KubeBlocks 0.8 APIs, but compatibility with APIs from versions prior to v0.8 is not guaranteed. If you are using addons from KubeBlocks 0.7 or earlier (v0.7., 0.6., etc), DO [upgrade KubeBlocks and all addons to v0.8 first](./upgrade-kubeblocks-to-0.8.md) to ensure service availability before upgrading to v0.9. - -## Upgrade from KubeBlocks v0.8 - - - - - -1. Set keepAddons. - - KubeBlocks v0.8 streamlines the default installed engines. To avoid deleting addon resources that are already in use during the upgrade, execute the following commands first. - - - Check the current KubeBlocks version. - - ```shell - helm -n kb-system list | grep kubeblocks - ``` - - - Set the value of keepAddons as 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 - ``` - - Replace `{VERSION}` with your current KubeBlocks version, such as 0.8.3. - - - Check addons. - - Execute the following command to ensure that the addon annotations contain `"helm.sh/resource-policy": "keep"`. - - ```shell - kubectl get addon -o json | jq '.items[] | {name: .metadata.name, annotations: .metadata.annotations}' - ``` - -2. Delete the incompatible OpsDefinition. - - ```bash - kubectl delete opsdefinitions.apps.kubeblocks.io kafka-quota kafka-topic kafka-user-acl switchover - ``` - -3. Install CRD. - - To reduce the size of Helm chart, KubeBlocks v0.8 removes CRD from the Helm chart. Before upgrading, you need to install CRD. - - ```shell - kubectl replace -f https://github.com/apecloud/kubeblocks/releases/download/v0.9.0/kubeblocks_crds.yaml - ``` - -4. Upgrade KubeBlocks. - - ```shell - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.0 --set upgradeAddons=false - ``` - - :::note - - To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9, the versions of already-installed addons will not be upgraded by default. If you want to upgrade the addons to the versions built into KubeBlocks v0.9, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution. - - ```bash - helm -n kb-system upgrade kubeblocks kubeblocks/kubeblocks --version 0.9.0 --set upgradeAddons=true - ``` - - ::: - - - - - -1. Download kbcli v0.9. - - ```shell - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.9.0 - ``` - -2. Upgrade KubeBlocks. - - ```bash - kbcli kb upgrade --version 0.9.0 - ``` - - :::note - - To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9, the versions of already-installed addons will not be upgraded by default. If you want to upgrade the addons to the versions built into KubeBlocks v0.9, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution. - - ```bash - kbcli kb upgrade --version 0.9.0 --set upgradeAddons=true - ``` - - ::: - - kbcli will automatically add the annotation `"helm.sh/resource-policy": "keep"` to ensure that existing addons are not deleted during the upgrade. - - - - - -## Upgrade addons - -If you didn't specify `upgradeAddons` as `true` or your addon is not included in the default installed addons, you can upgrade addons by the options provided below to use the v0.9.0 API. - -:::note - -If the addon you want to upgrade is `mysql`, you need to upgrade this addon and restart the cluster. Otherwise, the cluster created in KubeBlocks v0.8 cannot be used in v0.9. - -If the addon you want to use is `clickhouse/milvus/elasticsearch/llm`, you need to upgrade KubeBlocks first and then upgrade this addon. Otherwise, these addons cannot be used in KubeBlocks v0.9 normally. - -::: - - - - - -```bash -# Add Helm repo -helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts - -# If github is not accessible or very slow for you, please use following repo instead -helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable - -# Update helm repo -helm repo update - -# Update addon version -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/docs/user_docs/overview/about-this-manual.md b/docs/user_docs/overview/about-this-manual.md index 37fcc3e0aaf..f4096eab895 100644 --- a/docs/user_docs/overview/about-this-manual.md +++ b/docs/user_docs/overview/about-this-manual.md @@ -2,6 +2,6 @@ title: About this manual description: KubeBlocks, kbcli, how to keywords: [kubeblocks, overview, introduction] -sidebar_position: 4 +sidebar_position: 5 --- This manual introduces how to operate KubeBlocks with `kbcli`. For advanced users familiar with Kubernetes, this manual also includes guidance on how to operate KubeBlocks using `helm` and `kubectl`. \ No newline at end of file diff --git a/docs/user_docs/overview/concept.md b/docs/user_docs/overview/concept.md index d8cb047b1b9..dad9b7694a9 100644 --- a/docs/user_docs/overview/concept.md +++ b/docs/user_docs/overview/concept.md @@ -128,7 +128,7 @@ Only Addon developers need to understand the ClusterDefinition and ComponentDefi #### ClusterDefinition ClusterDefinition is an API used to define all available topologies of a database cluster, offering a variety of topological configurations to meet diverse deployment needs and scenarios. -Each topology includes a list of component, each linked to a ComponentDefinition, which enhances reusability and reduce redundancy. For example, widely used components such as etcd and Zookeeper can be defined once and reused across multiple ClusterDefinitions, simplifying the setup of new systems. +Each topology includes a list of components, each linked to a ComponentDefinition, which enhances reusability and reduce redundancy. For example, ComponentDefinition of widely used components such as etcd and Zookeeper can be defined once and reused across multiple ClusterDefinitions, simplifying the setup of new systems. Additionally, ClusterDefinition also specifies the sequence of startup, upgrade, and shutdown for components, ensuring a controlled and predictable management of component lifecycles. diff --git a/docs/user_docs/overview/introduction.md b/docs/user_docs/overview/introduction.md index b6185732ebe..b329afd80d2 100644 --- a/docs/user_docs/overview/introduction.md +++ b/docs/user_docs/overview/introduction.md @@ -1,6 +1,6 @@ --- -title: KubeBlocks overview -description: KubeBlocks, kbcli, multicloud +title: Introduction +description: introduction to KubeBlocks keywords: [kubeblocks, overview, introduction] sidebar_position: 1 --- @@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem'; ## What is KubeBlocks -KubeBlocks is an open-source Kubernetes operator for databases, enabling users to run and manage multiple types of databases on Kubernetes. As far as we know, most database operators typically manage only one specific type of database. For example: +KubeBlocks is an open-source Kubernetes operator for databases (more specifically, for stateful applications, including databases and middleware like message queues), enabling users to run and manage multiple types of databases on Kubernetes. As far as we know, most database operators typically manage only one specific type of database. For example: - CloudNativePG, Zalando, CrunchyData, StackGres operator can manage PostgreSQL - Strimzi manages Kafka - Oracle and Percona MySQL operator manage MySQL @@ -217,7 +217,7 @@ This means that managing multiple databases on Kubernetes becomes simple, effici - Rolling upgrades - Decommission a specific replica - Minor version upgrades -- In addition to the declarative API, KubeBlocks also offers an Ops API for executing one-time operational tasks on database clusters. The Ops API supports additional features such as queuing, concurrency control, progress tracking, and operation rollback. +- In addition to the declarative API, KubeBlocks also offers an OpsRequest API for executing one-time operational tasks on database clusters. The OpsRequest API supports additional features such as queuing, concurrency control, progress tracking, and operation rollback. - Observability: Supports integration with Prometheus and Grafana. - Includes a powerful and intuitive command-line tool `kbcli`, which makes operating KubeBlocks CRs on Kubernetes more straightforward and reduces keystrokes. For those well-versed in Kubernetes, kbcli can be used alongside kubectl to provide a more streamlined way of performing operations. diff --git a/docs/user_docs/overview/kubernetes_and_operator_101.md b/docs/user_docs/overview/kubernetes_and_operator_101.md new file mode 100644 index 00000000000..a11087d6e2c --- /dev/null +++ b/docs/user_docs/overview/kubernetes_and_operator_101.md @@ -0,0 +1,106 @@ +--- +title: Kubernetes and Operator 101 +description: things about K8s you need to know +keywords: [K8s, operator, concept] +sidebar_position: 3 +--- + +# Kubernetes and Operator 101 + +# K8s +What is Kubernetes? Some say it's a container orchestration system, others describe it as a distributed operating system, while some view it as a multi-cloud PaaS (Platform as a Service) platform, and others consider it a platform for building PaaS solutions. + +This article will introduce the key concepts and building blocks within Kubernetes. + +## K8s Control Plane +The Kubernetes Control Plane is the brain and heart of Kubernetes. It manages the overall operation of the cluster, including processing API requests, storing configuration data, and ensuring the cluster's desired state. Key components include the API Server (which handles communication), etcd (which stores all cluster data), the Controller Manager (which enforces the desired state), the Scheduler (which assigns workloads to Nodes), and the Cloud Controller Manager (which manages cloud-specific integrations, such as load balancers, storage, and networking). Together, these components orchestrate the deployment, scaling, and management of containers across the cluster. + + +## Node +Some describe Kubernetes as a distributed operating system, capable of managing many Nodes. A Node is a physical or virtual machine that acts as a worker within the cluster. Each Node runs essential services, including the container runtime (such as Docker or containerd), the kubelet, and the kube-proxy. The kubelet ensures that containers are running as specified in a Pod, the smallest deployable unit in Kubernetes. The kube-proxy handles network routing, maintaining network rules, and enabling communication between Pods and services. Nodes provide the computational resources needed to run containerized applications and are managed by the Kubernetes Master, which distributes tasks, monitors Node health, and maintains the desired state of the cluster. + +:::note +In certain contexts, the term "Node" can be confusing when discussing Kubernetes (K8s) alongside databases. In Kubernetes, a "Node" refers to a physical or virtual machine that is part of the Kubernetes cluster and serves as a worker to run containerized applications. However, when a database is running within Kubernetes, the term "Database Node" typically refers to a Pod that hosts a database instance. + +In the KubeBlocks documentation, "Node" generally refers to a Database Node. If we are referring to a Kubernetes Node, we will explicitly specify it as a "K8s Node" to avoid any confusion. +::: + +## kubelet +The kubelet is the agent that the Kubernetes Control Plane uses to manage each Node in the cluster. It ensures that containers are running in a Pod as defined by the Kubernetes control plane. The kubelet continuously monitors the state of the containers, making sure they are healthy and running as expected. If a container fails, the kubelet attempts to restart it according to the specified policies. + + +## Pod +In Kubernetes, a Pod is somewhat analogous to a virtual machine but is much more lightweight and specialized. It is the smallest deployable unit in Kubernetes. +It represents one or more containers that are tightly coupled and need to work together, along with shared storage (volumes), network resources, and a specification for how to run the containers. These containers can communicate with each other using localhost and share resources like memory and storage. + +Kubernetes dynamically manages Pods, ensuring they are running as specified and automatically restarting or replacing them if they fail. Pods can be distributed across Nodes for redundancy, making them fundamental to deploying and managing containerized applications (including databases) in Kubernetes. + + +## Storage Class +When creating disks for workloads inside a Pod, such as databases, you may need to specify the type of disk media, whether it's HDD or SSD. In cloud environments, there are often more options available. For example, AWS EBS offers various volume types, such as General Purpose SSD (gp2/gp3), Provisioned IOPS SSD (io1/io2), and Throughput Optimized HDD (st1). In Kubernetes, you can select the desired disk type through a StorageClass. + +## PVC +A Persistent Volume Claim (PVC) in Kubernetes is a request for storage by a user. A PVC is essentially a way to ask for storage with specific characteristics, such as storage class, size and access modes (e.g., read-write or read-only). PVCs enable Pods to use storage without needing to know the details of the underlying infrastructure. + +In K8s, to use this storage, users create a PVC. When a PVC is created, Kubernetes looks for a StorageClass that matches the request. If a matching StorageClass is found, it automatically provisions the storage according to the defined parameters—whether it's SSD, HDD, EBS or NAS. If a PVC does not specify a StorageClass, Kubernetes will use the default StorageClass (if one is configured) to provision storage. + +## CSI +In Kubernetes, various StorageClasses are provided through the Container Storage Interface (CSI), which is responsible for provisioning the underlying storage "disks" used by applications. CSI functions similarly to a "disk driver" in Kubernetes, enabling the platform to adapt to and integrate with a wide range of storage systems, such as local disks, AWS EBS, and Ceph. These StorageClasses, and the associated storage resources, are provisioned by specific CSI drivers that handle the interaction with the underlying storage infrastructure. + +CSI is a standard API that enables Kubernetes to interact with various storage systems in a consistent and extensible manner. CSI drivers, created by storage vendors or the Kubernetes community, expose essential storage functions like dynamic provisioning, attaching, mounting, and snapshotting to Kubernetes. + +When you define a StorageClass in Kubernetes, it typically specifies a CSI driver as its provisioner. This driver automatically provisions Persistent Volumes (PVs) based on the parameters in the StorageClass and associated Persistent Volume Claims (PVCs), ensuring the appropriate type and configuration of storage—whether SSD, HDD, or otherwise—is provided for your applications. + +## PV +In Kubernetes, a Persistent Volume (PV) represents a storage resource that can be backed by various systems like local disks, NFS, or cloud-based storage (e.g., AWS EBS, Google Cloud Persistent Disks), typically managed by different CSI drivers. + +A PV has its own lifecycle, independent of the Pod, and is managed by the Kubernetes control plane. It allows data to persist even if the associated Pod is deleted. PVs are bound to Persistent Volume Claims (PVCs), which request specific storage characteristics like size and access modes, ensuring that applications receive the storage they require. + +In summary, PV is the actual storage resource, while PVC is a request for storage. Through the StorageClass in the PVC, it can be bound to a PV provisioned by different CSI drivers. + +## Service +In Kubernetes, a Service acts as a load balancer. It defines a logical set of Pods and provides a policy for accessing them. Since Pods are ephemeral and can be dynamically created and destroyed, their IP addresses are not stable. A Service resolves this issue by providing a stable network endpoint (a virtual IP address, known as a ClusterIP) that remains constant, allowing other Pods or external clients to communicate with the set of Pods behind the Service without needing to know their specific IP addresses. + +Service supports different types: ClusterIP (internal cluster access), NodePort (external access via :), LoadBalancer (exposes the Service externally using a cloud provider’s load balancer), and ExternalName (maps the Service to an external DNS). + + +## ConfigMap + +A ConfigMap is used to store configuration data in key-value pairs, allowing you to decouple configuration from application code. This way, you can manage application settings separately and reuse them across multiple environments. ConfigMaps can be used to inject configuration data into Pods as environment variables, command-line arguments, or configuration files. They provide a flexible and convenient way to manage application configurations without hardcoding values directly into your application container. + + +## Secret + +A Secret is used to store sensitive data such as passwords, tokens, or encryption keys. Secrets allow you to manage confidential information separately from your application code and avoid exposing sensitive data in your container images. Kubernetes Secrets can be injected into Pods as environment variables or mounted as files, ensuring that sensitive information is handled in a secure and controlled manner. + +However, Secrets are not encrypted by default—they are simply base64-encoded, which does not provide real encryption. They should still be used with care, ensuring proper access controls are in place. + +## CRD +If you want to manage database objects using Kubernetes, you need to extend the Kubernetes API to describe the database objects you're managing. This is where the CRD (Custom Resource Definition) mechanism comes in, allowing you to define custom resources specific to your use case, such as database clusters or backups, and manage them just like native Kubernetes resources. + +## CR +A Custom Resource (CR) is an instance of a Custom Resource Definition (CRD). It represents a specific configuration or object that extends the Kubernetes API. CRs allow you to define and manage custom resources, such as databases or applications, using Kubernetes' native tools. Once a CR is created, Kubernetes controllers or Operators monitor it and perform actions to maintain the desired state. + +CRD and CR are the foundation for developing a Kubernetes Operator. CRDs are often used to implement custom controllers or operators, allowing for continuously watches for changes to CRs (representing, for example, database clusters) and automatically performs actions. + +## What is Kubernetes Operator? + +A Kubernetes Operator is a software, typically composed of one or more controllers, that automates the management of complex applications by translating changes made to a Custom Resource (CR) into actions on native Kubernetes objects, such as Pods, Services, PVCs, ConfigMaps, and Secrets. + +- Input: User modifications to the CR. +- Output: Corresponding changes to underlying Kubernetes resources or interactions with external systems (e.g., writing to a database or calling APIs), depending on the requirements of the managed application. + +The Operator continuously watches the state of these Kubernetes objects. When changes occur (e.g., a Pod crashes), the Operator automatically takes corrective actions, like recreating the Pod or adjusting traffic (e.g., updating Service Endpoints). + +In essence, a Kubernetes Operator encapsulates complex operational knowledge into software, automating tasks like deployment, scaling, upgrades, and backups, ensuring the application consistently maintains its desired state without manual intervention. + +## Helm and Helm Chart + +Helm is a popular package manager for Kubernetes that helps manage and deploy applications. It packages all the necessary Kubernetes resources into a single Helm Chart, allowing you to install applications with a single command (helm install). Helm also handles configuration management and updates (helm upgrade), making the entire lifecycle of the application much easier to manage. +Key components of a Helm Chart: + +- Templates: YAML files with placeholders that define Kubernetes resources (like Pods, Services, and ConfigMaps). +- Values.yaml: A file where users specify default values for the templates, allowing easy customization. Helm allows you to take an existing chart and override the default values using values.yaml or command-line flags, enabling you to provide environment-specific configurations without modifying the underlying templates. +- Chart.yaml: Metadata about the chart, including the name, version, and description. + +Helm integrates well with CI/CD tools like Jenkins, GitLab CI, and GitHub Actions. It can be used to automate deployments and rollbacks as part of a continuous delivery pipeline, ensuring that applications are consistently deployed across different environments. \ No newline at end of file diff --git a/docs/user_docs/overview/supported-addons.md b/docs/user_docs/overview/supported-addons.md index bde945ab242..ed500c0e09f 100644 --- a/docs/user_docs/overview/supported-addons.md +++ b/docs/user_docs/overview/supported-addons.md @@ -2,7 +2,7 @@ title: Supported addons description: Addons supported by KubeBlocks keywords: [addons, enable, KubeBlocks, prometheus, s3, alertmanager,] -sidebar_position: 3 +sidebar_position: 4 sidebar_label: Supported addons --- diff --git a/docs/api_docs/connect_database/_category_.yml b/docs/user_docs/upgrade/_category_.yml similarity index 66% rename from docs/api_docs/connect_database/_category_.yml rename to docs/user_docs/upgrade/_category_.yml index c84c1e9c2d8..2a6c5143ff8 100644 --- a/docs/api_docs/connect_database/_category_.yml +++ b/docs/user_docs/upgrade/_category_.yml @@ -1,4 +1,4 @@ position: 4 -label: Connect Database +label: Upgrade collapsible: true collapsed: true \ No newline at end of file diff --git a/docs/user_docs/upgrade/upgrade with helm/_category_.yml b/docs/user_docs/upgrade/upgrade with helm/_category_.yml new file mode 100644 index 00000000000..47e3fb2677a --- /dev/null +++ b/docs/user_docs/upgrade/upgrade with helm/_category_.yml @@ -0,0 +1,4 @@ +position: 2 +label: Upgrade with helm +collapsible: true +collapsed: true \ No newline at end of file diff --git a/docs/api_docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md b/docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.8.md similarity index 88% rename from docs/api_docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md rename to docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.8.md index e0ad7e3b701..ab0e5123d9b 100644 --- a/docs/api_docs/installation/upgrade/upgrade-kubeblocks-to-0.8.md +++ b/docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.8.md @@ -19,22 +19,6 @@ Execute `helm -n kb-system list | grep kubeblocks` to check the current KubeBloc ::: -## Upgrade from KubeBlocks v0.6 - -If you are currently running KubeBlocks v0.6, please upgrade to v0.7.2 first. - -1. Download kbcli v0.7.2. - - ```bash - curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.7.2 - ``` - -2. Upgrade to KubeBlocks v0.7.2. - - ```bash - kbcli kb upgrade --version 0.7.2 - ``` - ## Upgrade from KubeBlocks v0.7 1. Set keepAddons. diff --git a/docs/api_docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md b/docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.9.md similarity index 97% rename from docs/api_docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md rename to docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.9.md index 96e924960b0..da92bb21825 100644 --- a/docs/api_docs/installation/upgrade/upgrade-kubeblocks-to-0.9.md +++ b/docs/user_docs/upgrade/upgrade with helm/upgrade-kubeblocks-to-0.9.md @@ -18,7 +18,7 @@ Execute `helm -n kb-system list | grep kubeblocks` to check the current KubeBloc ## Compatibility -KubeBlocks 0.9 is compatible with KubeBlocks 0.8 APIs, but compatibility with APIs from versions prior to v0.8 is not guaranteed. If you are using addons from KubeBlocks 0.7 or earlier (v0.7., 0.6., etc), DO [upgrade KubeBlocks and all addons to v0.8 first](./upgrade-kubeblocks-to-0.8.md) to ensure service availability before upgrading to v0.9. +KubeBlocks 0.9 is compatible with KubeBlocks 0.8 APIs, but compatibility with APIs from versions prior to v0.8 is not guaranteed. If you are using addons from KubeBlocks 0.7 or earlier (v0.7., 0.6., etc), DO [upgrade KubeBlocks and all addons to v0.8 first](upgrade-kubeblocks-to-0.8.md) to ensure service availability before upgrading to v0.9. ## Upgrade from KubeBlocks v0.8 diff --git a/docs/user_docs/upgrade/upgrade with kbcli/_category_.yml b/docs/user_docs/upgrade/upgrade with kbcli/_category_.yml new file mode 100644 index 00000000000..134ba5d56b3 --- /dev/null +++ b/docs/user_docs/upgrade/upgrade with kbcli/_category_.yml @@ -0,0 +1,4 @@ +position: 1 +label: Upgrade with kbcli +collapsible: true +collapsed: true \ No newline at end of file diff --git a/docs/user_docs/upgrade/upgrade with kbcli/upgrade-kubeblocks-to-0.8.md b/docs/user_docs/upgrade/upgrade with kbcli/upgrade-kubeblocks-to-0.8.md new file mode 100644 index 00000000000..3ab961e2f77 --- /dev/null +++ b/docs/user_docs/upgrade/upgrade with kbcli/upgrade-kubeblocks-to-0.8.md @@ -0,0 +1,55 @@ +--- +title: Upgrade to KubeBlocks v0.8 +description: Upgrade to KubeBlocks v0.8, operation, tips and notes +keywords: [upgrade, 0.8] +sidebar_position: 2 +sidebar_label: Upgrade to KubeBlocks v0.8 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +# Upgrade to KubeBlocks v0.8 + +In this tutorial, you will learn how to upgrade to KubeBlocks v0.8. + +:::note + +Execute `kbcli version` to check the current KubeBlocks version you are running, and then upgrade. + +::: + +## Upgrade from KubeBlocks v0.6 + +If you are currently running KubeBlocks v0.6, please upgrade to v0.7.2 first. + +1. Download kbcli v0.7.2. + + ```shell + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.7.2 + ``` + +2. Upgrade to KubeBlocks v0.7.2. + + ```shell + kbcli kb upgrade --version 0.7.2 + ``` + +## Upgrade from KubeBlocks v0.7 + +1. Download kbcli v0.8. + + ```shell + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.8.1 + ``` + +2. Upgrade KubeBlocks. + + ```shell + + kbcli kb upgrade --version 0.8.1 --set dataProtection.image.datasafed.tag=0.1.0 + + ``` + + kbcli will automatically add the annotation `"helm.sh/resource-policy": "keep"` to ensure that existing addons are not deleted during the upgrade. \ No newline at end of file diff --git a/docs/user_docs/upgrade/upgrade with kbcli/upgrade-kubeblocks-to-0.9.md b/docs/user_docs/upgrade/upgrade with kbcli/upgrade-kubeblocks-to-0.9.md new file mode 100644 index 00000000000..0129db2e36b --- /dev/null +++ b/docs/user_docs/upgrade/upgrade with kbcli/upgrade-kubeblocks-to-0.9.md @@ -0,0 +1,72 @@ +--- +title: Upgrade to KubeBlocks v0.9 +description: Upgrade to KubeBlocks v0.9, operation, tips and notes +keywords: [upgrade, 0.9] +sidebar_position: 1 +sidebar_label: Upgrade to KubeBlocks v0.9 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Upgrade to KubeBlocks v0.9 + +In this tutorial, you will learn how to upgrade to KubeBlocks v0.9. + +:::note + +Execute `kbcli version` to check the current KubeBlocks version you are running, and then upgrade. + +::: + +## Compatibility + +KubeBlocks 0.9 is compatible with KubeBlocks 0.8 APIs, but compatibility with APIs from versions prior to v0.8 is not guaranteed. If you are using addons from KubeBlocks 0.7 or earlier (v0.7., 0.6., etc), DO [upgrade KubeBlocks and all addons to v0.8 first](upgrade-kubeblocks-to-0.8.md) to ensure service availability before upgrading to v0.9. + +## Upgrade from KubeBlocks v0.8 + +1. Download kbcli v0.9. + + ```shell + curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash -s 0.9.0 + ``` + +2. Upgrade KubeBlocks. + + ```bash + kbcli kb upgrade --version 0.9.0 + ``` + + :::note + + To avoid affecting existing database clusters, when upgrading to KubeBlocks v0.9, the versions of already-installed addons will not be upgraded by default. If you want to upgrade the addons to the versions built into KubeBlocks v0.9, execute the following command. Note that this may restart existing clusters and affect availability. Please proceed with caution. + + ```bash + kbcli kb upgrade --version 0.9.0 --set upgradeAddons=true + ``` + + ::: + + kbcli will automatically add the annotation `"helm.sh/resource-policy": "keep"` to ensure that existing addons are not deleted during the upgrade. + + +## Upgrade addons + +If you didn't specify `upgradeAddons` as `true` or your addon is not included in the default installed addons, you can upgrade addons by the options provided below to use the v0.9.0 API. + +:::note + +If the addon you want to upgrade is `mysql`, you need to upgrade this addon and restart the cluster. Otherwise, the cluster created in KubeBlocks v0.8 cannot be used in v0.9. + +If the addon you want to use is `clickhouse/milvus/elasticsearch/llm`, you need to upgrade KubeBlocks first and then upgrade this addon. Otherwise, these addons cannot be used in KubeBlocks v0.9 normally. + +::: + + +```bash +kbcli addon index list + +kbcli addon index update kubeblocks + +kbcli addon upgrade xxx --force +```