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
| Requirement | Version | Needed for |
|---|---|---|
| PHP | 8.5 or later | rendering; nothing runs in the cluster |
| Composer | 2 | installing the packages |
kubectl | any recent | applying what you render |
helm | 3 | only 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 k8sThen require Klass8s:
composer require klass8s/klass8sKlass8s 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.
<?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:
# 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 YAMLThe 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:
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 k8sThe 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/phnphaenon/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:
{"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:
{
"require": {
"php": ">=8.5"
},
"autoload": {
"psr-4": {
"App\\": ".src/"
}
}
}In config/services.yaml, the resource and its excludes name .src/:
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:
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:appsNext
The quick start writes an App with a Deployment, a ConfigMap and a Service, renders it and applies it.