Guide
Apps
The App is the unit that groups manifests: it names their resources, labels them, carries their files and orders their deployment.
An App is a named group of manifests that render, reference each other and deploy together. In Helm's terms it takes the place of a chart, without the templates.
Defining an App
namespace App\K8S\Shop;
use Klass8s\App\AbstractApp;
final class ShopApp extends AbstractApp
{
const string NAME = 'shop';
static name(): string => self::NAME;
}<?php
declare(strict_types=1);
namespace App\K8S\Shop;
use Klass8s\App\AbstractApp;
final class ShopApp extends AbstractApp
{
public const string NAME = 'shop';
public static function name(): string
{
return self::NAME;
}
}An App is found because it is a service: any class implementing AppInterface (in practice, extending AbstractApp) that the container registers becomes available under its name(). A manifest belongs to the App whose namespace contains it, so App\K8S\Shop\Manifest\ApiDeployment belongs to App\K8S\Shop\ShopApp. The name must be a valid DNS subdomain. A NAME constant, as above, lets other classes refer to the App without repeating the string.
What an App decides
Names. Every resource name is <app>-<short name>: shop-api, shop-nginx. Klass8s checks the result against a 52-character limit, which leaves room for the suffixes Kubernetes adds to the objects it creates from a resource. The name appears nowhere in your code; another class that needs it asks the App: resourceNameFromManifestClass(ApiConfigMap::class) or resourceNameFromShortName('api').
Identity. Every resource of the App gets the labels app.kubernetes.io/name: <app> and app.kubernetes.io/component: <short name>, and the annotations klass8s.dev/app and klass8s.dev/deploy-priority. Tools that read the output (kubectl get -l, dashboards, a deploy that orders by them) can group and order resources without knowing your project.
Files. An App reads files from the Resources/ directory beside its class, so that a configuration file stays a file:
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringMap;
use Klass8s\App\ReadsResourceFiles;
use Klass8s\Core\ConfigMap\AbstractConfigMap;
class NginxConfigMap extends AbstractConfigMap
{
static shortName(): string => 'nginx';
data(StringMap $data): void {
// readFile() is on ReadsResourceFiles, which AbstractApp implements, and not on AppInterface
assert($this->app instanceof ReadsResourceFiles);
// src/K8S/Shop/Resources/configs/nginx.conf, beside the App class
$data->add('nginx.conf', $this->app->readFile('configs/nginx.conf'));
}
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringMap;
use Klass8s\App\ReadsResourceFiles;
use Klass8s\Core\ConfigMap\AbstractConfigMap;
class NginxConfigMap extends AbstractConfigMap
{
public static function shortName(): string
{
return 'nginx';
}
public function data(StringMap $data): void
{
// readFile() is on ReadsResourceFiles, which AbstractApp implements, and not on AppInterface
assert($this->app instanceof ReadsResourceFiles);
// src/K8S/Shop/Resources/configs/nginx.conf, beside the App class
$data->add('nginx.conf', $this->app->readFile('configs/nginx.conf'));
}
}readFile() throws at render time when the file does not exist, with the resolved path in the message. It belongs to Klass8s\App\ReadsResourceFiles, an interface AbstractApp implements, and not to AppInterface: a class that implements AppInterface directly need not keep files at all. A manifest's $this->app is an AppInterface, so the manifest asks for the capability it uses with assert($this->app instanceof ReadsResourceFiles), the same line in Phaenon and in PHP, and a type checker then knows that readFile() is there.
Deploy priority. deployPriority() (0 by default) is written into the klass8s.dev/deploy-priority annotation of everything the App owns, where deployment tools can read it. Set it with deploy_priority on the App's entry in config/packages/klass8s.yaml, which per-environment files can override, or override deployPriority() in the App class:
klass8s:
apps:
infrastructure:
deploy_priority: -10 # before the Apps that use it# File: /infrastructure/endpoints.config-map.yaml
apiVersion: v1
kind: ConfigMap
data:
CACHE_HOST: valkey.cache.svc.cluster.local
metadata:
annotations:
klass8s.dev/app: infrastructure
klass8s.dev/deploy-priority: '-10'
labels:
app.kubernetes.io/name: infrastructure
app.kubernetes.io/component: endpoints
name: infrastructure-endpointsSeveral Apps in one project
Most projects define several Apps, because "deploys together" has natural seams:
- Setup and runtime.
shop-setupholds what must exist before a workload starts (an ExternalSecret, a schema migration Job);shopholds the workloads. The setup App deploys first. - Capabilities. An infrastructure project defines one App per capability (
gateway,cache,secret-stores), each rendered and deployed on its own:
bin/console k8s:render:apps gateway cache # these two
bin/console k8s:render:apps # all of themReferences across Apps
Resources of one App often need resources of another: every workload runs under a ServiceAccount the infrastructure App provides, every service reads the infrastructure's endpoints. Such references stay classes:
// a ServiceAccount of another App, by class
serviceAccount(): ?ManifestClassReference
=> new ManifestClassReference(InfrastructureApp::NAME, WorkloadServiceAccount::class);
env(EnvConfigurator $env): void {
// every key of another App's ConfigMap as a variable
$env->withExternalApp(InfrastructureApp::NAME)->addConfigMapClass(EndpointsConfigMap::class);
// a name, where a value needs one
$env->var('ENDPOINTS_CONFIG_MAP', $this->apps->get(InfrastructureApp::NAME)->resourceNameFromManifestClass(EndpointsConfigMap::class));
}// a ServiceAccount of another App, by class
public function serviceAccount(): ?ManifestClassReference
{
return new ManifestClassReference(InfrastructureApp::NAME, WorkloadServiceAccount::class);
}
public function env(EnvConfigurator $env): void
{
// every key of another App's ConfigMap as a variable
$env->withExternalApp(InfrastructureApp::NAME)->addConfigMapClass(EndpointsConfigMap::class);
// a name, where a value needs one
$env->var('ENDPOINTS_CONFIG_MAP', $this->apps->get(InfrastructureApp::NAME)->resourceNameFromManifestClass(EndpointsConfigMap::class));
}- A
ManifestClassReferencenames an App and a manifest class; Klass8s resolves it to the resource name and fails the render when the App or the class does not exist. withExternalApp()returns a configurator bound to another App; the*Class()methods on it resolve that App's classes. Most configurators that take class references have it.AppRegistrygives any service the Apps by name, for the cases where a value (a connection string, an operator's specification) has to contain another App's resource name.
The rendered Deployment:
# File: /shop/api.deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
klass8s.dev/app: shop
klass8s.dev/deploy-priority: '0'
labels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
name: shop-api
spec:
replicas: 1
revisionHistoryLimit: 1
selector:
matchLabels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
template:
metadata:
annotations:
klass8s.dev/env-sources-checksum: ccce9555c3a288fb5b4bc16bb91fee73
klass8s.dev/volume-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
labels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
spec:
containers:
-
env:
- { name: ENDPOINTS_CONFIG_MAP, value: infrastructure-endpoints }
envFrom:
- { configMapRef: { name: infrastructure-endpoints, optional: false } }
image: 'acme/shop-api:1.0.0'
imagePullPolicy: IfNotPresent
name: app
serviceAccountName: infrastructure-workloadConfiguring Apps in YAML
Discovery covers the common case. The apps section of config/packages/klass8s.yaml, keyed by the Apps' names, adds control per App: switching an App off, ordering it, registering a class under a second name, and handing data to its manifests:
klass8s:
apps:
shop:
manifests:
api:
rate_limit: 200 # read by ApiDeployment as $this->config
legacy-worker:
virtual: true # stays referenceable, is not rendered
trust-bundle:
virtual: true # written by another system; read by ApiDeployment
reports:
enabled: false # not registered, not renderedenabled: falseleaves the App out entirely.deploy_prioritysets the App'sdeployPriority(), as above.virtual: truekeeps a manifest in the build, so that other classes can still reference it, and leaves it out of the output: for a resource something else creates in this cluster. A workload that reads a virtual ConfigMap or Secret by class gets its name and treats it as external: the render holds none of its bytes, so the checksums leave it out (example).- Any other key under a manifest reaches it as
$this->config, and per-environment files override it (Environments). classregisters an App class under an alias other than itsname(), to render one App definition twice.
The section may also be a list whose entries name their App with alias (- alias: shop); both forms merge the same way across files.
Next
- Manifests: the classes inside an App.
- Configuration and DI: how values reach Apps and manifests.