File size: 6,351 Bytes
9492c76 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 |
# Using KubeBlocks to Deploy and Manage Databases
Learn how to quickly deploy and manage various databases in a Kubernetes (K8s) environment through KubeBlocks.
## Introduction to KubeBlocks
KubeBlocks is a production-ready, open-source toolkit that runs any database--SQL, NoSQL, vector, or document--on Kubernetes.
It scales smoothly from quick dev tests to full production clusters, making it a solid choice for RAG workloads like FastGPT that need several data stores working together.
## Prerequisites
Make sure the following tools are installed and configured:
* **Kubernetes cluster**
* A running Kubernetes cluster is required.
* For local development or demos you can use [Minikube](https://minikube.sigs.k8s.io/docs/start/) (needs ≥ 2 CPUs, ≥ 4 GB RAM, and Docker/VM-driver support).
* Any standard cloud or on-premises Kubernetes cluster (EKS, GKE, AKS, etc.) also works.
* **kubectl**
* The Kubernetes command-line interface.
* Follow the official guide: [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl).
* **Helm** (v3.x+)
* Kubernetes package manager used by the scripts below.
* Install it via the official instructions: [Installing Helm](https://helm.sh/docs/intro/install/).
## Installing
1. **Configure the databases you want**
Edit `00-config.sh` file. Based on your requirements, set the variable to `true` for the databases you want to install.
For example, to install PostgreSQL and Neo4j:
```bash
ENABLE_POSTGRESQL=true
ENABLE_REDIS=false
ENABLE_ELASTICSEARCH=false
ENABLE_QDRANT=false
ENABLE_MONGODB=false
ENABLE_NEO4J=true
```
2. **Prepare the environment and install KubeBlocks add-ons**
```bash
bash ./01-prepare.sh
```
*What the script does*
`01-prepare.sh` performs basic pre-checks (Helm, kubectl, cluster reachability), adds the KubeBlocks Helm repo, and installs any core CRDs or controllers that KubeBlocks itself needs. It also installs the addons for every database you enabled in `00-config.sh`, but **does not** create the actual database clusters yet.
3. **(Optional) Modify database settings**
Before deployment you can edit the `values.yaml` file inside each `<db>/` directory to change `version`, `replicas`, `CPU`, `memory`, `storage size`, etc.
4. **Install the database clusters**
```bash
bash ./02-install-database.sh
```
*What the script does*
`02-install-database.sh` **actually deploys the chosen databases to Kubernetes**.
When the script completes, confirm that the clusters are up. It may take a few minutes for all the clusters to become ready,
especially if this is the first time running the script as Kubernetes needs to pull container images from registries.
You can monitor the progress using the following commands:
```bash
kubectl get clusters -n rag
NAME CLUSTER-DEFINITION TERMINATION-POLICY STATUS AGE
es-cluster Delete Running 11m
mongodb-cluster mongodb Delete Running 11m
pg-cluster postgresql Delete Running 11m
qdrant-cluster qdrant Delete Running 11m
redis-cluster redis Delete Running 11m
```
You can see all the Database `Pods` created by KubeBlocks.
Initially, you might see pods in `ContainerCreating` or `Pending` status - this is normal while images are being pulled and containers are starting up.
Wait until all pods show `Running` status:
```bash
kubectl get po -n rag
NAME READY STATUS RESTARTS AGE
es-cluster-mdit-0 2/2 Running 0 11m
mongodb-cluster-mongodb-0 2/2 Running 0 11m
pg-cluster-postgresql-0 4/4 Running 0 11m
pg-cluster-postgresql-1 4/4 Running 0 11m
qdrant-cluster-qdrant-0 2/2 Running 0 11m
redis-cluster-redis-0 2/2 Running 0 11m
```
You can also check the detailed status of a specific pod if it's taking longer than expected:
```bash
kubectl describe pod <pod-name> -n rag
```
## Connect to Databases
To connect to your databases, follow these steps to identify available accounts, retrieve credentials, and establish connections:
### 1. List Available Database Clusters
First, view the database clusters running in your namespace:
```bash
kubectl get cluster -n rag
```
### 2. Retrieve Authentication Credentials
For PostgreSQL, retrieve the username and password from Kubernetes secrets:
```bash
# Get PostgreSQL username
kubectl get secrets -n rag pg-cluster-postgresql-account-postgres -o jsonpath='{.data.username}' | base64 -d
# Get PostgreSQL password
kubectl get secrets -n rag pg-cluster-postgresql-account-postgres -o jsonpath='{.data.password}' | base64 -d
```
If you have trouble finding the correct secret name, list all secrets:
```bash
kubectl get secrets -n rag
```
### 3. Port Forward to Local Machine
Use port forwarding to access PostgreSQL from your local machine:
```bash
# Forward PostgreSQL port (5432) to your local machine
# You can see all services with: kubectl get svc -n rag
kubectl port-forward -n rag svc/pg-cluster-postgresql-postgresql 5432:5432
```
### 4. Connect Using Database Client
Now you can connect using your preferred PostgreSQL client with the retrieved credentials:
```bash
# Example: connecting with psql
export PGUSER=$(kubectl get secrets -n rag pg-cluster-postgresql-account-postgres -o jsonpath='{.data.username}' | base64 -d)
export PGPASSWORD=$(kubectl get secrets -n rag pg-cluster-postgresql-account-postgres -o jsonpath='{.data.password}' | base64 -d)
psql -h localhost -p 5432 -U $PGUSER
```
Keep the port-forwarding terminal running while you're connecting to the database.
## Uninstalling
1. **Remove the database clusters**
```bash
bash ./03-uninstall-database.sh
```
The script deletes the database clusters that were enabled in `00-config.sh`.
2. **Clean up KubeBlocks add-ons**
```bash
bash ./04-cleanup.sh
```
This removes the addons installed by `01-prepare.sh`.
## Reference
* [Kubeblocks Documentation](https://kubeblocks.io/docs/preview/user_docs/overview/introduction)
|