Start here
Project structure
The layout of a Klass8s project, what the framework's discovery expects, and the naming conventions that follow from it.
A Klass8s project is a Symfony application, so it has Symfony's layout; Klass8s adds a convention for where manifest classes live and how they are named.
Where the project lives
Two arrangements are common, and both work the same way:
- A
k8s/directory inside a service's repository. The manifests change in the same pull request as the code they deploy: a new endpoint and its route, a new queue and its worker. - A repository of its own, for what belongs to no single service: a gateway, operators, databases, secret stores, the Helm releases of third-party software.
The layout
With the defaults, a project with two Apps looks like this (in a Phaenon project the sources are .phn files, compiled into .src/ beside src/):
k8s/
├── bin/console
├── composer.json
├── config/
│ ├── bundles.php # FrameworkBundle, ProximityBundle, Klass8sBundle
│ ├── services.yaml # autowiring, bindings, excluded directories
│ └── packages/
│ ├── klass8s.yaml # optional: locations, behaviour flags, apps, Helm
│ └── prod/
│ └── klass8s.yaml # optional: values for APP_ENV=prod only
├── src/
│ ├── Kernel.php
│ ├── K8S/ # manifest code: one directory per App
│ │ ├── Shop/
│ │ │ ├── ShopApp.php # the App
│ │ │ ├── Manifest/ # one class per Kubernetes resource
│ │ │ │ ├── ApiDeployment.php
│ │ │ │ ├── ApiService.php
│ │ │ │ └── ApiConfigMap.php
│ │ │ ├── Container/ # sidecar and init container classes, not services
│ │ │ └── Resources/ # files the App reads: readFile('…') (ReadsResourceFiles)
│ │ └── ShopSetup/ # a second App: what must exist before the workloads
│ └── EventSubscriber/ # rules for the whole build (Guide: Events)
├── tests/ # render tests (Guide: Testing)
└── var/
└── k8s-manifests/ # k8s:dump:* output, by environmentThe conventions, and why
One App per unit that deploys together, one class per resource. Apps and manifests are found because they are services: the skeleton's config/services.yaml registers every class under src/, autoconfiguration tags them, and Klass8s collects the tagged ones. A manifest belongs to the App whose namespace contains it: App\K8S\Shop\Manifest\ApiDeployment belongs to the App App\K8S\Shop\ShopApp. Finding the class behind shop-api is a file search.
A setup App and a runtime App. What must exist before a workload starts (an ExternalSecret, a schema migration Job) goes into its own App, which deploys first: shop-setup, then shop. An App is also what you render and apply as one (bin/console k8s:render:apps shop-setup), and every resource names its App in the klass8s.dev/app annotation, which is how a deploy can order them.
Container/ directories are not services. Sidecar and init containers are classes you construct yourself, often with arguments, so config/services.yaml excludes them:
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/'Facts every manifest may need are bindings. The environment, a gateway's name, a public hostname: bound once in config/services.yaml, they reach any constructor that names the parameter. See Configuration and DI.
Files stay files. An nginx.conf or a Fluent Bit pipeline that a ConfigMap carries lives in the App's Resources/ directory and is read with $this->app->readFile('configs/nginx.conf'), the app narrowed to ReadsResourceFiles first (Apps). See Dynamic manifests.
klass8s.yaml
The file is optional. Every key has a default, and Apps need no entry: an App class in the container is registered under its name(). The apps section exists to override (switch an App off, set its deploy priority, hand a manifest its own configuration data); the whole schema is 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 YAMLNaming
| Thing | Convention | Example |
|---|---|---|
| App class | <Name>App in src/K8S/<Name>/ | ShopApp |
| App name | short, a valid DNS label | shop |
| Manifest class | <ShortName><Kind> in the App's Manifest/ | ApiDeployment |
| Resource name | <app>-<short name>, at most 52 characters | shop-api |
| Dumped file | apps/<app>/<short name>.<kind>.yaml, the kind in kebab case | apps/shop/api.deployment.yaml |
The 52-character limit leaves room for the suffixes Kubernetes adds to the names of the objects it creates from a resource, such as a Deployment's ReplicaSets and pods.
Next: Apps.