Kubernetes resource plugin for formae. This plugin enables formae to manage Kubernetes resources via Server-Side Apply, with strongly-typed Pkl schemas pinned to your cluster's exact K8s minor (v1.21 → v1.36, 16 minors).

Two version ranges are in play, and they are not the same:

So schema trees exist for 1.21 → 1.30, but those minors are below the runtime floor: you can author and pkl eval against them, yet the plugin refuses to drive a live cluster older than 1.31. client-go is pinned in lockstep with the highest supported minor.

This plugin supports 38 Kubernetes resource types across 15 API groups, plus a generic catch-all for arbitrary custom resources.

MutatingAdmissionPolicy reached GA in K8s 1.36 (KEP-3962) and is only present in the v1.36+ schema trees; it cannot be referenced when kubernetesVersion is set to an earlier minor.

Custom resources. K8S::Custom::Resource manages any CRD instance (cert-manager Certificate, Argo Application, and so on) through a generic catch-all — no per-CRD Go code or generated schema. A CRD and instances of the kind it defines can live in one forma and deploy in a single formae apply. Both custom types are discoverable = false, so they are managed via explicit declaration only, not surfaced by discovery.

See schema/pkl/ for the complete list of supported resource types.

Configure a Kubernetes target in your Forma file:

import "@formae/formae.pkl"
import "@k8s/k8s.pkl" as k8s

target: formae.Target = new formae.Target {
  label = "k8s-target"
  namespace = "K8S"
  config = new k8s.Config {
    kubernetesVersion = "1.31"          // K8s minor — selects the schema subtree
    auth = new k8s.KubeconfigAuth {}    // see Credentials below
  }
}

Config fields:

Every namespaced resource MUST set metadata.namespace. Reference a K8S::Core::Namespace declared in the same Forma to keep it single-sourced:

import "@k8s/k8s.pkl" as k8s
import "@k8s/v1.31/core/Namespace.pkl" as ns
import "@k8s/v1.31/core/ConfigMap.pkl" as cm

local appNs = new ns.Namespace {
  label = "my-app-ns"
  metadata = new ns.NamespaceMetadata { name = "my-app" }
}

local appConfig = new cm.ConfigMap {
  label = "my-app-config"
  metadata = new k8s.NamespacedObjectMeta {
    name = "my-app-config"
    namespace = appNs.res.name   // resolvable ref into the Namespace above
  }
  data { "log.level" = "info" }
}

The plugin supports six authentication strategies. Configure via the auth field on k8s.Config:

Kubeconfig (local development, any pre-configured cluster):

auth = new k8s.KubeconfigAuth {
  context = "kind-formae-test"        // optional — defaults to current-context
  kubeconfig = "/path/to/kubeconfig"  // optional — defaults to $KUBECONFIG / ~/.kube/config
}

Managed clusters (EKSAuth, GKEAuth, AKSAuth, OVHAuth, OCIAuth) — each takes the cluster endpoint, CA, and provider-specific identifiers, with auth tokens minted from your existing cloud session. See schema/pkl-main/target.pkl for the field shapes.

In-cluster (when formae itself runs as a Pod):

auth = new k8s.InClusterAuth {}

The Pod's ServiceAccount token at /var/run/secrets/kubernetes.io/serviceaccount/ is used automatically.

The K8s package ships Helm-chart wrappers under schema/pkl/helm/ that render Helm charts at Pkl-eval time and map the output to typed K8s resources. Import via @k8s/helm/v<X.Y>/HelmChart.pkl; the wrapper version must match the kubernetesVersion on the Target. Requires pkl-reader-helm on PATH.

See schema/pkl-helm/README.md for the wrapper layout and codegen details.

The examples/ directory has runnable forma files covering two patterns.

Each workload is a directory of per-cloud entry files — examples/<workload>/<cloud>.pkl, where <cloud> is one of aws, azure, gcp, oci, or local (a kubeconfig-accessible cluster). Pick a cloud by choosing the matching file.

# Resolve Pkl deps once per fresh clone
pkl project resolve examples/

# Pick a cloud by choosing the matching file
formae apply --mode reconcile --watch examples/bookstore/local.pkl
formae apply --mode reconcile --watch examples/bookstore/aws.pkl
formae apply --mode reconcile --watch examples/lgtm-observability/azure.pkl
formae apply --mode reconcile --watch examples/crossplane/gcp.pkl

Each workload example has a per-directory README with prerequisites, smoke test commands, and per-provider tear-down steps.

The examples/helm/ directory uses the @k8s/helm wrappers to render Helm charts into typed K8s resources.

pkl eval examples/helm/nginx-v1.31.pkl --project-dir examples/helm/
formae apply examples/helm/nginx-v1.31.pkl --mode reconcile --yes --watch
formae destroy examples/helm/nginx-v1.31.pkl --yes --watch

Pick a cloud by choosing examples/<workload>/<cloud>.pkl:

The cluster-provisioning code lives under examples/clusters/; each provider's <cloud>.pkl is a Pkl module exposing resources(slug) and target(slug) functions that the workload examples consume. To add a new provider, create examples/clusters/<provider>.pkl exposing resources(slug) and target(slug), then add a <provider>.pkl entry file in each workload directory.

This plugin is licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2).

Copyright 2026 Platform Engineering Labs Inc.