GuideWorkloads

Guide

Workloads

StatefulSets with their claims, Jobs and CronJobs, HorizontalPodAutoscalers, PriorityClasses, StorageClasses and scheduling.

Deployments cover stateless services. This page covers the other workloads and what goes with them. All of them share the container API.

StatefulSets

src/K8S/Search/Manifest/IndexStatefulSet.phnsrc/K8S/Search/Manifest/IndexStatefulSet.php
namespace App\K8S\Search\Manifest;

use App\K8S\Search\SearchApp;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Container\VolumeMount\VolumeMountsConfigurator;
use Klass8s\Core\StatefulSet\AbstractContainerStatefulSet;
use Klass8s\Core\StatefulSet\PodManagementPolicy;
use Klass8s\Manifest\Reference\ManifestClassReference;

class IndexStatefulSet extends AbstractContainerStatefulSet
{
    static shortName(): string => 'index';

    // required: the governing headless Service, by class
    serviceName(): ManifestClassReference => new ManifestClassReference(SearchApp::NAME, IndexHeadlessService::class);

    image(): Image => Image::fromName('acme/search-index')->setTag('2.1.0');

    replicas(): int => 3;

    podManagementPolicy(): ?PodManagementPolicy => PodManagementPolicy::Parallel;

    // one claim per pod, from a PersistentVolumeClaim manifest
    volumeClaimTemplates(): iterable {
        yield new DataVolumeClaim();
    }

    volumeMounts(VolumeMountsConfigurator $mounts): void => $mounts->add('data', '/var/lib/index', checkVolumeExistence: false);
}
<?php

declare(strict_types=1);

namespace App\K8S\Search\Manifest;

use App\K8S\Search\SearchApp;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Container\VolumeMount\VolumeMountsConfigurator;
use Klass8s\Core\StatefulSet\AbstractContainerStatefulSet;
use Klass8s\Core\StatefulSet\PodManagementPolicy;
use Klass8s\Manifest\Reference\ManifestClassReference;

class IndexStatefulSet extends AbstractContainerStatefulSet
{
    public static function shortName(): string
    {
        return 'index';
    }

    // required: the governing headless Service, by class
    public function serviceName(): ManifestClassReference
    {
        return new ManifestClassReference(SearchApp::NAME, IndexHeadlessService::class);
    }

    public function image(): Image
    {
        return Image::fromName('acme/search-index')->setTag('2.1.0');
    }

    public function replicas(): int
    {
        return 3;
    }

    public function podManagementPolicy(): ?PodManagementPolicy
    {
        return PodManagementPolicy::Parallel;
    }

    // one claim per pod, from a PersistentVolumeClaim manifest
    public function volumeClaimTemplates(): iterable
    {
        yield new DataVolumeClaim();
    }

    public function volumeMounts(VolumeMountsConfigurator $mounts): void
    {
        $mounts->add('data', '/var/lib/index', checkVolumeExistence: false);
    }
}

serviceName() is required: Kubernetes needs a governing Service for every StatefulSet, and the class names it by class, so the headless Service exists in the build:

src/K8S/Search/Manifest/IndexHeadlessService.phnsrc/K8S/Search/Manifest/IndexHeadlessService.php
namespace App\K8S\Search\Manifest;

use Klass8s\Core\Service\AbstractService;
use Klass8s\Core\Service\Configurator\ServicePortsConfigurator;

// The governing Service of the StatefulSet: one DNS name per pod.
class IndexHeadlessService extends AbstractService
{
    static shortName(): string => IndexStatefulSet::shortName();

    clusterIP(): ?string => 'None';

    ports(ServicePortsConfigurator $ports): void => $ports->add(9200, 9200)->setName('http');
}
<?php

declare(strict_types=1);

namespace App\K8S\Search\Manifest;

use Klass8s\Core\Service\AbstractService;
use Klass8s\Core\Service\Configurator\ServicePortsConfigurator;

// The governing Service of the StatefulSet: one DNS name per pod.
class IndexHeadlessService extends AbstractService
{
    public static function shortName(): string
    {
        return IndexStatefulSet::shortName();
    }

    public function clusterIP(): ?string
    {
        return 'None';
    }

    public function ports(ServicePortsConfigurator $ports): void
    {
        $ports->add(9200, 9200)->setName('http');
    }
}

volumeClaimTemplates() yields PersistentVolumeClaim manifests, one claim per pod:

src/K8S/Search/Manifest/DataVolumeClaim.phnsrc/K8S/Search/Manifest/DataVolumeClaim.php
namespace App\K8S\Search\Manifest;

use Klass8s\Core\Container\Resources\Memory;
use Klass8s\Core\Persistence\AbstractPersistentVolumeClaim;
use Klass8s\Core\Persistence\AccessMode;
use Klass8s\Core\Persistence\PvcResourcesConfigurator;

class DataVolumeClaim extends AbstractPersistentVolumeClaim
{
    static shortName(): string => 'data';

    accessModes(): iterable {
        yield AccessMode::ReadWriteOnce;
    }

    resources(PvcResourcesConfigurator $resources): void => $resources->requestStorage(Memory::gibibytes(10));

    storageClassName(): ?string => 'fast';
}
<?php

declare(strict_types=1);

namespace App\K8S\Search\Manifest;

use Klass8s\Core\Container\Resources\Memory;
use Klass8s\Core\Persistence\AbstractPersistentVolumeClaim;
use Klass8s\Core\Persistence\AccessMode;
use Klass8s\Core\Persistence\PvcResourcesConfigurator;

class DataVolumeClaim extends AbstractPersistentVolumeClaim
{
    public static function shortName(): string
    {
        return 'data';
    }

    public function accessModes(): iterable
    {
        yield AccessMode::ReadWriteOnce;
    }

    public function resources(PvcResourcesConfigurator $resources): void
    {
        $resources->requestStorage(Memory::gibibytes(10));
    }

    public function storageClassName(): ?string
    {
        return 'fast';
    }
}

A claim class in an App's discovered directories is also a manifest of that App, so it renders as a claim of its own too (search-data below). To use a class only as a template, keep it out of service discovery, as container classes are.

For infrastructure state (databases, brokers), the usual choice is an operator installed from its Helm chart, configured with its custom resource. Write your own StatefulSets for state your team owns.

Jobs

A Job is a container class plus backoffLimit(), activeDeadlineSeconds(), ttlSecondsAfterFinished(), completions(), parallelism() and suspend(). The migration Job in Containers is the common shape: it lives in a setup App that deploys before the workloads, waits for its dependency in an init container, runs one command and cleans itself up.

CronJobs

src/K8S/Shop/Manifest/SessionPruneCronJob.phnsrc/K8S/Shop/Manifest/SessionPruneCronJob.php
namespace App\K8S\Shop\Manifest;

use K8Schema\Collection\StringList;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\CronJob\AbstractContainerCronJob;

class SessionPruneCronJob extends AbstractContainerCronJob
{
    static shortName(): string => 'session-prune';

    schedule(): string => '15 3 * * *';

    timeZone(): ?string => 'Europe/Kyiv';

    image(): Image => Image::fromName('acme/shop-api')->setTag('1.4.0');

    args(StringList $args): void => $args->addAll(['bin/console', 'app:sessions:prune']);

    backoffLimit(): ?int => 2;

    ttlSecondsAfterFinished(): ?int => 300;
}
<?php

declare(strict_types=1);

namespace App\K8S\Shop\Manifest;

use K8Schema\Collection\StringList;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\CronJob\AbstractContainerCronJob;

class SessionPruneCronJob extends AbstractContainerCronJob
{
    public static function shortName(): string
    {
        return 'session-prune';
    }

    public function schedule(): string
    {
        return '15 3 * * *';
    }

    public function timeZone(): ?string
    {
        return 'Europe/Kyiv';
    }

    public function image(): Image
    {
        return Image::fromName('acme/shop-api')->setTag('1.4.0');
    }

    public function args(StringList $args): void
    {
        $args->addAll(['bin/console', 'app:sessions:prune']);
    }

    public function backoffLimit(): ?int
    {
        return 2;
    }

    public function ttlSecondsAfterFinished(): ?int
    {
        return 300;
    }
}

schedule() is the one required method. concurrencyPolicy() defaults to Forbid, so a run never overlaps the previous one unless you return Allow or Replace; Kubernetes' own default is Allow. The history limits, startingDeadlineSeconds() and suspendCronJob() are an override away; the Job's settings (backoffLimit() above) apply to every run.

HorizontalPodAutoscalers

src/K8S/Shop/Manifest/ApiHorizontalPodAutoscaler.phnsrc/K8S/Shop/Manifest/ApiHorizontalPodAutoscaler.php
namespace App\K8S\Shop\Manifest;

use App\K8S\Shop\ShopApp;
use K8Schema\Api\Autoscaling\V2\CrossVersionObjectReference;
use Klass8s\Core\Autoscaling\AbstractHorizontalPodAutoscaler;
use Klass8s\Core\Autoscaling\Configurator\MetricsConfigurator;
use Klass8s\Core\Autoscaling\Metric\TypedMetricTarget;
use Klass8s\Core\Container\Resources\ContainerResource;
use Klass8s\Manifest\Reference\VersionedManifestClassReference;

class ApiHorizontalPodAutoscaler extends AbstractHorizontalPodAutoscaler
{
    static shortName(): string => 'api';

    scaleTargetRef(): VersionedManifestClassReference|CrossVersionObjectReference
        => new VersionedManifestClassReference(ShopApp::NAME, ApiDeployment::class);

    minReplicas(): int => 2;

    maxReplicas(): int => 12;

    metrics(MetricsConfigurator $metrics): void
        => $metrics->addResourceMetric(ContainerResource::CPU, TypedMetricTarget::utilization(70));
}
<?php

declare(strict_types=1);

namespace App\K8S\Shop\Manifest;

use App\K8S\Shop\ShopApp;
use K8Schema\Api\Autoscaling\V2\CrossVersionObjectReference;
use Klass8s\Core\Autoscaling\AbstractHorizontalPodAutoscaler;
use Klass8s\Core\Autoscaling\Configurator\MetricsConfigurator;
use Klass8s\Core\Autoscaling\Metric\TypedMetricTarget;
use Klass8s\Core\Container\Resources\ContainerResource;
use Klass8s\Manifest\Reference\VersionedManifestClassReference;

class ApiHorizontalPodAutoscaler extends AbstractHorizontalPodAutoscaler
{
    public static function shortName(): string
    {
        return 'api';
    }

    public function scaleTargetRef(): VersionedManifestClassReference|CrossVersionObjectReference
    {
        return new VersionedManifestClassReference(ShopApp::NAME, ApiDeployment::class);
    }

    public function minReplicas(): int
    {
        return 2;
    }

    public function maxReplicas(): int
    {
        return 12;
    }

    public function metrics(MetricsConfigurator $metrics): void
    {
        $metrics->addResourceMetric(ContainerResource::CPU, TypedMetricTarget::utilization(70));
    }
}

The target is a class reference. metrics() adds resource, container-resource, pods, object and external metrics, and behavior() the scaling policies. For scaling on queue lengths and other external signals, Autoscaling generates KEDA ScaledObjects from attributes on the workload.

Priority and scheduling

src/K8S/Cluster/Manifest/CriticalPriorityClass.phnsrc/K8S/Cluster/Manifest/CriticalPriorityClass.php
namespace App\K8S\Cluster\Manifest;

use Klass8s\Core\PriorityClass\AbstractPriorityClass;

class CriticalPriorityClass extends AbstractPriorityClass
{
    static shortName(): string => 'critical';

    value(): int => 1000000;

    description(): ?string => 'Workloads on the path of a payment; preempts batch work.';
}
<?php

declare(strict_types=1);

namespace App\K8S\Cluster\Manifest;

use Klass8s\Core\PriorityClass\AbstractPriorityClass;

class CriticalPriorityClass extends AbstractPriorityClass
{
    public static function shortName(): string
    {
        return 'critical';
    }

    public function value(): int
    {
        return 1000000;
    }

    public function description(): ?string
    {
        return 'Workloads on the path of a payment; preempts batch work.';
    }
}

Every workload has the scheduling surface: priorityClass(), tolerations(), topologySpreadConstraints(), affinity() and nodeSelector():

src/K8S/Shop/Manifest/ApiDeployment.phnsrc/K8S/Shop/Manifest/ApiDeployment.php
priorityClass(PriorityClassConfigurator $priorityClass): void
    => $priorityClass->withExternalApp(ClusterApp::NAME)->fromPHPClass(CriticalPriorityClass::class);

tolerations(TolerationsConfigurator $tolerations): void => $tolerations->add(
    key: 'node.kubernetes.io/not-ready',
    operator: TolerationOperator::Exists,
    effect: TolerationEffect::NoExecute,
    tolerationSeconds: 30,
);

topologySpreadConstraints(TopologySpreadConstraintsConfigurator $constraints): void
    => $constraints->add(maxSkew: 1, topologyKey: WellKnownTopologyKeys::ZONE, whenUnsatisfiable: WhenUnsatisfiable::ScheduleAnyway);
public function priorityClass(PriorityClassConfigurator $priorityClass): void
{
    $priorityClass->withExternalApp(ClusterApp::NAME)->fromPHPClass(CriticalPriorityClass::class);
}

public function tolerations(TolerationsConfigurator $tolerations): void
{
    $tolerations->add(
        key: 'node.kubernetes.io/not-ready',
        operator: TolerationOperator::Exists,
        effect: TolerationEffect::NoExecute,
        tolerationSeconds: 30,
    );
}

public function topologySpreadConstraints(TopologySpreadConstraintsConfigurator $constraints): void
{
    $constraints->add(maxSkew: 1, topologyKey: WellKnownTopologyKeys::ZONE, whenUnsatisfiable: WhenUnsatisfiable::ScheduleAnyway);
}

fromPriorityClassName('system-cluster-critical') names a class outside the build. The configurators reference lists every method.

StorageClasses

A StorageClass is cluster-wide and known by a conventional name, so a class usually implements FullNameAwareInterface to keep its own name instead of <app>-<short name>:

src/K8S/Cluster/Manifest/FastStorageClass.phnsrc/K8S/Cluster/Manifest/FastStorageClass.php
namespace App\K8S\Cluster\Manifest;

use K8Schema\Collection\StringMap;
use Klass8s\Core\Persistence\AbstractStorageClass;
use Klass8s\Core\Persistence\AllowedTopologiesConfigurator;
use Klass8s\Core\Persistence\VolumeBindingMode;
use Klass8s\Manifest\FullNameAwareInterface;

// Cluster-wide and known by its name, so the name is its own rather than <app>-<short name>.
class FastStorageClass extends AbstractStorageClass implements FullNameAwareInterface
{
    static shortName(): string => 'fast';

    fullName(): string => 'fast';

    provisioner(): string => 'pd.csi.storage.gke.io';

    parameters(StringMap $parameters): void => $parameters->add('type', 'pd-ssd');

    volumeBindingMode(): VolumeBindingMode => VolumeBindingMode::WaitForFirstConsumer;

    allowVolumeExpansion(): bool => true;

    allowedTopologies(AllowedTopologiesConfigurator $topologies): void
        => $topologies->addTerm()->matchLabel('topology.kubernetes.io/zone', 'europe-west3-a', 'europe-west3-b');
}
<?php

declare(strict_types=1);

namespace App\K8S\Cluster\Manifest;

use K8Schema\Collection\StringMap;
use Klass8s\Core\Persistence\AbstractStorageClass;
use Klass8s\Core\Persistence\AllowedTopologiesConfigurator;
use Klass8s\Core\Persistence\VolumeBindingMode;
use Klass8s\Manifest\FullNameAwareInterface;

// Cluster-wide and known by its name, so the name is its own rather than <app>-<short name>.
class FastStorageClass extends AbstractStorageClass implements FullNameAwareInterface
{
    public static function shortName(): string
    {
        return 'fast';
    }

    public function fullName(): string
    {
        return 'fast';
    }

    public function provisioner(): string
    {
        return 'pd.csi.storage.gke.io';
    }

    public function parameters(StringMap $parameters): void
    {
        $parameters->add('type', 'pd-ssd');
    }

    public function volumeBindingMode(): VolumeBindingMode
    {
        return VolumeBindingMode::WaitForFirstConsumer;
    }

    public function allowVolumeExpansion(): bool
    {
        return true;
    }

    public function allowedTopologies(AllowedTopologiesConfigurator $topologies): void
    {
        $topologies->addTerm()->matchLabel('topology.kubernetes.io/zone', 'europe-west3-a', 'europe-west3-b');
    }
}

isDefaultClass() marks the cluster's default, the class a claim without storageClassName binds to. reclaimPolicy() (Delete) and mountOptions() complete the specification.

Ready-made storage for managed Kubernetes

Some managed products need storage that does not change between projects, and Klass8s has it under Klass8s\Cloud\<provider>\. Discovery works per App, so you subclass the class into the App that should own it, with an empty body:

src/K8S/Cluster/Manifest/Gp3StorageClass.phnsrc/K8S/Cluster/Manifest/Gp3StorageClass.php
namespace App\K8S\Cluster\Manifest;

use Klass8s\Cloud\Aws\EksAutoMode\Gp3StorageClass as EksAutoModeGp3StorageClass;

// The gp3 default class EKS Auto Mode does not create, owned by this App.
class Gp3StorageClass extends EksAutoModeGp3StorageClass {}
<?php

declare(strict_types=1);

namespace App\K8S\Cluster\Manifest;

use Klass8s\Cloud\Aws\EksAutoMode\Gp3StorageClass as EksAutoModeGp3StorageClass;

// The gp3 default class EKS Auto Mode does not create, owned by this App.
class Gp3StorageClass extends EksAutoModeGp3StorageClass {}

It renders the gp3 default class that EKS Auto Mode does not create; without it, every claim that relies on the default class stays Pending. The reference lists what it sets.

The render

Renderedbin/console k8s:render:apps cluster search shop
# File: /search/data.persistent-volume-claim.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  annotations:
    klass8s.dev/app: search
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: search
    app.kubernetes.io/component: data
  name: search-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: fast
  volumeMode: Filesystem
---
# File: /search/index.stateful-set.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  annotations:
    klass8s.dev/app: search
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: search
    app.kubernetes.io/component: index
  name: search-index
spec:
  podManagementPolicy: Parallel
  replicas: 3
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: search
      app.kubernetes.io/component: index
  serviceName: search-index
  template:
    metadata:
      annotations:
        klass8s.dev/env-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
        klass8s.dev/volume-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
      labels:
        app.kubernetes.io/name: search
        app.kubernetes.io/component: index
    spec:
      containers:
        -
          image: 'acme/search-index:2.1.0'
          imagePullPolicy: IfNotPresent
          name: app
          volumeMounts:
            - { mountPath: /var/lib/index, name: data }
  volumeClaimTemplates:
    -
      apiVersion: v1
      kind: PersistentVolumeClaim
      metadata:
        labels:
          app.kubernetes.io/name: search
          app.kubernetes.io/component: data
        name: data
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 10Gi
        storageClassName: fast
        volumeMode: Filesystem
---
# File: /shop/session-prune.cron-job.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  annotations:
    klass8s.dev/app: shop
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: shop
    app.kubernetes.io/component: session-prune
  name: shop-session-prune
spec:
  concurrencyPolicy: Forbid
  jobTemplate:
    metadata: {}
    spec:
      backoffLimit: 2
      suspend: false
      template:
        metadata:
          annotations:
            klass8s.dev/env-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
            klass8s.dev/volume-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
          labels:
            app.kubernetes.io/name: shop
            app.kubernetes.io/component: session-prune
        spec:
          containers:
            - { args: [bin/console, 'app:sessions:prune'], image: 'acme/shop-api:1.4.0', imagePullPolicy: IfNotPresent, name: app }
          restartPolicy: Never
      ttlSecondsAfterFinished: 300
  schedule: '15 3 * * *'
  suspend: false
  timeZone: Europe/Kyiv

Next