Guide
Autoscaling
Declare that a workload scales with an attribute and a trigger, and the build renders a KEDA ScaledObject for it, with the replica count left to the autoscaler.
A workload that should scale horizontally says so as a fact of its class, and the build derives the rest. Put #[Autoscale] and at least one trigger attribute on a Deployment manifest, and Klass8s spawns a KEDA ScaledObject for it into the workload's App:
namespace App\K8S\Media\Manifest;
use App\Autoscaling\ScaleOnQueueLag;
use K8Schema\Collection\StringList;
use Klass8s\Autoscaling\Attribute\Autoscale;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Deployment\AbstractContainerDeployment;
#[Autoscale(maxReplicas: 8, minReplicas: 1)]
#[ScaleOnQueueLag(stream: 'MEDIA', consumer: 'conversion', lagThreshold: 16)]
class ConversionWorkerDeployment extends AbstractContainerDeployment
{
static shortName(): string => 'conversion-worker';
image(): Image => Image::fromName('acme/media-worker')->setTag('2.0.0');
// what renders when autoscaling is off; with it on, the autoscaler owns the count
replicas(): int => 2;
args(StringList $args): void => $args->addAll(['bin/console', 'messenger:consume', 'conversion']);
}<?php
declare(strict_types=1);
namespace App\K8S\Media\Manifest;
use App\Autoscaling\ScaleOnQueueLag;
use K8Schema\Collection\StringList;
use Klass8s\Autoscaling\Attribute\Autoscale;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Deployment\AbstractContainerDeployment;
#[Autoscale(maxReplicas: 8, minReplicas: 1)]
#[ScaleOnQueueLag(stream: 'MEDIA', consumer: 'conversion', lagThreshold: 16)]
class ConversionWorkerDeployment extends AbstractContainerDeployment
{
public static function shortName(): string
{
return 'conversion-worker';
}
public function image(): Image
{
return Image::fromName('acme/media-worker')->setTag('2.0.0');
}
// what renders when autoscaling is off; with it on, the autoscaler owns the count
public function replicas(): int
{
return 2;
}
public function args(StringList $args): void
{
$args->addAll(['bin/console', 'messenger:consume', 'conversion']);
}
}# File: /media/conversion-worker.deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
klass8s.dev/autoscale: 1-8
klass8s.dev/app: media
klass8s.dev/deploy-priority: '0'
labels:
app.kubernetes.io/name: media
app.kubernetes.io/component: conversion-worker
name: media-conversion-worker
spec:
revisionHistoryLimit: 1
selector:
matchLabels:
app.kubernetes.io/name: media
app.kubernetes.io/component: conversion-worker
template:
metadata:
annotations:
klass8s.dev/env-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
klass8s.dev/volume-sources-checksum: d41d8cd98f00b204e9800998ecf8427e
labels:
app.kubernetes.io/name: media
app.kubernetes.io/component: conversion-worker
spec:
containers:
-
args:
- bin/console
- 'messenger:consume'
- conversion
image: 'acme/media-worker:2.0.0'
imagePullPolicy: IfNotPresent
name: app
---
# File: /media/conversion-worker-scaler.scaled-object.yaml
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
annotations:
klass8s.dev/app: media
klass8s.dev/deploy-priority: '0'
labels:
app.kubernetes.io/name: media
app.kubernetes.io/component: conversion-worker-scaler
name: media-conversion-worker-scaler
spec:
scaleTargetRef:
name: media-conversion-worker
apiVersion: apps/v1
kind: Deployment
pollingInterval: 30
cooldownPeriod: 300
minReplicaCount: 1
maxReplicaCount: 8
advanced:
horizontalPodAutoscalerConfig:
behavior: {}
triggers:
-
type: nats-jetstream
metadata:
stream: MEDIA
consumer: conversion
natsServerMonitoringEndpoint: 'nats.messaging.svc.cluster.local:8222'
lagThreshold: '16'Three things happen to the output:
- A ScaledObject appears beside the Deployment, named
<app>-<workload>-scaler, with the attribute's bounds and timing (pollingIntervalSecondstospec.pollingInterval, 30 by default;cooldownSecondstospec.cooldownPeriod, 300 by default) and one trigger per trigger attribute. KEDA scales on the largest of several triggers. spec.replicasdisappears from the Deployment. The autoscaler owns the replica count; a rendered one would make every apply fight it.replicas()stays in the class: it is what renders when autoscaling is off.- The Deployment is annotated
klass8s.dev/autoscalewith the effective bounds (1-8), oroffwhen scaling is switched off, so the output documents the scaling and tools find it without running any code.
The attributes are inherited, nearest class first: the closest class that declares #[Autoscale] supplies the whole attribute, and the closest class that declares trigger attributes supplies all of them.
Triggers and resolvers
A trigger attribute is data: a class attribute implementing the empty ScalingTriggerAttributeInterface.
namespace App\Autoscaling;
use Attribute;
use Klass8s\Autoscaling\Attribute\ScalingTriggerAttributeInterface;
/** Scale on the backlog of a JetStream consumer. Data only: the resolver turns it into a trigger. */
#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
final readonly class ScaleOnQueueLag implements ScalingTriggerAttributeInterface
{
__construct(public string $stream, public string $consumer, public int $lagThreshold) {}
}<?php
declare(strict_types=1);
namespace App\Autoscaling;
use Attribute;
use Klass8s\Autoscaling\Attribute\ScalingTriggerAttributeInterface;
/** Scale on the backlog of a JetStream consumer. Data only: the resolver turns it into a trigger. */
#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
final readonly class ScaleOnQueueLag implements ScalingTriggerAttributeInterface
{
public function __construct(public string $stream, public string $consumer, public int $lagThreshold) {}
}The logic is in a resolver, a service implementing ScalingTriggerResolverInterface (autoconfigured), which can therefore depend on anything the container provides:
namespace App\Autoscaling;
use Klass8s\Autoscaling\Attribute\ScalingTriggerAttributeInterface;
use Klass8s\Autoscaling\AutoscaleContext;
use Klass8s\Autoscaling\Keda\API\ScaledObject\Trigger;
use Klass8s\Autoscaling\Keda\Manifest\ScaledObject\Trigger\Nats\NatsJetStreamTrigger;
use Klass8s\Autoscaling\ScalingTriggerResolverInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
/** A service like any other: it may depend on whatever the container knows. */
final class ScaleOnQueueLagResolver implements ScalingTriggerResolverInterface
{
__construct(#[Autowire(env: 'NATS_MONITORING_ENDPOINT')] private string $monitoringEndpoint) {}
supports(ScalingTriggerAttributeInterface $attribute): bool => $attribute instanceof ScaleOnQueueLag;
resolve(ScalingTriggerAttributeInterface $attribute, AutoscaleContext $context): Trigger {
assert($attribute instanceof ScaleOnQueueLag);
return NatsJetStreamTrigger::forConsumer($attribute->stream, $attribute->consumer)
->monitoringEndpoint($this->monitoringEndpoint)
->lagThreshold($attribute->lagThreshold)
->build();
}
}<?php
declare(strict_types=1);
namespace App\Autoscaling;
use Klass8s\Autoscaling\Attribute\ScalingTriggerAttributeInterface;
use Klass8s\Autoscaling\AutoscaleContext;
use Klass8s\Autoscaling\Keda\API\ScaledObject\Trigger;
use Klass8s\Autoscaling\Keda\Manifest\ScaledObject\Trigger\Nats\NatsJetStreamTrigger;
use Klass8s\Autoscaling\ScalingTriggerResolverInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
/** A service like any other: it may depend on whatever the container knows. */
final class ScaleOnQueueLagResolver implements ScalingTriggerResolverInterface
{
public function __construct(#[Autowire(env: 'NATS_MONITORING_ENDPOINT')] private string $monitoringEndpoint) {}
public function supports(ScalingTriggerAttributeInterface $attribute): bool
{
return $attribute instanceof ScaleOnQueueLag;
}
public function resolve(ScalingTriggerAttributeInterface $attribute, AutoscaleContext $context): Trigger
{
assert($attribute instanceof ScaleOnQueueLag);
return NatsJetStreamTrigger::forConsumer($attribute->stream, $attribute->consumer)
->monitoringEndpoint($this->monitoringEndpoint)
->lagThreshold($attribute->lagThreshold)
->build();
}
}AutoscaleContext gives the resolver the workload manifest, its generated Deployment, its App and the environment. A resolver returns a KEDA Trigger, or a list of them when one attribute stands for several; an empty list fails the build, and so does anything else in the list ("Resolver … must return Klass8s\Autoscaling\Keda\API\ScaledObject\Trigger instances, … given"). Klass8s has builders for the CPU, memory, cron, Prometheus, RabbitMQ, MySQL, PostgreSQL, Redis, Redis Streams and NATS JetStream scalers (reference).
The policy
The attribute holds literal defaults. Whether a ScaledObject renders, and with which bounds, is decided at every render by the AutoscalePolicyInterface service. The default, AttributeAutoscalePolicy, passes the attribute through. A project can alias the interface to its own policy for decisions that belong to the deployment:
- Is KEDA installed in this environment? Return
AutoscaleDecision::disabled(), and the Deployment renders with itsreplicas(), as if it had no attribute, annotatedoff. - Other bounds per environment? Return
AutoscaleDecision::enabled($min, $max).
The split keeps the service's author declaring intent and signals in code, and the deployment deciding sizes and whether to scale at all, without environment names in attributes.
Guardrails
#[Autoscale]without a trigger attribute fails the build: a ScaledObject without triggers is invalid.- A workload that implements
NonScalableWorkloadInterface(a singleton that would race with its copies) fails the build when it carries the attribute. - The spawned name must fit the 52-character limit like any other.
- The attribute checks itself (
minReplicasat mostmaxReplicas, positive intervals) and fails the render with the class's name.
ScaledObjects written by hand
For what the attribute does not cover (fallbacks, custom HPA behaviour, idleReplicaCount, ScaledJobs), extend AbstractScaledObject or AbstractScaledJob as an ordinary manifest (reference). Both kinds coexist; the attribute machinery ignores manifests that are ScaledObjects already.
Under the hood
AutoscaleSubscriber sees every DeploymentGeneratedEvent, reads the attributes from the manifest's class, asks the policy, removes spec.replicas, and at ManifestsProcessedEvent (priority 512, before the late subscribers) resolves the triggers and spawns one AutoscaleScaledObject per workload through ManifestSpawner.