GuideApps

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

src/K8S/Shop/ShopApp.phnsrc/K8S/Shop/ShopApp.php
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:

src/K8S/Shop/Manifest/NginxConfigMap.phnsrc/K8S/Shop/Manifest/NginxConfigMap.php
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:

config/packages/klass8s.yaml
klass8s:
    apps:
        infrastructure:
            deploy_priority: -10    # before the Apps that use it
Renderedbin/console k8s:render:apps infrastructure shop
# 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-endpoints

Several Apps in one project

Most projects define several Apps, because "deploys together" has natural seams:

  • Setup and runtime. shop-setup holds what must exist before a workload starts (an ExternalSecret, a schema migration Job); shop holds 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 them

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

src/K8S/Shop/Manifest/ApiDeployment.phnsrc/K8S/Shop/Manifest/ApiDeployment.php
// 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 ManifestClassReference names 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.
  • AppRegistry gives 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:

Renderedbin/console k8s:render:apps infrastructure shop
# 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-workload

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

config/packages/klass8s.yaml
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 rendered
  • enabled: false leaves the App out entirely.
  • deploy_priority sets the App's deployPriority(), as above.
  • virtual: true keeps 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).
  • class registers an App class under an alias other than its name(), 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