Start hereProject structure

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 environment

The 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:

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/'

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.

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

Naming

ThingConventionExample
App class<Name>App in src/K8S/<Name>/ShopApp
App nameshort, a valid DNS labelshop
Manifest class<ShortName><Kind> in the App's Manifest/ApiDeployment
Resource name<app>-<short name>, at most 52 charactersshop-api
Dumped fileapps/<app>/<short name>.<kind>.yaml, the kind in kebab caseapps/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.