Adding Helm Charts to the Catalog

Overview

Helm charts are the most common packaging format for Kubernetes applications. Instead of defining containers, ports, and volumes manually, you point PodWarden at a chart repository and let the chart handle the details.

This guide is for template authors and Hub administrators who want to add Helm chart deployment options to the catalog.

Prerequisites

Admin access to PodWarden Hub (or a PodWarden instance with Hub connection)
The target cluster must have the Helm Operator installed as a System App

Creating a Helm Chart Template

Step 1: Choose the Stack Type

When creating a new template in the catalog, select Helm Chart as the stack type. This changes the template form — instead of image/ports/volumes fields, you get Helm-specific configuration.

Step 2: Configure Helm Settings

Set the helm_config fields:

Field	Required	Description	Example
Chart Repository URL	Yes	HTTPS URL of the Helm chart repository	`https://charts.bitnami.com/bitnami`
Chart Name	Yes	The chart name within the repository	`kube-prometheus`
Chart Version	Yes	Exact version to deploy	`9.6.1`
Default Values	No	YAML values that are always applied	See below

# Example helm_config
helm_config:
  repo_url: "https://charts.bitnami.com/bitnami"
  chart_name: "kube-prometheus"
  chart_version: "9.6.1"
  default_values:
    prometheus:
      retention: "15d"
    alertmanager:
      enabled: true

Only exact chart versions are supported. Semver ranges like ^9.0.0 or >=9.6.0 are not accepted — this ensures deployments are reproducible.

Step 3: Define Environment Schema

Use env_schema to expose configurable values to operators. For Helm charts, environment schema names use dotted path notation that maps directly to nested Helm values:

env_schema name	Maps to Helm value	Type
`server.replicas`	`server: { replicas: N }`	number
`server.resources.requests.cpu`	`server: { resources: { requests: { cpu: "..." } } }`	string
`alertmanager.enabled`	`alertmanager: { enabled: true/false }`	boolean
`server.image.tag`	`server: { image: { tag: "..." } }`	string

Each env_schema entry supports the same fields as single-service templates:

env_schema:
  - name: "server.replicas"
    description: "Number of Prometheus server replicas"
    required: false
    default_value: "1"
  - name: "alertmanager.enabled"
    description: "Enable Alertmanager for alert routing"
    required: false
    default_value: "true"
  - name: "server.retention"
    description: "How long to keep metrics data"
    required: false
    default_value: "15d"

When an operator deploys the template, PodWarden converts these dotted paths into nested YAML values and merges them with default_values.

Step 4: Set Default Values

Use default_values in helm_config for values that should always be set but don't need user input. These are applied as the base layer — operator-configured env_schema values override them.

Common uses for default values:

Disabling sub-charts you don't want (e.g., grafana: { enabled: false })
Setting resource defaults that match PodWarden conventions
Configuring storage class names or namespace-scoped settings
Pinning image registries to avoid rate limits

default_values:
  global:
    storageClass: "longhorn"
  grafana:
    enabled: false
  prometheus:
    prometheusSpec:
      storageSpec:
        volumeClaimTemplate:
          spec:
            resources:
              requests:
                storage: 50Gi

Step 5: Fill in Standard Template Fields

The remaining template fields work the same as other stack types:

Name, description, and tags — For catalog display and search
Category — Where the template appears in the catalog
Resource requirements — CPU, memory, and GPU estimates (informational — Helm charts manage their own resource requests)
Screenshots — UI previews for the catalog listing

Testing Your Template

Create a test deployment with dry-run enabled. The dry-run renders all chart templates and shows you the Kubernetes resources that would be created.
Check for cluster-scoped resources — The dry-run output highlights ClusterRoles, ClusterRoleBindings, CRDs, and other resources that affect the entire cluster. Make sure these are expected.
Deploy to a staging cluster first and verify the application starts correctly.
Test env_schema values — Change configurable values and redeploy to confirm they take effect.

Example: Prometheus Stack Template

name: "Kube Prometheus Stack"
description: "Complete cluster monitoring with Prometheus, Alertmanager, and Grafana"
stack_type: "helm"
category: "Monitoring"
tags: ["monitoring", "prometheus", "grafana", "alertmanager"]

helm_config:
  repo_url: "https://prometheus-community.github.io/helm-charts"
  chart_name: "kube-prometheus-stack"
  chart_version: "65.1.0"
  default_values:
    grafana:
      adminPassword: "changeme"
      persistence:
        enabled: true
        size: 10Gi
    prometheus:
      prometheusSpec:
        retention: 15d
        storageSpec:
          volumeClaimTemplate:
            spec:
              resources:
                requests:
                  storage: 50Gi

env_schema:
  - name: "grafana.adminPassword"
    description: "Grafana admin password"
    required: true
    generate: "password"
  - name: "prometheus.prometheusSpec.retention"
    description: "Metrics retention period"
    required: false
    default_value: "15d"
  - name: "alertmanager.enabled"
    description: "Enable Alertmanager"
    required: false
    default_value: "true"

Limitations

Array indices in dotted paths (e.g., ingress.hosts[0].host) are not supported. Use default_values for array-typed configuration.
Keys containing dots cannot be used as env_schema names because dots are used as path separators.
Only exact chart versions are supported — no semver ranges.
OCI-based chart repositories (oci://) are not yet supported. Use HTTPS chart repositories.
Chart dependencies are resolved by the Helm Operator at install time. If sub-chart repositories are unreachable from the cluster, the install will fail.