Helm integration

Use Helm charts in your formae deployments. Reference a chart by name and version, set values inline, and apply it alongside the rest of your Kubernetes resources, with no separate helm install step.

Prerequisites

• pkl 0.30+
• pkl-reader-helm on PATH. Install from the apple/pkl-readers releases page (look for helm@<ver> tags).
• helm 3+ with the chart repos you reference:

  helm repo add bitnami https://charts.bitnami.com/bitnami
  helm repo update

• A matching @formae-helm/v<X.Y> import that lines up with your Target's kubernetesVersion and the @k8s/v<X.Y> imports elsewhere in the forma. See Version coupling.

Usage

amends "@formae/forma.pkl"

import "@formae/formae.pkl"
import "@k8s/k8s.pkl" as k8s
import "@k8s/v1.31/core/Namespace.pkl" as ns
import "@formae-helm/v1.31/HelmChart.pkl"

local chart = new HelmChart {
  chart       = "bitnami/nginx"
  version     = "22.4.7"
  releaseName = "my-nginx"
  namespace   = "demo"
  values = new Dynamic {
    replicaCount = 2
    service { type = "ClusterIP" }
  }
}

forma {
  new formae.Stack { label = "helm-nginx" }
  new formae.Target {
    label = "k8s-local"
    namespace = "K8S"
    config = new k8s.Config {
      kubernetesVersion = "1.31"
      auth = new k8s.KubeconfigAuth {}
    }
  }
  new ns.Namespace {
    label = "demo-namespace"
    metadata = new ns.NamespaceMetadata { name = "demo" }
  }
  ...chart.resources
}

Apply and destroy:

formae apply <forma>.pkl --mode reconcile --yes --watch
formae destroy <forma>.pkl --yes --watch

HelmChart fields

Field	Type	Default	Purpose
chart	String	(required)	Helm chart reference (<repo>/<chart> or OCI URL).
version	String	(required)	Chart version.
releaseName	String	(required)	Helm release name. Used as label prefix.
namespace	String	"default"	Target namespace for namespaced resources.
values	Dynamic?	null	Helm values overrides. Use new Dynamic { ... }.
labelPrefix	String	releaseName	Prefix used on formae resource labels.
skipUnsupported	Boolean	true	Skip resource Kinds the K8s minor doesn't ship. false throws instead.

Version coupling

Three things must agree:

• @formae-helm/v<X.Y> import
• @k8s/v<X.Y> imports
• Config.kubernetesVersion = "<X.Y>"

A mismatch fails at pkl eval, before any cluster call. The supported version set tracks the K8s plugin. To deploy the same chart against multiple K8s minors, write one forma per minor, or parameterise the file via Pkl properties.

Charts with newer Kinds

If a chart emits a Kind your K8s minor doesn't have (for example, FlowSchema against a 1.28 cluster), the integration drops it from the output by default. Set skipUnsupported = false to fail at eval time instead.

Not to be confused with

operations/install-helm.md covers installing formae itself via a Helm chart. This page covers using formae to manage other Helm charts. Different direction, same word.

Source

formae-plugin-k8s/helm/. Ships as the formae-helm Pkl package on the hub.