@k8slens/kubernetes-contracts

What names and types a Kubernetes resource: every API version as a typed specifier, every kind Lens itself knows as a typed kind, and the types of the Kubernetes API, generated from @kubernetes/client-node.

import { podKind, coreV1, type V1PodSpec, type KubeResource } from "@k8slens/kubernetes-contracts";

type ServedPod = KubeResource<typeof podKind, typeof coreV1>; // metadata.name, metadata.uid and spec are required

• getKubernetesApiVersion and getKubeResourceKind declare an API version and a kind of your own, typed; coreV1, appsV1, autoscalingV2, ... and podKind, deploymentKind, ... are the built-in ones.
• The schema types are named as client-node names them, the API version first: V1Pod, V1PodSpec, V2HorizontalPodAutoscaler. A kind carries its apiVersion and kind as literals, timestamps are the strings the API serves (Time, MicroTime), ports that may be named are IntOrString, and what the schema leaves open is unknown. Property names are the wire names. The few names client-node had to disambiguate keep their group prefix: CoreV1Event is the core Event, EventsV1Event the one of events.k8s.io.
• PodV1, DeploymentV1, ... are the built-in kinds' resources as the API serves them, with the fields a served resource always carries made required.

Regenerating

src/generated/ is generated by generator/ from the installed @kubernetes/client-node and the list of built-in kinds in generator/built-in-kinds.ts, and committed. When Dependabot bumps client-node, CI fails until the types are regenerated:

npm run generate --workspace @k8slens/kubernetes-contracts

npm run generate:check --workspace @k8slens/kubernetes-contracts is what CI runs. Which Kubernetes release the types describe, and which client-node version they came from, is recorded in the kubernetes field of package.json and in the header of every generated module.

Versioning

Semver from conventional commits, like every @k8slens package: a regeneration that only adds fields is a feat, one that removes an API version is a breaking change. The Kubernetes release is not the package version.

Provenance

Derived from @kubernetes/client-node (Apache-2.0), itself generated from the Kubernetes OpenAPI specification (Apache-2.0). This package is MIT like its siblings; the notices travel in the generated modules' headers. The field documentation is kept on purpose: it is the Kubernetes API reference, which is what an extension author needs at the call site.