RagLeap Packages
Looking for the self-hosted AI employee system? This page documents the open-source pip install ragleap-app-chart package. To install and run ragleap-core (AI employees, channels, Docker), see docs.ragleap.com; the project home is ragleap.com.
Not RagLeap-specific — proven against a non-RagLeap toy app, per the design proposal's own requirement

ragleap-app-chart

A generic, reusable Helm chart for deploying arbitrary services to Kubernetes — built by RagLeap, but doesn't know or care what RagLeap is. Point it at your own app via an arbitrary services: list.

0.3.2
PyPI version
3
Real bugs found & fixed live
2/2
both live examples Running, 0 restarts

Install

The Python package itself ships no functional code — it exists so this content can be versioned and released through the same PyPI pipeline as the other RagLeap packages. The real deliverable is the helm/ chart.

Chart in the wheel: from 0.3.1, pip install ragleap-app-chart includes helm/. Earlier wheels contained only the Python module, so use a repository checkout for those.

pip install ragleap-app-chart
# or, with uv
uv add ragleap-app-chart

What's inside

Each entry under a services: list in values.yaml renders its own Deployment, Service, and — conditionally — PVC, NetworkPolicy, and Ingress, via Helm range loops. Nothing is hardcoded to a specific app.

deployment.yaml
Per-service Deployment. Optional initChown flag renders a one-time root fix-permissions init container using the service's own declared securityContext.runAsUser.
service.yaml
Per-service Service, always rendered.
pvc.yaml
Rendered only if persistent: true. Mount path is currently fixed at /data — see Known limitations.
networkpolicy.yaml
Deny-by-default per service. Ingress rules are derived automatically from other services' dependsOn entries.
ingress.yaml
Rendered only if expose: true, with cert-manager TLS via a configurable ClusterIssuer.

Secure by default

Per-service resources and securityContext overrides, falling back to chart-level defaultResources/defaultSecurityContext when a service omits its own.

defaultSecurityContext:
  runAsNonRoot: true
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: false   # many images need write access; override per-service to true where possible

Live verification — 3 real bugs found and fixed

First helm install against a real kind cluster, using the chart's own default example (web + postgres) — the genericity proof the design proposal explicitly requires: "proven against a non-RagLeap toy app." Neither bug was caught by helm lint/helm template alone.

  • runAsNonRoot without runAsUser rejected postgres:16 outright. The default image runs as root before its entrypoint drops privileges internally — same bug class found in ragleap-ops the same day. Fixed generically: the opt-in initChown flag uses each service's own declared UID, not a hardcoded one.
  • Hardcoded /data mount path vs. postgres's real data directory. The official postgres image defaults to /var/lib/postgresql/data, not /data — without an explicit PGDATA override, data would have silently NOT persisted to the actual PVC.
  • No way to override a container's command/args at all, for any service. Found while building a second, deliberately different worked example (Redis + a small HTTP service, see EXAMPLE.md): an env-var-based config for a CLI-flag-configured image (hashicorp/http-echo) deployed successfully with no errors, but returned the wrong response — the chart simply had no command/args field to override it correctly. Fixed by adding command/args support to the chart, mirroring the pattern already used in ragleap-ops's voice service.

After all three fixes: both live examples (web + postgres, and redis + api) reached fully Running state, 0 restarts sustained. Data persistence independently confirmed via SHOW data_directory; → /data/pgdata for postgres, and real Redis SET/GET roundtrip + CONFIG GET dir → /data for the second example — not just pod status either time.

Autoscaling and disruption budgets (0.3.0)

Optional per-service autoscaling (HorizontalPodAutoscaler) and pdb (PodDisruptionBudget). Both are off by default. Tested live on a kind cluster with metrics-server.

  • Scale-up verified. Under CPU load the HPA took a service from 1 to 4 replicas (the configured maximum) and all new pods reached Running.
  • PDB verified. Allowed disruptions went from 0 with 1 replica to 3 with 4 replicas (minAvailable: 1).
  • Not tested: scale-down back to the minimum (the test was cleaned up before the 5-minute stabilization window ended) and PDB behaviour during a real node drain. A PDB with minAvailable: 1 on a single replica blocks voluntary drains. CPU-percentage autoscaling needs a CPU request on the service and metrics-server in the cluster.

Known limitations

Drawn from the real live-cluster test — including a real risk the chart doesn't yet guard against automatically.

  • The hardcoded /data mount path is a real generic risk, not just a postgres-specific quirk. Any persistent service whose image doesn't default its data directory to /data needs an explicit env override — the chart does not currently warn or validate this.
  • initChown requires the service to also declare its own securityContext.runAsUser. If a service sets initChown: true without runAsUser, the rendered chown command would be malformed. Not currently validated — would fail at apply-time, not before.
  • Not part of RagLeap Core's numbered ecosystem sequence. This is a deliberately separate track from packages like ragleap-ops — see GENERIC-K8S-CHART-PROPOSAL.md in the repo root for the design rationale.