Skip to content

Deployment and Operations Kubernetes Deployment Helm Chart Configuration

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

Helm Chart 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 Helm chart configuration guidance for Kairos MCP. It explains all available values, environment-specific configurations, secret management, and custom resource definitions (CRDs) used to deploy the application with PostgreSQL, Redis, Keycloak, and optional components like Qdrant. It also includes examples for common deployment scenarios, configuration overrides, and production best practices.

Project Structure

The Helm charts are organized under helm/kairos-mcp with templates that render Kubernetes resources. Environment-specific values files are provided at helm/values.dev.yaml and helm/values.prod.yaml. The top-level helm/README.md documents usage patterns and conventions.

graph TB
subgraph "Helm Chart"
A["values.yaml"]
B["Chart.yaml"]
C["templates/*"]
end
subgraph "Environment Values"
D["values.dev.yaml"]
E["values.prod.yaml"]
end
subgraph "Docs"
F["helm/README.md"]
G["docs/install/helm.md"]
end
A --> C
B --> C
D --> C
E --> C
F --> C
G --> C
Loading

Diagram sources

Section sources

Core Components

Kairos MCP is deployed as a Kubernetes Deployment with supporting services and CRDs:

  • Application Deployment: renders from kairos-mcp-deployment.yaml and consumes values for image, replicas, resources, probes, and environment variables.
  • Database: Percona PostgreSQL cluster via postgres-cluster-cr.yaml.
  • Cache/Session: Redis Failover via redis-failover-cr.yaml.
  • Identity: Keycloak via keycloak-cr.yaml and related routes.
  • Ingress/Gateway: Gateway and HTTPRoute resources for external access.
  • Autoscaling: HPA for app and Qdrant.
  • Secrets: Generated by credentials-secret-generator-job.yaml.

Key value categories:

  • Application settings: image, replicas, resources, probes, logging, metrics, feature flags.
  • Database connections: host, port, database name, credentials, SSL options.
  • Redis configuration: host, port, password, TLS, failover mode.
  • Keycloak integration: issuer URL, client ID/secret, realms, admin endpoints.
  • Networking: gateway class, TLS secrets, route hosts.
  • Observability: service monitors, Prometheus rules.
  • Optional components: Qdrant storage, Ollama.

Section sources

Architecture Overview

The following diagram maps core runtime components and their relationships as rendered by the Helm chart.

graph TB
Client["Client / Browser"]
GW["Gateway + HTTPRoute"]
App["Kairos MCP Deployment"]
PG["PostgreSQL Cluster"]
R["Redis Failover"]
KC["Keycloak"]
Q["Qdrant (optional)"]
Client --> GW
GW --> App
App --> PG
App --> R
App --> KC
App --> Q
Loading

Diagram sources

Detailed Component Analysis

Application Settings (Deployment)

  • Image and tags: control container image and version.
  • Replicas and autoscaling: base replica count and HPA targets.
  • Resources: CPU/memory requests and limits.
  • Probes: liveness/readiness/startup probes for health checks.
  • Logging and metrics: log levels, structured logging, metrics endpoint exposure.
  • Feature flags: toggles for UI, MCP features, and integrations.
  • Environment variables: derived from values and secrets; include DB, Redis, Keycloak, and app-specific keys.

Best practices:

  • Use separate values files per environment.
  • Pin images to specific digests in production.
  • Set meaningful resource requests/limits based on load tests.
  • Enable readiness probes to avoid routing traffic before warm-up.

Section sources

Database Connections (PostgreSQL)

  • Connection parameters: host, port, database name, user, password, SSL mode.
  • Operator-managed cluster: size, storage class, backup policy, high availability.
  • Initialization: schema migrations and seed data handled by jobs or init containers.

Production considerations:

  • Use managed storage classes with snapshots.
  • Configure backups and retention policies.
  • Ensure network policies allow only app pods to connect.

Section sources

Redis Configuration

  • Connection parameters: host, port, password, TLS enablement.
  • Failover mode: sentinel-based HA with master and replicas.
  • Persistence: disk persistence and eviction policies.
  • Session store alignment: ensure TTLs match application session behavior.

Production considerations:

  • Enable TLS for Redis in production.
  • Size memory appropriately and monitor hit ratios.
  • Use dedicated namespaces and network policies.

Section sources

Keycloak Integration

  • OIDC provider: issuer URL, client ID, client secret, scopes, and claims mapping.
  • Realm configuration: realm import, default users, roles, and groups.
  • Admin endpoints: internal admin API access for automation.
  • Routes: HTTPRoute for Keycloak UI and admin redirect.

Security notes:

  • Store client secrets in Kubernetes Secrets.
  • Restrict admin endpoints to internal networks.
  • Rotate secrets regularly and audit Keycloak logs.

Section sources

Networking and Routing

  • Gateway: ingress controller configuration and TLS termination.
  • HTTPRoutes: expose MCP and Keycloak endpoints with hostnames and path rules.
  • Reference grants: allow cross-namespace access where required.

Operational tips:

  • Use consistent hostnames across environments.
  • Enable TLS with managed certificates.
  • Validate routes after upgrades.

Section sources

Secret Management

  • Credentials generator job: creates application secrets from values or external vaults.
  • Secret references: mounted as environment variables or config maps.
  • Rotation strategy: update values and re-run job; roll out new pods.

Best practices:

  • Never commit plaintext secrets to version control.
  • Use sealed-secrets or external secret managers.
  • Audit secret creation and rotation events.

Section sources

Optional Components (Qdrant)

  • Qdrant stateful set and HPA for vector search.
  • Storage sizing and persistence tuning.
  • Network policies and monitoring.

When to enable:

  • For semantic search and embedding-backed retrieval.
  • Scale horizontally based on query volume.

Section sources

Dependency Analysis

The Helm chart orchestrates multiple dependencies. The following diagram shows how values drive template rendering and resource creation.

flowchart TD
V["values.yaml / values.prod.yaml"]
T["Templates"]
R1["Deployment"]
R2["PostgreSQL CR"]
R3["Redis Failover CR"]
R4["Keycloak CR"]
R5["Gateway + HTTPRoutes"]
R6["Secret Generator Job"]
R7["HPA (App/Qdrant)"]
V --> T
T --> R1
T --> R2
T --> R3
T --> R4
T --> R5
T --> R6
T --> R7
Loading

Diagram sources

Section sources

Performance Considerations

  • Right-size resources: set CPU/memory requests and limits based on profiling.
  • Tune HPA: configure min/max replicas and target utilization thresholds.
  • Database tuning: adjust connection pools and storage IOPS.
  • Redis tuning: set maxmemory and eviction policies; enable persistence if needed.
  • TLS overhead: terminate TLS at the gateway and use efficient ciphers.
  • Monitoring: enable ServiceMonitors and PrometheusRules for alerting.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Pod CrashLoopBackOff: check liveness/readiness probes and startup time; review logs and events.
  • Database connectivity errors: verify credentials, network policies, and SSL settings.
  • Redis timeouts: confirm host/port/password/TLS and memory limits.
  • Keycloak login failures: validate issuer URL, client ID/secret, and realm configuration.
  • Route not found: ensure GatewayClass exists and HTTPRoutes reference correct backends.
  • Secret missing: run the credentials generator job and verify secret names.

Diagnostic steps:

  • Inspect pod logs and describe events.
  • Test connectivity from within the cluster to DB/Redis/Keycloak.
  • Validate TLS certificates and DNS resolution.
  • Review Prometheus metrics and alerts.

Section sources

Conclusion

This guide consolidates Helm chart configuration for Kairos MCP, covering application settings, database and Redis connections, Keycloak integration, networking, secrets, and optional components. By following the environment-specific values and production best practices outlined here, you can reliably deploy and operate Kairos MCP across development and production clusters.

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

Appendices

Common Deployment Scenarios

  • Development:
    • Use values.dev.yaml with minimal resources and local storage classes.
    • Enable debug logging and disable strict TLS where appropriate.
  • Staging:
    • Mirror production values with smaller sizes.
    • Enable full observability and automated backups.
  • Production:
    • Use values.prod.yaml with pinned images, autoscaling, and hardened security.
    • Enforce TLS, RBAC, and network policies.

Configuration override examples:

  • Override image tag: helm upgrade --set image.tag=vX.Y.Z ...
  • Adjust replicas: helm upgrade --set replicaCount=3 ...
  • Provide external DB: helm upgrade --set postgresql.host=db.example.com ...
  • Configure Keycloak: helm upgrade --set keycloak.issuer=https://kc.example.com ...

Section sources

KAIROS MCP

Clone this wiki locally