Version a plugin's schema

This guide walks through how formae-plugin-kubernetes conforms to the API schema versioning contract, step by step. The same recipe applies to any plugin whose target API evolves per version: fields get introduced, graduate from alpha to GA, get renamed, or are removed between releases. For the mechanics of how formae core resolves versions and narrows imports, read the concept page API schema versioning first. This page is the task-oriented walkthrough.

Publish the per-version schema layout

This is the schema/pkl/ tree that ends up under ~/.pel/formae/plugins/k8s/ after formae plugin install. It’s also the package layout consumers see when they pull the package from hub.platform.engineering.

schema/pkl/
├── PklProject                         # package root; declares "@k8s" + deps
├── shared.pkl                         # version-agnostic typealiases + K8sVersion class
├── target.pkl                         # Config + Auth (Config carries kubernetesVersion)
├── helm/                              # helm-chart wrappers (per-version + shared)
│   └── v1.34/...
├── v1.21/
│   ├── PklProject
│   ├── k8s.pkl                        # SubResource classes valid in 1.21
│   ├── apps/Deployment.pkl
│   ├── core/Pod.pkl
│   └── ...
├── v1.22/
├── v1.23/
├── …
└── v1.36/                             # latest supported minor
    ├── PklProject
    ├── k8s.pkl
    ├── apps/Deployment.pkl
    ├── core/Pod.pkl
    └── …                              # all api-group subdirs

Important properties of this layout:

No top-level k8s.pkl. The package root is target.pkl (Config + Auth only). Per-version subdirs each hold their own k8s.pkl containing the SubResource classes valid for that minor. Avoids the basename collision that would otherwise force <baseName>_<sanitizedVersion> aliases.
shared.pkl at the root. Version-agnostic typealiases (KubernetesMinorVersion, etc.) and the K8sVersion annotation class live here. Per-version files reference them through the package root, so the version dropped doesn’t strand orphan imports.
Per-version PklProject. Each v<X.Y>/ ships its own PklProject so the per-version subtree can stand alone if needed (Pkl resolves @k8s/v1.34/... paths through that nested project).
helm/ is parallel. Helm-chart wrappers also ship per-version, in their own subtree, because they import per-version subresource files (@k8s/v1.34/k8s.pkl) and therefore need to be regenerated when versions change.

The kubernetes plugin includes 16 minor versions today (v1.21 to v1.36). Each new minor adds one subdir; an unsupported minor would be dropped from this list. CI runs a conformance matrix that exercises every minor against a real kind cluster.

Add the apiVersion field to Config

schema/pkl/target.pkl

typealias KubernetesMinorVersion = String(matches(Regex(#"^\d+\.\d+$"#)))

open class Config {
    kubernetesVersion: KubernetesMinorVersion?       // <-- The contract field
    auth: Auth
    // ...
}

Core picks up kubernetesVersion (matched by the case-insensitive ApiVersion / apiVersion lookup) and feeds it into resolveSchemaVersions. Users write:

new k8s.Config {
    kubernetesVersion = "1.34"
    auth = new k8s.KubeconfigAuth {}
}

Define the version annotation class

schema/pkl/shared.pkl

/// API version a field/class is gated to.
///
/// `introducedIn` is the first K8s minor in which the field is valid.
/// `removedIn`    is the minor in which the API was removed.
/// `deprecatedIn` is the minor in which the field was deprecated.
class K8sVersion {
    introducedIn: KubernetesMinorVersion?
    deprecatedIn: KubernetesMinorVersion?
    removedIn: KubernetesMinorVersion?
    reference: String?            // KEP URL, RFC, vendor doc
}

Inside each per-version v<X.Y>/ subtree, fields that were added in a later minor are simply absent from the file. The annotation is what drives that selection at publish time, so when a consumer imports @k8s/v1.30/core/Service.pkl, they only see fields that were available in K8s 1.30. trafficDistribution (Beta in 1.30) is present, while tolerance (Beta in 1.35) is not. Three granularities of gating, all visible in the per-version trees as additions or omissions:

Property-level, field landed in 1.30, beta then GA

@k8s.FieldHint {}
@k8s.K8sVersion { introducedIn = "1.30"; reference = "https://kep.k8s.io/4444" }
trafficDistribution: String?

Module-level, whole resource available from 1.29

@K8sVersion { introducedIn = "1.29"; reference = "https://github.com/kubernetes/enhancements/issues/3000" }
module flowschema extends "../k8s.pkl"

Class-level, nested class gated independently

@SubResourceHint {}
@K8sVersion { introducedIn = "1.32"; reference = "https://kep.k8s.io/2837" }
open class ContainerResizePolicy extends formae.SubResource {
    // ...
}

Resolve the runtime version (Go side)

Beyond the Config field, the plugin also resolves the runtime version (for client construction + preflight). Priority order:

pkg/config/version.go

const (
    MinSupportedK8sVersion = "1.31"
    MaxSupportedK8sVersion = "1.36"
    ClientGoVersion        = "0.36.0"   // keep in sync with go.mod
)

// ResolveK8sVersion: cfg.KubernetesVersion -> FORMAE_K8S_VERSION env ->
//                    live discovery via the cluster's /version endpoint.
func ResolveK8sVersion(ctx context.Context, cfg *Config, disc discovery.DiscoveryInterface) (string, error)

A preflight CheckField helper walks the per-version gate metadata and refuses to apply when the user pins a gated field on a cluster that doesn’t accept it. Catches the “I added trafficDistribution to my Service.pkl but my cluster is 1.29” mistake before any RPC is sent.

Author against versioned schemas

Users in their forma.pkl import paths matching the version they’re targeting:

examples/nginx-v1.34.pkl

amends "@formae/forma.pkl"

import "@formae/formae.pkl"
import "@k8s/target.pkl" as k8s
import "@k8s/v1.34/core/Namespace.pkl" as ns
import "@k8s/v1.34/apps/Deployment.pkl" as dep

forma {
  new formae.Target {
    label = "k8s-local"
    config = new k8s.Config {
      kubernetesVersion = "1.34"
      auth = new k8s.KubeconfigAuth {}
    }
  }
  // ...
}

The @k8s/v1.34/... paths are the per-version subtrees in the published package. The package root @k8s/target.pkl carries only Config + Auth (version-agnostic). When the Forma is extracted later, core’s ImportsGenerator narrowing makes sure only v1.34-relevant resources show up in the regenerated file. For the full contract, the version-resolution priority order, and the extract-time narrowing that ties this together, see API schema versioning.

Get started

Guides

Concepts

Reference

Version a plugin's schema

Publish the per-version schema layout

Add the apiVersion field to Config

Define the version annotation class

Resolve the runtime version (Go side)

Author against versioned schemas

​Publish the per-version schema layout

​Add the apiVersion field to Config

​Define the version annotation class

​Resolve the runtime version (Go side)

​Author against versioned schemas

Publish the per-version schema layout

Add the apiVersion field to Config

Define the version annotation class

Resolve the runtime version (Go side)

Author against versioned schemas