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
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:
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:
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
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
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
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():
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>:
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:
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
# 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/KyivNext
- RBAC and ServiceAccounts
- Custom resources: when the workload is an operator's job.