k8s-openapi

k8s-openapi provides Rust struct and enum definitions for every resource type in the Kubernetes client API, generated directly from the Kubernetes OpenAPI specification rather than a generic Swagger/OpenAPI code generator. Because the crate owns its own codegen pipeline, it can work around known mistakes in the upstream spec — including incorrect typing of CRD validation JSON and WatchEvent payloads — and backport those fixes to older supported Kubernetes versions that upstream itself never patches.

Exactly one Kubernetes version feature (v1_33 through v1_37) must be enabled at a time, enforced at compile time via a build script that panics on zero or multiple selections — this guarantees every crate in a dependency graph agrees on a single set of resource types. The crate ships a Resource/Metadata trait layer for generic programming over any resource, a DeepMerge implementation of RFC 7396 JSON merge-patch semantics for Kubernetes server-side apply, and is no_std-compatible for constrained environments. It underlies most of the Rust Kubernetes ecosystem, including the kube crate.

What You Get

• Generated Rust types for every Kubernetes resource across API groups (core, apps, batch, networking, rbac, storage, and more) for Kubernetes 1.33 through 1.37.
• A Resource/ListableResource/Metadata trait layer that lets you write generic code over any Kubernetes resource type.
• A DeepMerge trait implementing RFC 7396 JSON merge-patch semantics, matching how Kubernetes’ server-side apply actually merges objects.
• Compile-time enforcement of a single selected Kubernetes version via Cargo feature flags and a build script, preventing mismatched resource types across your dependency graph.
• no_std support (via an alloc-based std opt-in feature) for use in constrained or embedded environments.
• A companion k8s-openapi-derive crate for generating types for your own Custom Resource Definitions (CRDs).

Common Use Cases

• Building a Kubernetes controller or operator in Rust that needs typed, serde-compatible structs for Pods, Deployments, CustomResourceDefinitions, and other resources.
• Pairing with the kube crate’s client and watch APIs, which use k8s-openapi’s generated types as their request/response bodies.
• Constructing and applying JSON merge patches against the Kubernetes API server using DeepMerge instead of hand-rolling patch payloads.
• Writing CLI tools or automation that reads and writes Kubernetes manifests with compile-time-checked field names and types instead of untyped JSON.

Under The Hood

Architecture The crate is mostly generated code sitting on a small, hand-written core. Three files — resource.rs, deep_merge.rs, and byte_string.rs — define the shared abstractions, while thousands of generated modules under src/v1_33 through src/v1_37 mirror the Kubernetes API group/version hierarchy (api/core, apimachinery, apiextensions_apiserver, kube_aggregator, and more), each version gated behind a mutually-exclusive Cargo feature resolved in build.rs, which panics if zero or multiple version features are enabled and emits both a cfg for conditional compilation and links-based metadata (DEP_K8S_OPENAPI_*_VERSION) for downstream build scripts. A separate workspace member, k8s-openapi-codegen, is the binary that actually produces the generated modules from the upstream OpenAPI spec, with shared logic and templates factored into k8s-openapi-codegen-common. The core traits (Resource, ListableResource, Metadata, and marker types for cluster/namespace/subresource scope) give every generated struct a uniform interface, so changing that trait layer would ripple through every generated file and every downstream consumer, such as the kube crate, that programs against it.

Tech Stack Rust, edition 2021, no_std-compatible by default with an opt-in std feature that aliases core::alloc as std for allocation. Runtime dependencies are minimal and deliberately narrow: serde and serde_json (alloc feature) for (de)serialization, jiff (alloc and serde features) for timestamp handling, base64 for the ByteString type, and optional schemars or schemars08 (an aliased schemars 0.8) for JSON Schema generation behind feature flags. There is no bundled HTTP client — this is intentionally a types-only crate meant to pair with a client crate like kube. Build tooling centers on a custom build.rs for version-feature resolution, with codegen driven by the separate k8s-openapi-codegen binary via cargo run. CI (.github/workflows/ci.yaml) runs a global check plus a per-Kubernetes-version matrix job driven by test.sh list-versions, compiling and testing the crate against every supported version on every push.

Code Quality Dedicated unit tests live in the separate k8s-openapi-tests workspace member, covering deep merge behavior, patch construction, deserialization leniency, watch events, custom resource definitions, and clientset usage — a modest count given the surface area, but reasonable since the real correctness signal comes from compiling and exercising the crate across every supported Kubernetes version in CI rather than from unit tests alone. lib.rs opts into deny(clippy::all, clippy::pedantic) with an explicit, justified allow-list and a dedicated clippy.toml, indicating an actively enforced, strict lint posture. Error handling is straightforward serde Result propagation, naming faithfully mirrors Kubernetes’ own conventions mapped into Rust idioms, and no unsafe code appears in the hand-written core.

API Design The standout design choice is compile-time enforcement of exactly one Kubernetes version via a Cargo feature plus a build-script panic, closing off the class of bugs where multiple versions of a resource type end up coexisting in a dependency graph; conditional-compilation macros let library authors target a range of versions without picking a feature themselves, and the selected version is communicated to downstream build scripts via Cargo links metadata. The custom codegen pipeline exists specifically to patch documented bugs in Kubernetes’ own upstream OpenAPI spec and backport those fixes to older supported versions, something generic OpenAPI-generated clients typically don’t attempt. DeepMerge implements the actual JSON Merge Patch semantics Kubernetes’ server-side apply expects, sparing consumers from hand-rolling patch payloads. Getting started requires picking exactly one version feature up front, an unusual but thoroughly documented tradeoff.