diff --git a/docs/api_docs/connect_database/_category_.yml b/docs/api_docs/connect_database/_category_.yml deleted file mode 100644 index 812b4536b86..00000000000 --- a/docs/api_docs/connect_database/_category_.yml +++ /dev/null @@ -1,4 +0,0 @@ -position: 3 -label: Connect Database -collapsible: true -collapsed: true \ No newline at end of file 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 19070ed384a..00000000000 --- a/docs/api_docs/connect_database/connect-database-in-production-environment.md +++ /dev/null @@ -1,151 +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 `kubectl get service -`. - -```bash -kubectl get service mycluster-mysql -``` - -## 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. - -::: - -```yaml -kubectl apply -f - < - 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 27142fc6a68..00000000000 --- a/docs/api_docs/connect_database/overview-of-database-connection.md +++ /dev/null @@ -1,18 +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 the creation of clusters, the database runs on Kubernetes as a Pod. You can connect to the database via a client interface or `kubectl`. - -As the figure below indicates, you must be clear about 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/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..cdbfbb3525e 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,99 @@ 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).