GuideAutoscaling

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:

src/K8S/Media/Manifest/ConversionWorkerDeployment.phnsrc/K8S/Media/Manifest/ConversionWorkerDeployment.php
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']);
    }
}
Renderedbin/console k8s:render:apps media
# 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:

  1. A ScaledObject appears beside the Deployment, named <app>-<workload>-scaler, with the attribute's bounds and timing (pollingIntervalSeconds to spec.pollingInterval, 30 by default; cooldownSeconds to spec.cooldownPeriod, 300 by default) and one trigger per trigger attribute. KEDA scales on the largest of several triggers.
  2. spec.replicas disappears 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.
  3. The Deployment is annotated klass8s.dev/autoscale with the effective bounds (1-8), or off when 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.

src/Autoscaling/ScaleOnQueueLag.phnsrc/Autoscaling/ScaleOnQueueLag.php
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:

src/Autoscaling/ScaleOnQueueLagResolver.phnsrc/Autoscaling/ScaleOnQueueLagResolver.php
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 its replicas(), as if it had no attribute, annotated off.
  • 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 (minReplicas at most maxReplicas, 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.