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).

formae · Hub · Configuration · Supported resources

Requires the formae CLI: see the quick start.

formae plugin install k8s

Also included in the default plugin set: formae plugin install standard.

Restart the formae agent afterwards so it loads the plugin.

New project: with the agent running, formae project init --include k8s my-project creates my-project with a PklProject that declares the formae and k8s schema packages, so import "@k8s/..." resolves, and a starter main.pkl. Don't run it in an existing project: it overwrites both files.

Existing project: add the plugin to dependencies in your PklProject, with the current version from the hub page, then run pkl project resolve:

["k8s"] {
  uri = "package://hub.platform.engineering/plugins/k8s/schema/pkl/k8s/k8s@<version>"
}

Next: write your first forma, then formae apply (see apply modes).

With an AI coding assistant, use the formae plugin (formerly formae-mcp), which can search the hub and fetch plugin examples. The formae documentation is also available as llms.txt.

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 39 Kubernetes resource types across 16 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.

A chart is installed as a single K8S::Helm::Release, driven by the Helm SDK embedded in the plugin. formae manages the release; Helm manages the objects the chart renders, so hooks, hook weights, CRD install ordering and revision history all work — and helm list, helm history and helm rollback see the release.

import "@k8s/helm/Release.pkl" as helm

No version segment, unlike every other schema import: no field on a release has a shape that depends on the apiserver minor, so this module ships once at the package root instead of in each v<X.Y>/ tree. No pkl-reader-helm on PATH and no helm repo add either: the plugin embeds the SDK and nothing is rendered at Pkl-eval time.

See examples/helm/ for runnable formae and the drift and adoption scenarios.

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 examples/bookstore/local.pkl
formae apply --mode reconcile examples/bookstore/aws.pkl
formae apply --mode reconcile examples/lgtm-observability/azure.pkl
formae apply --mode reconcile 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 installs charts as K8S::Helm::Release resources via @k8s/helm/Release.pkl.

pkl project resolve examples/
pkl eval examples/helm/release-nginx.pkl --project-dir examples/
formae apply examples/helm/release-nginx.pkl --mode reconcile --yes
formae destroy examples/helm/release-nginx.pkl --yes

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.