Skip to content

Installation and Setup Kubernetes and Helm Deployment Database and Storage Configuration

Jump to bottom
github-actions[bot] edited this page Aug 3, 2026 · 3 revisions

Database and Storage Configuration

Referenced Files in This Document

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides comprehensive guidance for configuring database and storage components in Kairos MCP deployments. It covers:

  • PostgreSQL cluster setup using the Percona Operator
  • Qdrant vector database configuration
  • Redis failover setup
  • Ollama stateful deployment
  • Persistent volume claims, storage classes, and backup strategies
  • Performance tuning parameters, connection pooling, and high availability configurations
  • Data migration procedures and disaster recovery planning

The content is derived from Helm templates, operator subscriptions, application service modules, and configuration files within the repository.

Project Structure

Kairos MCP deploys its data plane via Kubernetes Operators and Helm charts. The relevant infrastructure manifests are located under helm/kairos-mcp/templates and helm/operators. Application-side integration with Qdrant and Redis is implemented in src/services.

graph TB
subgraph "Helm Chart"
A["postgres-cluster-cr.yaml"]
B["redis-failover-cr.yaml"]
C["qdrant-hpa.yaml"]
D["qdrant-vpa.yaml"]
E["ollama-statefulset.yaml"]
F["values.yaml"]
G["values.schema.json"]
end
subgraph "Operators"
H["subscription-percona-postgresql-operator.yaml"]
I["subscription-redis-operator.yaml"]
end
subgraph "Application Services"
J["src/services/qdrant/connection.ts"]
K["src/services/qdrant/service.ts"]
L["src/services/qdrant/initialization.ts"]
M["src/services/redis.ts"]
N["src/services/key-value-store-factory.ts"]
O["src/config.ts"]
end
H --> A
I --> B
F --> A
F --> B
F --> C
F --> D
F --> E
J --> K
K --> L
M --> N
O --> J
O --> M
Loading

Diagram sources

Section sources

Core Components

  • PostgreSQL (Percona Operator): Deployed as a Cluster Custom Resource managed by the Percona PostgreSQL Operator.
  • Qdrant: Vector database configured via Helm values; autoscaling via HPA/VPA.
  • Redis: Failover cluster deployed via Redis Operator’s RedisFailover CR.
  • Ollama: Stateful workload for embeddings/inference, deployed as a StatefulSet.
  • Application Integration:
    • Qdrant client initialization and lifecycle management
    • Redis client and key-value store factory for caching and session/state
    • Centralized configuration loader

Key responsibilities:

  • Provisioning persistent storage for each component
  • Exposing services for application access
  • Enabling HA and autoscaling where applicable
  • Providing configuration hooks for performance tuning

Section sources

Architecture Overview

The following diagram shows how Kairos MCP integrates with its data stores and operators.

graph TB
subgraph "Kubernetes Cluster"
subgraph "Operators"
PGO["Percona Postgres Operator"]
RFO["Redis Operator"]
end
subgraph "Stateful Workloads"
PG["PostgreSQL Cluster (PGO)"]
REDIS["RedisFailover"]
QDRANT["Qdrant"]
OLLAMA["Ollama StatefulSet"]
end
subgraph "Kairos MCP App"
APP["Kairos Server"]
QDCL["Qdrant Client"]
REDISCL["Redis Client"]
end
end
APP --> QDCL
APP --> REDISCL
QDCL --> QDRANT
REDISCL --> REDIS
PGO --> PG
RFO --> REDIS
Loading

Diagram sources

Detailed Component Analysis

PostgreSQL Cluster (Percona Operator)

  • Deployment model: Managed by the Percona PostgreSQL Operator via a Cluster Custom Resource.
  • Persistence: Uses PVCs provisioned by the operator based on storage class settings.
  • High availability: Multi-replica clusters with automatic failover handled by the operator.
  • Backups: Operator-managed backups can be configured through the cluster CR.

Operational notes:

  • Ensure the Percona Operator subscription is installed before deploying the cluster CR.
  • Tune replica count, resources, and storage class according to workload requirements.
  • Use secrets for credentials and TLS if required.

Section sources

Qdrant Vector Database

  • Deployment: Configured via Helm values; autoscaled with HPA and VPA.
  • Initialization: Application initializes collections and performs readiness checks at startup.
  • Connection: Client connects to the Qdrant service endpoint defined in configuration.

Configuration highlights:

  • Autoscaling thresholds and resource requests/limits are set via HPA/VPA manifests.
  • Service exposure and internal DNS names are used by the application.

Section sources

Redis Failover

  • Deployment: RedisFailover CR managed by the Redis Operator.
  • Persistence: Optional persistence enabled via CR; uses PVCs backed by storage class.
  • High availability: Master-replica topology with automatic failover.

Operational notes:

  • Configure memory limits and persistence options in the RedisFailover CR.
  • Use TLS and authentication settings as needed for production.

Section sources

Ollama Stateful Deployment

  • Deployment: StatefulSet ensures stable network identity and persistent storage per replica.
  • Storage: PVCs attached to each pod for model artifacts and runtime state.
  • Scaling: Typically scaled to one primary replica for state consistency unless multi-node inference is explicitly supported.

Operational notes:

  • Allocate sufficient CPU/GPU and memory for embedding workloads.
  • Mount persistent volumes for model caches to avoid re-downloads.

Section sources

Application Integration and Configuration

  • Qdrant client: Initializes connections, manages collection lifecycle, and exposes retrieval/update methods.
  • Redis client: Provides cache and key-value store capabilities; integrated via a factory for different backends.
  • Central config: Loads environment-driven settings for endpoints, timeouts, and feature toggles.
sequenceDiagram
participant App as "Kairos Server"
participant QDInit as "Qdrant Initialization"
participant QDSvc as "Qdrant Service"
participant QDCli as "Qdrant Client"
participant QD as "Qdrant Service"
App->>QDInit : "Initialize Qdrant"
QDInit->>QDSvc : "Ensure collections exist"
QDSvc->>QDCli : "Create client instance"
QDCli->>QD : "Connect and verify health"
QD-->>QDCli : "OK"
QDCli-->>App : "Ready"
Loading

Diagram sources

Section sources

Dependency Analysis

The chart depends on external operators to manage stateful components. Values drive resource sizing, autoscaling, and feature flags.

graph LR
Chart["Chart.yaml"] --> Values["values.yaml"]
Values --> Schema["values.schema.json"]
Chart --> PGO["Percona Subscription"]
Chart --> RFOps["Redis Subscription"]
Chart --> PGCR["Postgres Cluster CR"]
Chart --> RF["RedisFailover CR"]
Chart --> QHPA["Qdrant HPA"]
Chart --> QVPA["Qdrant VPA"]
Chart --> Ollama["Ollama StatefulSet"]
Loading

Diagram sources

Section sources

Performance Considerations

  • PostgreSQL
    • Set appropriate replica counts and resource requests/limits in the cluster CR.
    • Choose a storage class with suitable IOPS and throughput for OLTP workloads.
    • Enable WAL archiving and configure backup schedules via the operator.
  • Qdrant
    • Size replicas and tune HPA thresholds based on vector dimensionality and query load.
    • Use VPA to right-size CPU/memory over time.
    • Ensure adequate disk space for index growth.
  • Redis
    • Configure memory limits and eviction policies in the RedisFailover CR.
    • Enable persistence only if durability is required; otherwise use ephemeral mode for speed.
    • Place on low-latency storage for cache-heavy workloads.
  • Ollama
    • Allocate GPU/CPU and memory proportional to model size and concurrency.
    • Persist model caches to avoid repeated downloads.
    • Limit concurrent requests if necessary to prevent resource exhaustion.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Connectivity issues
    • Verify service endpoints and DNS resolution for Qdrant and Redis.
    • Check TLS and authentication settings in application configuration.
  • Startup failures
    • Inspect Qdrant initialization logs for collection creation errors.
    • Confirm Redis connectivity and permissions.
  • Storage problems
    • Validate PVC bindings and storage class availability.
    • Review operator status for PostgreSQL and RedisFailover.
  • Backup and restore
    • Use operator-native backup mechanisms for PostgreSQL and Redis.
    • For Qdrant, leverage snapshotting features exposed by the service.

Section sources

Conclusion

Kairos MCP leverages Kubernetes Operators and Helm to deploy and manage its data plane components. By correctly configuring the Percona PostgreSQL cluster, Qdrant, Redis failover, and Ollama stateful sets—along with appropriate storage classes, autoscaling, and backup strategies—you can achieve a robust, scalable, and high-availability deployment. Application-side integration points provide clear hooks for initialization, health checks, and operational controls.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Persistent Volume Claims and Storage Classes

  • PostgreSQL: PVCs are created by the Percona Operator based on the cluster CR and storage class.
  • Redis: Optional persistence uses PVCs defined in the RedisFailover CR.
  • Qdrant: If persistence is enabled, PVCs are bound per replica.
  • Ollama: Each replica mounts a PVC for model artifacts and runtime state.

Section sources

Backup Strategies

  • PostgreSQL: Use Percona Operator backup resources and retention policies.
  • Redis: Enable persistence and schedule snapshots; consider offloading to object storage.
  • Qdrant: Utilize snapshot APIs or operator-backed mechanisms if available.
  • Ollama: Snapshot PVC contents or replicate models across nodes.

Section sources

Data Migration Procedures

  • PostgreSQL: Perform logical dumps and restores using operator tools or pg_dump/pg_restore workflows.
  • Qdrant: Export/import collections via snapshotting and restoration steps.
  • Redis: Dump RDB/AOF and restore to new instances during upgrades.
  • Ollama: Copy model directories between PVCs or pre-warm images.

Section sources

Disaster Recovery Planning

  • Define RPO/RTO targets for each component.
  • Automate backups and test restores regularly.
  • Maintain runbooks for operator-driven failovers and manual interventions.
  • Keep configuration drift under control via GitOps and versioned Helm values.

[No sources needed since this section provides general guidance]

KAIROS MCP

Clone this wiki locally