Skip to main content

KubeBlocks

KubeBlocks is a cloud-native database management operator that simplifies the deployment and management of databases on Kubernetes. This guide demonstrates how to deploy and manage FalkorDB using the KubeBlocks operator.

What is KubeBlocks?​

KubeBlocks is an open-source Kubernetes operator designed to manage stateful workloads, particularly databases. It provides:

  • Unified Management: Manage multiple database engines through a consistent API
  • Day-2 Operations: Automated scaling, backup, restore, monitoring, and failover
  • Production-Ready: Built for production environments with high availability
  • Multi-Topology Support: Standalone, replication, and sharding configurations

Prerequisites​

Before you begin, ensure you have:

Installing KubeBlocks​

If you haven't installed KubeBlocks yet, follow these steps:

Step 1: Install KubeBlocks Operator​

# Add the KubeBlocks Helm repository
helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update

# Install KubeBlocks
helm install kubeblocks kubeblocks/kubeblocks --namespace kb-system --create-namespace

Wait for KubeBlocks to be ready:

kubectl get pods -n kb-system

Step 2: Install FalkorDB Addon​

Enable the FalkorDB addon for KubeBlocks. You can use either the kbcli command-line tool or Helm.

First, install kbcli:

# Install kbcli
curl -fsSL https://kubeblocks.io/installer/install_cli.sh | bash

# Verify installation
kbcli version

Then install the FalkorDB addon:

# Install the FalkorDB addon
kbcli addon install falkordb

# Verify the addon is enabled
kbcli addon list | grep falkordb

Option B: Using Helm​

# Add the KubeBlocks addons Helm repository
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts
helm repo update

# Install the FalkorDB addon
helm install falkordb-addon kubeblocks-addons/falkordb

# Verify the addon is installed
helm list -A | grep falkordb

Step 3: Create a Namespace​

Create a dedicated namespace for your FalkorDB instances:

kubectl create namespace demo

Deployment Options​

KubeBlocks supports three deployment topologies for FalkorDB:

  1. Standalone - Single instance for development and testing
  2. Replication - High availability with primary/secondary nodes and Sentinel
  3. Sharding - Horizontal scalability with multiple shards (Redis Cluster mode)

Option 1: Standalone Deployment​

A standalone deployment is ideal for development, testing, or small workloads.

Create a Standalone Cluster​

Create a file named falkordb-standalone.yaml:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: falkordb-standalone
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: falkordb
  topology: standalone
  componentSpecs:
  - name: falkordb
    replicas: 1
    resources:
      limits:
        cpu: "0.5"
        memory: "0.5Gi"
      requests:
        cpu: "0.5"
        memory: "0.5Gi"
    volumeClaimTemplates:
    - name: data
      spec:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 20Gi

Apply the configuration:

kubectl apply -f falkordb-standalone.yaml

Monitor the cluster creation:

# Check cluster status
kubectl get cluster -n demo falkordb-standalone

# View pods
kubectl get pods -n demo -l app.kubernetes.io/instance=falkordb-standalone

A replication deployment provides high availability with automatic failover using Redis Sentinel.

Understanding the Architecture​

The replication topology includes:

  • FalkorDB Component: Primary and secondary nodes for data storage and queries
  • Sentinel Component: Monitors FalkorDB nodes and manages automatic failover
  • Minimum of 3 Sentinel Replicas: Required for quorum-based failover decisions

Create a Replication Cluster​

Create a file named falkordb-replication.yaml:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: falkordb-replication
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: falkordb
  topology: replication
  componentSpecs:
  - name: falkordb
    serviceVersion: "4.12.5"
    disableExporter: false
    replicas: 2
    resources:
      limits:
        cpu: "0.5"
        memory: "0.5Gi"
      requests:
        cpu: "0.5"
        memory: "0.5Gi"
    volumeClaimTemplates:
    - name: data
      spec:
        storageClassName: ""
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 20Gi
  - name: falkordb-sent
    serviceVersion: "4.12.5"
    replicas: 3
    resources:
      limits:
        cpu: "0.5"
        memory: "0.5Gi"
      requests:
        cpu: "0.5"
        memory: "0.5Gi"
    volumeClaimTemplates:
    - name: data
      spec:
        storageClassName: ""
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 20Gi

Apply the configuration:

kubectl apply -f falkordb-replication.yaml

Why Does Sentinel Start First?​

KubeBlocks ensures that Sentinel instances start before FalkorDB replicas. This is because:

  1. Each FalkorDB replica queries Sentinel on startup to determine if a primary node exists
  2. If no primary exists, the replica configures itself as the primary
  3. If a primary exists, the replica configures itself as a secondary and begins replication

This startup sequence is defined in the ClusterDefinition and ensures proper cluster initialization.

Verify the Deployment​

Check the cluster status:

# View cluster information
kubectl get cluster -n demo falkordb-replication

# View all pods
kubectl get pods -n demo -l app.kubernetes.io/instance=falkordb-replication

# Check roles of FalkorDB pods
kubectl get pods -n demo -l app.kubernetes.io/instance=falkordb-replication,apps.kubeblocks.io/component-name=falkordb -L kubeblocks.io/role

Expected output shows one primary and one or more secondary pods.

Option 3: Sharding Deployment​

A sharding deployment distributes data across multiple shards for horizontal scalability.

Create a Sharding Cluster​

Create a file named falkordb-sharding.yaml:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: falkordb-sharding
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: falkordb
  topology: sharding
  shardings:
  - name: shard
    shards: 3
    template:
      name: falkordb
      componentDef: falkordb-cluster-4
      replicas: 2
      serviceVersion: "4.12.5"
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
      - name: data
        spec:
          accessModes:
          - ReadWriteOnce
          resources:
            requests:
              storage: 20Gi

Apply the configuration:

kubectl apply -f falkordb-sharding.yaml

This creates a cluster with 3 shards, each having 2 replicas (1 primary + 1 secondary).

Connecting to FalkorDB​

Step 1: Get Connection Credentials​

Retrieve the password for your FalkorDB instance:

# For replication cluster
kubectl get secret -n demo falkordb-replication-conn-credential -o jsonpath='{.data.password}' | base64 -d

Step 2: Port Forward to the Cluster​

Enable local access to the FalkorDB service:

# For standalone
kubectl port-forward -n demo svc/falkordb-standalone-falkordb 6379:6379

# For replication
kubectl port-forward -n demo svc/falkordb-replication-falkordb 6379:6379

# For sharding
kubectl port-forward -n demo svc/falkordb-sharding-shard-5rf-falkordb 6379:6379

Step 3: Connect Using redis-cli​

Connect to your FalkorDB instance:

redis-cli -h 127.0.0.1 -p 6379 -a <your-password>

Step 4: Run a Test Query​

Execute a simple Cypher query to verify the connection:

GRAPH.QUERY social "CREATE (:Person {name: 'Alice', age: 30})-[:KNOWS]->(:Person {name: 'Bob', age: 25})"
GRAPH.QUERY social "MATCH (p:Person) RETURN p.name, p.age"

Day-2 Operations​

KubeBlocks provides comprehensive Day-2 operations for managing your FalkorDB clusters.

Horizontal Scaling​

Scale Out​

Add more replicas to your cluster:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-scale-out
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: HorizontalScaling
  horizontalScaling:
  - componentName: falkordb
    scaleOut:
      replicaChanges: 1

Apply the scaling operation:

kubectl apply -f scale-out.yaml

Scale In​

Remove replicas from your cluster:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-scale-in
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: HorizontalScaling
  horizontalScaling:
  - componentName: falkordb
    scaleIn:
      replicaChanges: 1

Alternatively, update the cluster directly:

kubectl patch cluster -n demo falkordb-replication --type merge -p '{"spec":{"componentSpecs":[{"name":"falkordb","replicas":3}]}}'

Vertical Scaling​

Update CPU and memory resources:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-vertical-scale
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: VerticalScaling
  verticalScaling:
  - componentName: falkordb
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "2"
      memory: "4Gi"

Volume Expansion​

Expand storage volume (requires storage class with volume expansion support):

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-volume-expand
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: VolumeExpansion
  volumeExpansion:
  - componentName: falkordb
    volumeClaimTemplates:
    - name: data
      storage: 30Gi

Restart Cluster​

Restart all components:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-restart
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: Restart
  restart:
  - componentName: falkordb

Stop and Start​

Stop the cluster (releases pods but retains storage):

kubectl patch cluster -n demo falkordb-replication --type merge -p '{"spec":{"componentSpecs":[{"name":"falkordb","stop":true},{"name":"falkordb-sent","stop":true}]}}'

Start the cluster:

kubectl patch cluster -n demo falkordb-replication --type merge -p '{"spec":{"componentSpecs":[{"name":"falkordb","stop":false},{"name":"falkordb-sent","stop":false}]}}'

Configuration Management​

Reconfigure Parameters​

Update FalkorDB configuration dynamically:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-reconfigure
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: Reconfiguring
  reconfigure:
    componentName: falkordb
    configurations:
    - name: falkordb-config
      keys:
      - key: redis.conf
        parameters:
        - key: maxclients
          value: "10001"

Some parameters (like maxclients) require a restart. KubeBlocks will handle this automatically.

Verify the configuration:

kubectl exec -it -n demo falkordb-replication-falkordb-0 -- redis-cli CONFIG GET maxclients

Backup and Restore​

Create a Backup Repository​

Before creating backups, configure a backup repository:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: BackupRepo
metadata:
  name: my-backup-repo
spec:
  storageProviderRef: s3
  config:
    bucket: my-falkordb-backups
    endpoint: s3.amazonaws.com
    region: us-west-2
  credential:
    name: s3-credentials
    namespace: demo

Full Backup​

Create a full backup using Redis BGSAVE:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: falkordb-backup
  namespace: demo
spec:
  backupPolicyName: falkordb-replication-falkordb-backup-policy
  backupMethod: datafile

Apply the backup:

kubectl apply -f backup.yaml

Check backup status:

kubectl get backup -n demo falkordb-backup

Continuous Backup (Point-in-Time Recovery)​

Enable continuous backup using AOF (Append-Only File):

  1. Enable AOF timestamps:
apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: enable-aof-timestamps
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: Reconfiguring
  reconfigure:
    componentName: falkordb
    configurations:
    - name: falkordb-config
      keys:
      - key: redis.conf
        parameters:
        - key: aof-timestamp-enabled
          value: "yes"
  1. Update the BackupSchedule to enable AOF backup:
kubectl edit backupschedule -n demo falkordb-replication-falkordb-backup-schedule

Set enabled: true for the aof backup method.

Restore from Backup​

Restore a new cluster from a backup:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: falkordb-restored
  namespace: demo
  annotations:
    kubeblocks.io/restore-from-backup: '{"falkordb":{"name":"falkordb-backup","namespace":"demo"}}'
spec:
  clusterDef: falkordb
  topology: replication
  componentSpecs:
  - name: falkordb
    serviceVersion: "4.12.5"
    replicas: 2
    resources:
      limits:
        cpu: "0.5"
        memory: "0.5Gi"
      requests:
        cpu: "0.5"
        memory: "0.5Gi"
    volumeClaimTemplates:
    - name: data
      spec:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 20Gi

Exposing Services​

Expose via LoadBalancer​

Expose FalkorDB to external clients:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: falkordb-expose
  namespace: demo
spec:
  clusterName: falkordb-replication
  type: Expose
  expose:
  - componentName: falkordb
    services:
    - name: external
      serviceType: LoadBalancer
      annotations:
        # Add cloud-specific annotations as needed
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"

For different cloud providers, use appropriate annotations:

# AWS
service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
service.beta.kubernetes.io/aws-load-balancer-internal: "false"

# Azure
service.beta.kubernetes.io/azure-load-balancer-internal: "false"

# GCP
cloud.google.com/l4-rbs: "enabled"

# Alibaba Cloud
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type: "internet"

Expose via NodePort​

For on-premises or development environments:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: falkordb-replication
  namespace: demo
spec:
  # ... other fields ...
  componentSpecs:
  - name: falkordb
    services:
    - name: falkordb-advertised
      serviceType: NodePort
      podService: true

Monitoring with Prometheus​

Enable Metrics Export​

Ensure metrics are enabled when creating the cluster:

spec:
  componentSpecs:
  - name: falkordb
    disableExporter: false  # Enable metrics exporter

Create PodMonitor​

Create a PodMonitor to scrape metrics:

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: falkordb-replication-pod-monitor
  namespace: demo
  labels:
    app.kubernetes.io/instance: falkordb-replication
spec:
  selector:
    matchLabels:
      app.kubernetes.io/instance: falkordb-replication
      apps.kubeblocks.io/component-name: falkordb
  podMetricsEndpoints:
  - port: http-metrics
    path: /metrics
    scheme: http

Apply the PodMonitor:

kubectl apply -f pod-monitor.yaml

Access Grafana Dashboard​

  1. Access your Grafana instance
  2. Import a Redis/FalkorDB dashboard from the Grafana dashboard store
  3. Configure the dashboard to use the correct job label (e.g., monitoring/falkordb-replication-pod-monitor)

Best Practices​

High Availability​

  • Use the replication topology with at least 3 Sentinel replicas
  • Distribute pods across availability zones using pod anti-affinity
  • Configure appropriate resource requests and limits
  • Enable automated backups with appropriate retention policies

Security​

  • Use Kubernetes secrets for storing passwords
  • Enable TLS for client connections (if required)
  • Use Network Policies to restrict access to FalkorDB pods
  • Regularly rotate credentials

Performance​

  • Choose appropriate storage class with good I/O performance
  • Monitor resource usage and scale vertically/horizontally as needed
  • For write-heavy workloads, consider disabling AOF timestamps
  • Use sharding topology for large datasets

Storage​

  • Ensure storage class supports volume expansion
  • Configure appropriate storage size based on expected data growth
  • Use persistent volumes with replication for data durability
  • Test backup and restore procedures regularly

Troubleshooting​

Cluster Not Ready​

If the cluster status remains Creating for an extended period:

# Check pod status
kubectl get pods -n demo -l app.kubernetes.io/instance=falkordb-replication

# Check pod logs
kubectl logs -n demo <pod-name>

# Describe the cluster for events
kubectl describe cluster -n demo falkordb-replication

Connection Issues​

If you cannot connect to FalkorDB:

# Verify service exists
kubectl get svc -n demo

# Check if pods are running
kubectl get pods -n demo -l app.kubernetes.io/instance=falkordb-replication

# Verify credentials
kubectl get secret -n demo falkordb-replication-conn-credential -o yaml

Backup Failures​

If backups fail:

# Check backup status
kubectl describe backup -n demo <backup-name>

# Check backup policy
kubectl get backuppolicy -n demo -o yaml

# Verify BackupRepo configuration
kubectl describe backuprepo my-backup-repo

Deleting the Cluster​

To delete a cluster and all its resources:

# Change termination policy to allow deletion
kubectl patch cluster -n demo falkordb-replication -p '{"spec":{"terminationPolicy":"WipeOut"}}' --type="merge"

# Delete the cluster
kubectl delete cluster -n demo falkordb-replication

Note: WipeOut policy deletes all data including backups. Use Delete policy to retain backups.

Additional Resources​

Summary​

KubeBlocks provides a powerful, production-ready solution for deploying and managing FalkorDB on Kubernetes. With support for multiple topologies, comprehensive Day-2 operations, and automated backup/restore capabilities, KubeBlocks simplifies the operational complexity of running FalkorDB in Kubernetes environments. Whether you need a simple standalone instance for development or a highly available sharded cluster for production, KubeBlocks has you covered.