Search by

klass8s / k8schema

tequila

PHP class definitions of Kubernetes API resources

v1.37.3 2026-11-17 14:26 UTC

README

PHP classes for the Kubernetes API, generated from the upstream OpenAPI definitions (yannh/kubernetes-json-schema) by k8schema-generator: one class per API object and per nested type, with typed getters and setters, and jsonSerialize() writing the object the API server reads. It is the foundation of Klass8s, which defines manifests as PHP classes, and it can be used on its own.

Installation

k8schema requires PHP 8.5. Install the minor release line of the Kubernetes version your clusters run, with a tilde, so that composer update brings that minor's patches and never another Kubernetes API:

composer require klass8s/k8schema:~1.35.0

Example

use K8Schema\Api\Apps\V1\Deployment;
use K8Schema\Api\Core\V1\Container;

$deployment = new Deployment();
$deployment->metadata()->setName('web');
$deployment->spec()->setReplicas(2);
$deployment->spec()->selector()->matchLabels()->add('app', 'web');
$deployment->spec()->template()->metadata()->labels()->add('app', 'web');
$deployment->spec()->template()->spec()->containers()->add(new Container('web')->setImage('nginx:1.29'));

echo json_encode($deployment, JSON_PRETTY_PRINT);

json_encode() writes the Deployment as the Kubernetes API document, apiVersion and kind included; the fields left unset are written as null. Klass8s renders these objects to YAML and leaves the empty fields out.

Versions — one line per Kubernetes minor

vX.Y.Z X.Y is the Kubernetes API minor the classes describe; Z is this package's own release counter within that minor — bumped whenever a regeneration changes the tree (a newer upstream patch schema or a generator change). It is not the upstream patch number.
Pin the minor your clusters run: "klass8s/k8schema": "~1.35.0". Patches within the minor arrive with composer update.
Provenance every release names the upstream schema it was generated from and the generator commit.

Branch main is the template (bin/, the tool locks under tools/, the code-style config, src/K8SApi.php with its SetMe placeholder). Every minor lives on its own branch (v1.35) with the generated src/; tags v1.35.N are cut on that branch.

How a version is produced — the Generate workflow

Versions come from CI, not from a laptop. .github/workflows/generate.yaml:

  • On demand: Actions → Generate → Run workflow. minors = supported (the newest four upstream minors) or a list such as v1.36 v1.37; dry_run generates and reports the diff without pushing or tagging; force releases past the guards.
  • Weekly: the supported minors. A minor that appeared upstream since the last run gets its branch from the template and its .0 tag.

Each run, per minor: copy the template into the minor's branch, fetch the newest schema of that minor, wipe src/, generate, then check — every file compiles, the tree autoloads and serializes a Deployment, K8SApi::VERSION is the minor, code style is clean. No diff against the branch → nothing is pushed, nothing is tagged. A diff is committed, pushed and tagged as the next patch, with a GitHub release whose notes carry the provenance and the diffstat. The shrink guard holds a regeneration that deletes files or loses more than 3% of the lines: it lands as a PR against the minor branch and the run fails, for a human to look at (that shape is how a broken generator shows up — e.g. every status property gone).

The generator is pinned by tools/k8schema-generator/composer.lock. After a generator change:

composer update -d tools/k8schema-generator   # then commit the lock on main

and run the workflow — every supported minor regenerates; those whose tree changed get a tag.

Locally

composer install -d tools/k8schema-generator && composer install -d tools/php-cs-fixer
git checkout v1.35
bin/generate v1.35            # schema patch from the generator's default map
bin/generate v1.35 v1.35.8    # a specific upstream schema directory
git status                    # a clean tree = the branch is current for that schema

bin/push-to-branch and bin/release are the pre-CI laptop path (they git add . and count the next tag the same way the workflow does); prefer a dry_run of the workflow.

Origins

k8schema continues dealroadshow/k8s-resources, an MIT-licensed package, renamed here and regenerated by klass8s/k8schema-generator. Its notice is in NOTICE, which the Generate workflow copies into every minor branch with the rest of the template.

Contributing

Bug reports and pull requests are welcome: CONTRIBUTING.md says what a pull request needs. A wrong generated class is usually fixed in k8schema-generator, never by hand here. Report a security vulnerability privately, as SECURITY.md describes.

License

k8schema is released under the MIT License. The portions that come from the package it continues remain under their own MIT notice, in NOTICE.