ComparedKlass8s and Kustomize

Compared

Klass8s and Kustomize

Kustomize patches plain YAML and has no logic by design. Where that is the right tool, and where manifests outgrow it.

Kustomize's founding idea is sound: templating YAML as text is painful, so don't; keep plain YAML bases and patch them per environment. No template syntax, built into kubectl apply -k, declarative files. For laying a namespace and a few fields over manifests you do not own, it is the right tool.

The difference is everything past that point. Kustomize removes templating by removing logic, and maintaining manifests involves a lot of logic. Klass8s keeps the logic and writes it in a programming language. They answer problems of different sizes.

Where patching runs out

One decision, several files

The usual layout (a base/, then overlays/dev/, overlays/staging/, overlays/prod/, each with a kustomization.yaml and patches) means that "what does production run?" is answered by merging three or four files in your head. Klass8s keeps what differs between environments in the class it changes:

src/K8S/Shop/Manifest/ApiDeployment.phnsrc/K8S/Shop/Manifest/ApiDeployment.php
replicas(): int => 2;

replicasStaging(): int => 3;

replicasProd(): int => 6;

resources(ContainerResourcesInterface $resources): void
    => $resources->requestCPU(CPU::millicores(100))->requestMemory(Memory::mebibytes(128));

resourcesProd(ContainerResourcesInterface $resources): void {
    $resources
        ->requestCPU(CPU::millicores(500))
        ->requestMemory(Memory::mebibytes(512))
        ->limitMemory(Memory::gibibytes(1));
}
public function replicas(): int
{
    return 2;
}

public function replicasStaging(): int
{
    return 3;
}

public function replicasProd(): int
{
    return 6;
}

public function resources(ContainerResourcesInterface $resources): void
{
    $resources->requestCPU(CPU::millicores(100))->requestMemory(Memory::mebibytes(128));
}

public function resourcesProd(ContainerResourcesInterface $resources): void
{
    $resources
        ->requestCPU(CPU::millicores(500))
        ->requestMemory(Memory::mebibytes(512))
        ->limitMemory(Memory::gibibytes(1));
}

Merge rules to remember

Strategic merge is a set of rules per field: maps merge, some lists merge by a key (containers by name), some are replaced whole, and custom resources, which carry no merge information, are replaced. The alternative, JSON Patch, addresses list items by position, which breaks when a list is reordered. Kustomize builds the result without checking it against the schema; mistakes show when the API server reads it.

In Klass8s there is no merging: a variant is a method called on a typed builder after the base method, plain control flow with types.

No abstraction, derivation or rules

  • Reuse. The same init container in five workloads is five copies, or a Component that applies the same patch; neither takes parameters the way a constructor does. In Klass8s it is one class.
  • Derivation. namePrefix and the label transformers go some way, but nothing derives a Service's selector from its Deployment. configMapGenerator appends a content hash to generated ConfigMaps' names, which restarts the pods that read them, for the ConfigMaps it generates; Klass8s checksums every ConfigMap and Secret a pod reads and keeps the names.
  • Rules. "Every production workload sets limits" cannot be enforced by patches; it can be checked by another tool afterwards. In Klass8s it is a subscriber that fails the render.

Where Kustomize wins

  • YAML you do not own. A directory of upstream manifests that needs a namespace, an image and one variable: Kustomize was made for this, and a Klass8s project would be ceremony.
  • Nothing to install. kubectl apply -k needs nothing more; Klass8s needs PHP and Composer to render.
  • Nothing to learn but the merge rules, which is an advantage until the merge rules are what bites.
  • Everyone reads it. Every Kubernetes engineer reads a kustomization; a Klass8s project is read by PHP developers, and its output by everyone.

They combine

Klass8s prints plain YAML, so it can stand on either side of Kustomize: a dumped directory can be the base someone else overlays, and upstream YAML can keep going through -k while your own services are Apps (though software distributed as charts fits the Helm bridge better).

Side by side

KustomizeKlass8s
Adjusting YAML you do not ownmade for itthe wrong tool
Needed to rendernothing beyond kubectlPHP and Composer
Per-environment differencesoverlays and merge rulesmethods and attributes in one class
Checked before applyingby the API servertypes and references, at render time
Reusecopies, Componentsclasses, traits, dependency injection
Derived names, labels, selectorsprefixes and transformersderived
Rules for every resourceother toolssubscribers
Testsrender and comparePHPUnit
Learninglittle, until the merge rulesa framework

Moving from Kustomize

  1. Port the base. Each resource becomes a class; most of the YAML becomes what Klass8s derives.
  2. Fold in the overlays. Each patch becomes an environment method, an #[AfterMethod] decorator or a value in a per-environment file, next to the resource it changes.
  3. Turn repeated patches into subscribers. A patch in every overlay is a rule.
  4. Compare. APP_ENV=prod bin/console k8s:render:apps | kubectl diff -f - against the cluster.

A base and one small overlay: keep Kustomize. Fifteen patch files whose combined effect nobody can state: that is a program kept in a format that refuses to be one.