Deploy a Helm chart

​

Scope and limitations

• Helm hooks are not honored. Resources annotated with helm.sh/hook (pre-install, post-install, pre-upgrade, post-upgrade, pre-delete, post-delete) are rendered as ordinary resources and applied together with everything else. There is no hook ordering, no run-once-then-forget behavior, and no post-completion cleanup; helm.sh/hook-weight and helm.sh/hook-delete-policy are ignored. A chart that depends on a hook Job to initialize state (migrations, CRD installation, secret generation) may not behave as it does under helm install.
• Chart tests are not run. A helm.sh/hook: test pod is treated as a normal resource (created and left in place), not executed as a test. There is no helm test equivalent.
• No Helm release lifecycle. There is no release history, no helm rollback, no helm list, and no release-tracking Secret/ConfigMap. Rollback, waiting for readiness, and atomic apply are handled by formae’s own reconcile and drift correction; the Helm flags --wait, --timeout, and --atomic have no analog.
• No Helm ownership metadata. Resources are not stamped with app.kubernetes.io/managed-by: Helm or Helm release annotations; releaseName is used only as a formae label prefix.
• helm.sh/resource-policy: keep is ignored. formae’s reconcile owns deletion, so a resource the chart marks keep is still removed if a reconcile no longer declares it.
• CRDs shipped under a chart’s crds/ directory may not render. helm template does not emit crds/ by default, and there is no --include-crds toggle. CRDs a chart templates under templates/ do render (mapped to a custom resource); CRDs in crds/ should be applied separately.
• Rendering has no cluster access. Because the chart is templated at evaluation time (not against your cluster), lookup() returns empty and .Capabilities reflect Helm’s defaults rather than your live cluster’s API versions. Charts whose output branches on live cluster state render as if the cluster were empty. (Version alignment is instead enforced by the version coupling below.)
• The namespace is not created for you. There is no --create-namespace; declare the target namespace as its own resource in the forma (as in the forma below).

​

Prerequisites

• pkl 0.30 or newer.
• pkl-reader-helm on your PATH, from the apple/pkl-readers releases (look for helm@<ver> tags).
• helm 3 or newer, with the chart repositories you reference added:
  helm repo add bitnami https://charts.bitnami.com/bitnami
  helm repo update
  
• A @formae-helm/v<X.Y> import that lines up with your target’s kubernetesVersion and the @k8s/v<X.Y> imports in the same forma. See Version coupling.

​

The forma

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
}

formae apply --mode reconcile --yes helm-nginx.pkl
formae destroy --yes helm-nginx.pkl

​

HelmChart fields

​

Version coupling

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

​

Source