LightRAG/k8s-deploy/databases/README.md

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 (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.

• Helm (v3.x+)

  • Kubernetes package manager used by the scripts below.
  • Install it via the official instructions: Installing Helm.

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:

   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 ./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 ./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:

   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:

   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:

   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:

kubectl get cluster -n rag

2. Retrieve Authentication Credentials

For PostgreSQL, retrieve the username and password from Kubernetes secrets:

# 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:

kubectl get secrets -n rag

3. Port Forward to Local Machine

Use port forwarding to access PostgreSQL from your local machine:

# 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:

# 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 ./03-uninstall-database.sh
   

   The script deletes the database clusters that were enabled in 00-config.sh.

2. Clean up KubeBlocks add-ons

   bash ./04-cleanup.sh
   

   This removes the addons installed by 01-prepare.sh.

Reference

• Kubeblocks Documentation