Start hereWhat is Klass8s?

Start here

What is Klass8s?

A library and Symfony bundle that defines Kubernetes manifests as classes and renders them to plain YAML.

Klass8s defines Kubernetes manifests as classes instead of YAML files. A manifest is a class, a group of manifests that deploy together is an App, and rendering runs them through a small Symfony application that prints ordinary Kubernetes YAML. You write the classes in Phaenon or in PHP; every example on this site shows both, and the tabs on any example switch all of them.

The point is not YAML in another syntax. Producing manifests is already a program: it has inputs (the environment, settings), logic (names, wiring, the differences between environments) and an output. Klass8s gives that program a typed language, a dependency injection container, an event system and tests, and keeps the output plain.

A manifest

A web API's Deployment, with production scaled differently from everywhere else:

src/K8S/Checkout/Manifest/ApiDeployment.phnsrc/K8S/Checkout/Manifest/ApiDeployment.php
namespace App\K8S\Checkout\Manifest;

use Klass8s\Core\Container\Env\EnvConfigurator;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Container\Ports\PortsConfigurator;
use Klass8s\Core\Container\Resources\ContainerResourcesInterface;
use Klass8s\Core\Container\Resources\CPU;
use Klass8s\Core\Container\Resources\Memory;
use Klass8s\Core\Deployment\AbstractContainerDeployment;

class ApiDeployment extends AbstractContainerDeployment
{
    const int PORT = 8080;

    static shortName(): string => 'api';

    image(): Image => Image::fromName('acme/checkout-api')->setTag('1.42.0');

    replicas(): int => 2;

    replicasProd(): int => 6;

    ports(PortsConfigurator $ports): void => $ports->add(self::PORT)->setName('http');

    env(EnvConfigurator $env): void {
        $env->addConfigMapClass(ApiConfigMap::class)
            ->varFromSecretClass('PAYMENTS_TOKEN', PaymentsSecret::class, PaymentsSecret::KEY_TOKEN);
    }

    resources(ContainerResourcesInterface $resources): void {
        $resources->requestCPU(CPU::millicores(250))->requestMemory(Memory::mebibytes(256));
    }
}
<?php

declare(strict_types=1);

namespace App\K8S\Checkout\Manifest;

use Klass8s\Core\Container\Env\EnvConfigurator;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Container\Ports\PortsConfigurator;
use Klass8s\Core\Container\Resources\ContainerResourcesInterface;
use Klass8s\Core\Container\Resources\CPU;
use Klass8s\Core\Container\Resources\Memory;
use Klass8s\Core\Deployment\AbstractContainerDeployment;

class ApiDeployment extends AbstractContainerDeployment
{
    public const int PORT = 8080;

    public static function shortName(): string
    {
        return 'api';
    }

    public function image(): Image
    {
        return Image::fromName('acme/checkout-api')->setTag('1.42.0');
    }

    public function replicas(): int
    {
        return 2;
    }

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

    public function ports(PortsConfigurator $ports): void
    {
        $ports->add(self::PORT)->setName('http');
    }

    public function env(EnvConfigurator $env): void
    {
        $env->addConfigMapClass(ApiConfigMap::class)
            ->varFromSecretClass('PAYMENTS_TOKEN', PaymentsSecret::class, PaymentsSecret::KEY_TOKEN);
    }

    public function resources(ContainerResourcesInterface $resources): void
    {
        $resources->requestCPU(CPU::millicores(250))->requestMemory(Memory::mebibytes(256));
    }
}
Renderedbin/console k8s:render:apps checkout
# File: /checkout/api.deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    klass8s.dev/app: checkout
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: checkout
    app.kubernetes.io/component: api
  name: checkout-api
spec:
  replicas: 2
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: checkout
      app.kubernetes.io/component: api
  template:
    metadata:
      annotations:
        klass8s.dev/env-sources-checksum: f06e7058bfb51fd08dda20d7e1cd3254
        klass8s.dev/volume-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
      labels:
        app.kubernetes.io/name: checkout
        app.kubernetes.io/component: api
    spec:
      containers:
        -
          env:
            - { name: PAYMENTS_TOKEN, valueFrom: { secretKeyRef: { key: token, name: checkout-payments, optional: false } } }
          envFrom:
            - { configMapRef: { name: checkout-api, optional: false } }
          image: 'acme/checkout-api:1.42.0'
          imagePullPolicy: IfNotPresent
          name: app
          ports:
            - { containerPort: 8080, name: http }
          resources:
            requests: { cpu: 250m, memory: 256Mi }

The class never states the resource name, the labels, the selector, the names of the ConfigMap and the Secret it reads, or the annotations that make the pods restart when that configuration changes. Registered in an App named checkout, Klass8s derives them:

  • the name checkout-api, the App's name and the manifest's short name, checked against the length Kubernetes allows;
  • the app.kubernetes.io/name and app.kubernetes.io/component labels, the same on the Deployment, its selector, its pod template and any Service that selects it;
  • the names of ApiConfigMap and PaymentsSecret, referenced by class, so a rename cannot leave a stale string behind, and a reference to a class that is not part of the build fails the render;
  • a checksum of every ConfigMap and Secret the pod reads, written into the pod template, so that changing the configuration rolls exactly these pods;
  • six replicas when the environment is prod, two everywhere else.

bin/console k8s:render:apps | kubectl apply -f - applies it.

What makes it more than YAML in a class

Manifests are services. Each manifest class takes part in Symfony's dependency injection: a hostname, an image tag or a whole helper service arrives through the constructor. Shared behaviour is a trait or a base class, not a copied block. See Configuration and DI.

Rendering can be observed. Every manifest is wrapped in a proxy, and every method call and every generated resource dispatches an event. One subscriber can run every pod under a ServiceAccount, refuse a production container without a memory limit, or add a sidecar to every workload. The framework's own conveniences (labels, checksums, environment-specific methods) are subscribers of the same kind. See Events.

The output is inert. Rendering prints multi-document YAML. Nothing of Klass8s runs in the cluster, no custom resource definition is needed to apply what it renders, and PHP is not needed after rendering. The same code, configuration and environment give the same bytes, so kubectl diff and a review of the rendered output mean something, and leaving Klass8s leaves you with a directory of ordinary manifests.

Who it is for

ReaderWhat they get
DevelopersKubernetes with completion and types: CPU::millicores(), ImagePullPolicy::IfNotPresent, $probes->readinessProbe(). A wrong type fails before anything is applied.
Platform engineersConventions in base classes, rules in event subscribers that fail the render when broken, and rendered YAML that stays reviewable.
Teams whose product is PHPOne language from the application to its manifests, and manifest code tested in the same CI.

What it is not

  • Not a deployment tool. Klass8s renders manifests. Applying them is kubectl's job, or a GitOps controller's, or a CD pipeline's; every resource carries the annotations a deploy orders by.
  • Not a cluster operator. Nothing runs inside Kubernetes. Klass8s works at build time, like a compiler.
  • Not a replacement for third-party Helm charts. Install cert-manager or a database operator from its chart; Klass8s renders Helm releases next to your own manifests, with their values in the same configuration.
  • Not language-agnostic. It is for teams who write PHP or Phaenon; why.

The packages

PackageWhat it is
klass8s/klass8sThe library and Symfony bundle: manifest classes, configurators, events, console commands
klass8s/k8schemaKubernetes API objects as PHP classes, generated from the Kubernetes OpenAPI specification and versioned with Kubernetes
klass8s/proximityThe proxy library under the event system
klass8s/k8schema-generatorThe application that generates k8schema from the Kubernetes API's schema

All four are under the MIT License. Related packages describes each.

Where to go next

Origins

Klass8s continues dealroadshow/k8s-framework, dealroadshow/k8s-bundle and dealroadshow/keda-bundle, three MIT-licensed projects that ran in production for years before they were merged into one package, renamed and extended. Klass8s itself is under the MIT License (LICENSE); the portions that come from those projects keep their own MIT notice, which ships with the package in NOTICE.