How to Deploy Kaneo on Kubernetes Using Helm Charts: Complete Production Guide

Deploy Kaneo on Kubernetes using its official Helm chart by installing the kaneo release with embedded PostgreSQL, or customize values.yaml for external databases, ingress, and autoscaling.

Kaneo provides a production-ready Helm chart in the usekaneo/kaneo repository that automates the entire platform deployment. The chart bundles the API and web interface into a single container, optionally provisions PostgreSQL, and supports NGINX Ingress or Kubernetes Gateway API for external access.

Understanding the Kaneo Helm Chart Structure

The chart follows standard Helm conventions with clear separation of concerns. Located at charts/kaneo/ in the repository, it organizes all Kubernetes resources into reusable templates.

Core Components

Component	Template File	Purpose
Chart metadata	Chart.yaml	Defines chart version 2.13.0 and dependencies
Default configuration	values.yaml	Supplies replicas, image tags, environment variables, and feature flags
Application deployment	templates/deployment.yaml	Runs the combined Kaneo container with required environment variables
Database	templates/postgresql-deployment.yaml	Optional embedded PostgreSQL instance
Networking	templates/services.yaml	Exposes Kaneo on port 5173 via ClusterIP
External access	templates/ingress.yaml / templates/httproute.yaml	Optional NGINX Ingress or Gateway API HTTPRoute
Persistence	templates/pvc.yaml	Persistent storage for PostgreSQL data
Scaling	templates/hpa.yaml	Horizontal Pod Autoscaler based on CPU metrics
Security	templates/serviceaccount.yaml	Dedicated ServiceAccount for the Deployment

All templates reference values from values.yaml, enabling complete configuration without editing template files directly.

Prerequisites

Before deploying, ensure your cluster meets these requirements:

• Kubernetes version: 1.23.0 or later (specified in Chart.yaml as kubeVersion: ">=1.23.0-0")
• Helm 3.x installed locally
• kubectl configured for your target cluster
• Ingress controller (optional) for external access—NGINX or any Kubernetes Gateway API implementation

Installing Kaneo with Helm

Add the Kaneo Helm Repository

helm repo add kaneo https://usekaneo.github.io/kaneo
helm repo update

Skip this step if installing from a local chart copy.

Basic Installation with Embedded PostgreSQL

The fastest path to a running instance uses all defaults:

helm install kaneo-instance kaneo/kaneo \
  --namespace kaneo --create-namespace

This creates:

• A single-replica Kaneo Deployment with the combined API+web container
• An embedded PostgreSQL Deployment with persistent storage
• A ClusterIP Service exposing port 5173

Customizing Deployment with values.yaml

For production deployments, override defaults through a custom values file. The values.yaml in charts/kaneo/values.yaml exposes all tunable parameters.

Essential Production Configuration

Create production-values.yaml:

replicaCount: 2

kaneo:
  env:
    clientUrl: "https://kaneo.example.com"
    corsOrigins: "https://kaneo.example.com,https://app.example.com"
    authSecret: "your-minimum-32-character-secret-key-here"
    disableRegistration: false
  image:
    repository: usekaneo/kaneo
    tag: "2.13.0"
    pullPolicy: IfNotPresent
  resources:
    limits:
      memory: "512Mi"
      cpu: "500m"
    requests:
      memory: "256Mi"
      cpu: "250m"

postgresql:
  enabled: true
  persistence:
    enabled: true
    size: "20Gi"
    storageClass: "standard"

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: kaneo.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: kaneo-tls
      hosts:
        - kaneo.example.com

Deploy with your custom values:

helm install kaneo-instance kaneo/kaneo \
  --namespace kaneo --create-namespace \
  -f production-values.yaml

Critical Environment Variables

The templates/deployment.yaml injects these required variables:

Variable	Source in values.yaml	Purpose
KANEO_CLIENT_URL	kaneo.env.clientUrl	Public URL for email links and redirects
CORS_ORIGINS	kaneo.env.corsOrigins	Allowed origins for cross-origin requests
AUTH_SECRET	kaneo.env.authSecret	JWT signing key (minimum 32 characters)
DATABASE_URL	Auto-generated or external	PostgreSQL connection string

Connecting to External PostgreSQL

For production databases managed outside the cluster, disable the embedded PostgreSQL and provide connection details:

postgresql:
  enabled: false

kaneo:
  env:
    database:
      external:
        enabled: true
        host: "postgres.internal.example.com"
        port: 5432
        database: "kaneo_production"
        username: "kaneo_app"
        password: "secure-password-from-secret"

The templates/deployment.yaml constructs DATABASE_URL from these values when postgresql.enabled is false.

Enabling Horizontal Pod Autoscaling

Scale Kaneo based on CPU utilization by enabling the HPA in templates/hpa.yaml:

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

The HPA automatically adjusts replica count between 2 and 10 pods based on real-time metrics.

Exposing Kaneo with Ingress or Gateway API

The chart supports two patterns for external traffic.

NGINX Ingress (Traditional)

Enable in values.yaml:

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: kaneo.example.com
      paths:
        - path: /
          pathType: Prefix
          service: kaneo
          port: 5173

The templates/ingress.yaml generates the appropriate Ingress resource.

Kubernetes Gateway API (Modern)

For Gateway API implementations (Envoy Gateway, NGINX Gateway Fabric, Istio):

gateway:
  enabled: true
  gatewayName: external-gateway
  hostname: kaneo.example.com
  listenerName: https

The templates/httproute.yaml creates an HTTPRoute resource.

Upgrading and Maintaining Your Deployment

Upgrade to New Chart Version

helm upgrade kaneo-instance kaneo/kaneo \
  --namespace kaneo \
  -f production-values.yaml

Rollback on Failure

helm rollback kaneo-instance 1 --namespace kaneo

Uninstall Completely

helm uninstall kaneo-instance --namespace kaneo
kubectl delete namespace kaneo

Key Source Files Reference

File	Purpose
[charts/kaneo/Chart.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/Chart.yaml)	Chart metadata and versioning
[charts/kaneo/values.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/values.yaml)	Complete default configuration
[charts/kaneo/templates/deployment.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/deployment.yaml)	Main application Deployment
[charts/kaneo/templates/postgresql-deployment.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/postgresql-deployment.yaml)	Optional database Deployment
[charts/kaneo/templates/ingress.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/ingress.yaml)	NGINX Ingress resource
[charts/kaneo/templates/httproute.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/httproute.yaml)	Gateway API HTTPRoute
[charts/kaneo/templates/hpa.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/hpa.yaml)	Horizontal Pod Autoscaler
[charts/kaneo/templates/validations.yaml](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/validations.yaml)	Input validation helpers

Summary

• The Kaneo Helm chart packages the complete platform into a single installable unit with configurable PostgreSQL, networking, and scaling options.
• Default installation requires only helm install with embedded database for quick evaluation.
• Production deployments should customize values.yaml to set authSecret, clientUrl, external database connections, and ingress configuration.
• Autoscaling enables via autoscaling.enabled with CPU/memory thresholds in templates/hpa.yaml.
• Gateway API support provides a modern alternative to traditional Ingress through templates/httproute.yaml.

Frequently Asked Questions

Does the Kaneo Helm chart support high availability?

Yes. Set replicaCount above 1 and enable autoscaling for native HA. For database HA, disable embedded PostgreSQL (postgresql.enabled: false) and connect to an externally managed PostgreSQL cluster with replication.

What Kubernetes versions are compatible with the Kaneo Helm chart?

The chart requires Kubernetes 1.23.0 or later, as specified in Chart.yaml with kubeVersion: ">=1.23.0-0". This ensures support for stable Gateway API and security features used in the templates.

How do I use my own TLS certificates instead of cert-manager?

Omit the cert-manager.io/cluster-issuer annotation from ingress.annotations and manually create a TLS secret in the Kaneo namespace. Reference it in ingress.tls[0].secretName within your values.yaml.

Can I run Kaneo without the embedded PostgreSQL for local development?

Yes. Set postgresql.enabled: false and provide kaneo.env.database.external credentials, or use a local PostgreSQL instance accessible from your cluster. The templates/deployment.yaml constructs the connection URL from your external configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}