Start hereInstallation

Start here

Installation

From an empty directory to a Symfony application that has the Klass8s commands, in PHP or in Phaenon.

A Klass8s project is a small Symfony console application whose services are your manifest classes. It can live in a k8s/ directory of the service it deploys, so that a change to the code and to its manifests is one pull request, or in a repository of its own for infrastructure that belongs to no single service.

Requirements

RequirementVersionNeeded for
PHP8.5 or laterrendering; nothing runs in the cluster
Composer2installing the packages
kubectlany recentapplying what you render
helm3only for Helm releases

Create the application

Start from Symfony's skeleton, or use an existing Symfony 8 application:

composer create-project symfony/skeleton k8s
cd k8s

Then require Klass8s:

composer require klass8s/klass8s

Klass8s is written in Phaenon, and its repository also carries the PHP it compiles to: a PHP project gets plain PHP, with no compiler, plugin or binary to install. A Phaenon project reads the .phn sources as well, for their richer types (generics and named shapes).

The package brings klass8s/k8schema, the Kubernetes API as PHP classes, at the newest Kubernetes version Klass8s supports. To render for an older cluster, pin the Kubernetes version you target with a tilde, as in composer require klass8s/k8schema:~1.35.8 for Kubernetes 1.35. Klass8s accepts the lines for Kubernetes 1.34 to 1.37. A caret would let a routine composer update move you to another Kubernetes API.

Register the bundles

There is no Flex recipe: add the Proximity bundle (the proxies behind the event system) and the Klass8s bundle to config/bundles.php.

config/bundles.php
<?php

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Proximity\Bundle\ProximityBundle::class => ['all' => true],
    Klass8s\Bundle\Klass8sBundle::class => ['all' => true],
];

That is the whole setup. With no configuration, Klass8s expects manifest classes under src/K8S/ in the namespace App\K8S\, and k8s:dump:* writes YAML into var/k8s-manifests/. To change either, add config/packages/klass8s.yaml; all keys are in the configuration reference:

config/packages/klass8s.yaml
# Every key is optional; these are the defaults written out.
klass8s:
    code_dir: '%kernel.project_dir%/src/K8S'          # where k8s:make:* writes new classes
    namespace_prefix: 'App\K8S\'                     # their namespace
    manifests_dir: '%kernel.project_dir%/var/k8s-manifests' # where k8s:dump:* writes YAML

The skeleton's config/services.yaml already registers everything under src/ as autowired, autoconfigured services, which is how Klass8s finds Apps and manifests. Exclude the directories that will hold sidecar and init container classes, which you construct yourself:

config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'
        exclude:
            - '../src/Kernel.php'
            # Sidecar and init container classes take constructor arguments you pass yourself.
            - '../src/K8S/*/Container/'

Check that the commands are there:

bin/console list k8s

The list shows k8s:render:* and k8s:dump:* for YAML, and k8s:make:app and k8s:make:manifest for scaffolding (see the console commands).

Write in Phaenon

A Phaenon project compiles its .phn sources into a sibling directory, src/ into .src/, and everything that loads classes reads them there. Starting from the application above:

composer config allow-plugins.phaenon/phn true
composer require --dev phaenon/phn

phaenon/phn is a Composer plugin: it brings the phn compiler as vendor/bin/phn and compiles the project whenever Composer writes the autoloader. Tell it what to compile with phaenon.json at the project root:

phaenon.json
{"roots": {"src": ".src"}}

Then point the autoloader and the services at the compiled directory, and state the PHP version the output targets. In composer.json:

composer.json (excerpt)
{
    "require": {
        "php": ">=8.5"
    },
    "autoload": {
        "psr-4": {
            "App\\": ".src/"
        }
    }
}

In config/services.yaml, the resource and its excludes name .src/:

config/services.yaml (excerpt)
    App\:
        resource: '../.src/'
        exclude:
            - '../.src/Kernel.php'
            - '../.src/K8S/*/Container/'

Add /.src/ to .gitignore, and run composer dump-autoload once. From then on, vendor/bin/phn build compiles after an edit and vendor/bin/phn watch compiles on every save; vendor/bin/phn check type-checks without writing anything. A .php file under src/, such as the skeleton's Kernel.php, is copied into .src/ as it is, so a project can move to Phaenon one class at a time.

What bin/console k8s:make:manifest queue deployment --app=shop writes, in a Phaenon project and in a PHP project:

src/K8S/Shop/Manifest/QueueDeployment.phnsrc/K8S/Shop/Manifest/QueueDeployment.php
namespace App\K8S\Shop\Manifest;

use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Deployment\AbstractContainerDeployment;

class QueueDeployment extends AbstractContainerDeployment
{
    image(): Image => Image::fromName('my-cool/image');

    static shortName(): string => 'queue';
}
<?php

declare(strict_types=1);

namespace App\K8S\Shop\Manifest;

use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Deployment\AbstractContainerDeployment;

class QueueDeployment extends AbstractContainerDeployment
{
    public function image(): Image
    {
        return Image::fromName('my-cool/image');
    }

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

In a PHP project the generated class begins with declare(strict_types=1);, and a hook method left empty is written {}, as in the files on these pages.

Environments

Klass8s uses Symfony's environment, APP_ENV. The names dev, test, qa, staging and prod have constants on Klass8s\Bundle\EnvManagement\Env, but any name works. Environment-specific methods, #[EnabledForEnvs] and per-environment configuration files all follow it:

APP_ENV=prod bin/console k8s:render:apps

Next

The quick start writes an App with a Deployment, a ConfigMap and a Service, renders it and applies it.