GuideEnvironments

Guide

Environments

What differs between environments, written next to what it changes - environment-specific methods, methods added in some environments, manifests that exist in some, and configuration per environment.

Development wants one replica and a fake secret store; production wants six replicas and a real one. Most tools keep such differences in file trees (overlays, values-<env>.yaml), where one decision is spread over several files. Klass8s keeps them in the class they change, so that reading a manifest shows everything that differs for that resource.

The environment is Symfony's APP_ENV. Klass8s\Bundle\EnvManagement\Env has constants for the usual names: DEV (dev), TEST, QA, STAGING and PRODUCTION (prod). Any other name works the same way.

Methods per environment

For the values that differ in almost every project, add a method whose name ends with the environment's:

src/K8S/Shop/Manifest/ApiDeployment.phnsrc/K8S/Shop/Manifest/ApiDeployment.php
replicas(): int => 2;

replicasStaging(): int => 3;

replicasProd(): int => 6;

resources(ContainerResourcesInterface $resources): void
    => $resources->requestCPU(CPU::millicores(100))->requestMemory(Memory::mebibytes(128));

resourcesProd(ContainerResourcesInterface $resources): void {
    $resources
        ->requestCPU(CPU::millicores(500))
        ->requestMemory(Memory::mebibytes(512))
        ->limitMemory(Memory::gibibytes(1));
}
public function replicas(): int
{
    return 2;
}

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

public function replicasProd(): int
{
    return 6;
}

public function resources(ContainerResourcesInterface $resources): void
{
    $resources->requestCPU(CPU::millicores(100))->requestMemory(Memory::mebibytes(128));
}

public function resourcesProd(ContainerResourcesInterface $resources): void
{
    $resources
        ->requestCPU(CPU::millicores(500))
        ->requestMemory(Memory::mebibytes(512))
        ->limitMemory(Memory::gibibytes(1));
}
  • The suffix is the environment's name with its first letter upper-cased and spaces, hyphens and underscores removed: prod → Prod, load-test → Loadtest.
  • A method that returns a value replaces the base method's result. A configurator method (one that returns void) runs after the base one, on the same configurator, so resourcesProd() starts from what resources() set and changes what it touches.
  • The variant must declare the base method's parameters (names, types, by-reference, variadic and optional alike) and its return type, where a nullable return type counts as the type it makes nullable, the order of a union or an intersection does not matter, iterable equals array|Traversable and class names ignore case. Types are compared as PHP resolves them: where a base method declared in a parent class says self, the variant in a subclass names that parent class. A mismatch fails the render with Class "…" has env-aware version of method "replicas": method "replicasProd", but signatures do not match.

replicas and resources take part by default. Others can, for manifest methods, container methods or both, and conditionally:

klass8s:
    env_management:
        env_suffixed_methods:
            - replicas
            - resources
            - { name: ports, for: [container] }
            - { name: tolerations, if: '%spot_nodes%' }

if and if_not take a boolean or a container parameter that holds one, such as spot_nodes under parameters: in config/services.yaml. They cannot take an environment variable (%env(bool:SPOT_NODES)%): the list is compiled into the container, and an environment variable is known only when the container runs, so the container's compilation fails and says so. The list replaces the default, and does not merge across configuration files: declare it whole, in one place.

Methods added in some environments

To add something in some environments, or to decorate a method whose name says nothing about environments, use #[AfterMethod] or #[BeforeMethod] on a method of your own:

src/K8S/Shop/Manifest/ApiDeployment.phnsrc/K8S/Shop/Manifest/ApiDeployment.php
// dev and test mount a key from a Secret this project renders; other environments mount theirs
#[AfterMethod('volumes', forEnvs: [Env::DEV, Env::TEST])]
volumesDevKey(VolumesConfigurator $volumes): void
    => $volumes->fromSecretClass('signing-key', SigningKeySecret::class)->setDefaultMode(0o440);

#[AfterMethod('volumeMounts', forEnvs: [Env::DEV, Env::TEST])]
volumeMountsDevKey(VolumeMountsConfigurator $mounts): void
    => $mounts->add('signing-key', '/run/keys')->setReadOnly(true);
// dev and test mount a key from a Secret this project renders; other environments mount theirs
#[AfterMethod('volumes', forEnvs: [Env::DEV, Env::TEST])]
public function volumesDevKey(VolumesConfigurator $volumes): void
{
    $volumes->fromSecretClass('signing-key', SigningKeySecret::class)->setDefaultMode(0o440);
}

#[AfterMethod('volumeMounts', forEnvs: [Env::DEV, Env::TEST])]
public function volumeMountsDevKey(VolumeMountsConfigurator $mounts): void
{
    $mounts->add('signing-key', '/run/keys')->setReadOnly(true);
}

The decorating method must have the decorated one's parameters and return type, or the render fails. #[BeforeMethod] runs first, #[AfterMethod] afterwards; with replacesReturnValue: true the decorator's result replaces the method's.

The development key this mounts is a Secret that exists in development only:

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

use K8Schema\Collection\StringMap;
use Klass8s\App\ReadsResourceFiles;
use Klass8s\Bundle\EnvManagement\Attribute\EnabledForEnvs;
use Klass8s\Bundle\EnvManagement\Env;
use Klass8s\Core\Secret\AbstractSecret;

// A development key, rendered in dev and test only; other environments get theirs from a secret store.
#[EnabledForEnvs(Env::DEV, Env::TEST)]
class SigningKeySecret extends AbstractSecret
{
    const string KEY = 'signing.pem';

    static shortName(): string => 'signing-key';

    stringData(StringMap $stringData): void {
        assert($this->app instanceof ReadsResourceFiles);
        $stringData->add(self::KEY, $this->app->readFile('keys/dev-signing.pem'));
    }
}
<?php

declare(strict_types=1);

namespace App\K8S\Shop\Manifest;

use K8Schema\Collection\StringMap;
use Klass8s\App\ReadsResourceFiles;
use Klass8s\Bundle\EnvManagement\Attribute\EnabledForEnvs;
use Klass8s\Bundle\EnvManagement\Env;
use Klass8s\Core\Secret\AbstractSecret;

// A development key, rendered in dev and test only; other environments get theirs from a secret store.
#[EnabledForEnvs(Env::DEV, Env::TEST)]
class SigningKeySecret extends AbstractSecret
{
    public const string KEY = 'signing.pem';

    public static function shortName(): string
    {
        return 'signing-key';
    }

    public function stringData(StringMap $stringData): void
    {
        assert($this->app instanceof ReadsResourceFiles);
        $stringData->add(self::KEY, $this->app->readFile('keys/dev-signing.pem'));
    }
}

Manifests that exist in some environments

#[EnabledForEnvs] above renders a manifest in the environments it names and nowhere else. Symfony's own #[When(env: 'dev')] keeps any class out of the container outside that environment, which suits an App that exists for development only.

Decisions inside a method

Often the clearest form is plain code on an injected environment:

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

use Klass8s\Bundle\EnvManagement\Env;
use Klass8s\Manifest\AbstractSelfMakingManifest;

// An External Secrets Operator store, its provider chosen by environment.
class SecretStore extends AbstractSelfMakingManifest
{
    __construct(private string $environment) {}

    static apiVersion(): string => 'external-secrets.io/v1';

    static kind(): string => 'SecretStore';

    static shortName(): string => 'secrets';

    spec(): map<string, mixed> => [
        'provider' => match ($this->environment) {
            Env::DEV, Env::TEST => ['fake' => ['data' => [['key' => 'shop/database', 'value' => 'dev-only']]]],
            default => ['aws' => ['service' => 'SecretsManager', 'region' => 'eu-central-1']],
        },
    ];
}
<?php

declare(strict_types=1);

namespace App\K8S\Shop\Manifest;

use Klass8s\Bundle\EnvManagement\Env;
use Klass8s\Manifest\AbstractSelfMakingManifest;

// An External Secrets Operator store, its provider chosen by environment.
class SecretStore extends AbstractSelfMakingManifest
{
    public function __construct(private string $environment) {}

    public static function apiVersion(): string
    {
        return 'external-secrets.io/v1';
    }

    public static function kind(): string
    {
        return 'SecretStore';
    }

    public static function shortName(): string
    {
        return 'secrets';
    }

    /**
     * @return array<string, mixed>
     */
    public function spec(): array
    {
        return [
            'provider' => match ($this->environment) {
                Env::DEV, Env::TEST => ['fake' => ['data' => [['key' => 'shop/database', 'value' => 'dev-only']]]],
                default => ['aws' => ['service' => 'SecretsManager', 'region' => 'eu-central-1']],
            },
        ];
    }
}
RenderedAPP_ENV=prod bin/console k8s:render:apps shop
# File: /shop/secrets.secret-store.yaml
apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  annotations:
    klass8s.dev/app: shop
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: shop
    app.kubernetes.io/component: secrets
  name: shop-secrets
spec:
  provider:
    aws:
      service: SecretsManager
      region: eu-central-1

Configuration files per environment

The data half uses Symfony's configuration merging: config/packages/prod/klass8s.yaml overrides config/packages/klass8s.yaml for APP_ENV=prod, for manifest data and for Helm values alike.

Sizes from configuration

With auto_set_replicas and auto_set_resources, the replica counts and resources themselves come from these files, for teams where operations sets the sizes. The classes then declare neither replicas() nor resources():

src/K8S/Media/Manifest/ThumbnailerDeployment.phnsrc/K8S/Media/Manifest/ThumbnailerDeployment.php
namespace App\K8S\Media\Manifest;

use K8Schema\Collection\StringList;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Deployment\AbstractContainerDeployment;

// No replicas() and no resources(): with auto_set_* on, both come from config/packages/klass8s.yaml.
class ThumbnailerDeployment extends AbstractContainerDeployment
{
    static shortName(): string => 'thumbnailer';

    image(): Image => Image::fromName('acme/media-thumbnailer')->setTag('3.2.0');

    args(StringList $args): void => $args->addAll(['bin/console', 'messenger:consume', 'thumbnails']);
}
<?php

declare(strict_types=1);

namespace App\K8S\Media\Manifest;

use K8Schema\Collection\StringList;
use Klass8s\Core\Container\Image\Image;
use Klass8s\Core\Deployment\AbstractContainerDeployment;

// No replicas() and no resources(): with auto_set_* on, both come from config/packages/klass8s.yaml.
class ThumbnailerDeployment extends AbstractContainerDeployment
{
    public static function shortName(): string
    {
        return 'thumbnailer';
    }

    public function image(): Image
    {
        return Image::fromName('acme/media-thumbnailer')->setTag('3.2.0');
    }

    public function args(StringList $args): void
    {
        $args->addAll(['bin/console', 'messenger:consume', 'thumbnails']);
    }
}
src/K8S/Media/Manifest/PruneCronJob.phnsrc/K8S/Media/Manifest/PruneCronJob.php
namespace App\K8S\Media\Manifest;

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

// No resources(): with auto_set_resources on, they come from config/packages/klass8s.yaml.
class PruneCronJob extends AbstractContainerCronJob
{
    static shortName(): string => 'prune';

    schedule(): string => '30 4 * * *';

    image(): Image => Image::fromName('acme/media-thumbnailer')->setTag('3.2.0');

    args(StringList $args): void => $args->addAll(['bin/console', 'app:thumbnails:prune']);
}
<?php

declare(strict_types=1);

namespace App\K8S\Media\Manifest;

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

// No resources(): with auto_set_resources on, they come from config/packages/klass8s.yaml.
class PruneCronJob extends AbstractContainerCronJob
{
    public static function shortName(): string
    {
        return 'prune';
    }

    public function schedule(): string
    {
        return '30 4 * * *';
    }

    public function image(): Image
    {
        return Image::fromName('acme/media-thumbnailer')->setTag('3.2.0');
    }

    public function args(StringList $args): void
    {
        $args->addAll(['bin/console', 'app:thumbnails:prune']);
    }
}
config/packages/klass8s.yaml
klass8s:
    auto_set_replicas: true
    auto_set_resources: true
    apps:
        media:
            manifests:
                thumbnailer:
                    replicas: 1
                    resources:
                        requests: { cpu: 100m, memory: 256Mi }
                        limits: { memory: 512Mi }
                prune:
                    resources:                 # Jobs and CronJobs take resources too
                        requests: { cpu: 50m, memory: 64Mi }
                        limits: { memory: 128Mi }
config/packages/prod/klass8s.yaml
klass8s:
    apps:
        media:
            manifests:
                thumbnailer:
                    replicas: 4
                    resources:
                        requests: { cpu: 500m, memory: 1Gi }
                        limits: { memory: 2Gi }
config/packages/test/klass8s.yaml
klass8s:
    apps:
        media:
            manifests:
                thumbnailer:
                    replicas: 0                # off in the test cluster
RenderedAPP_ENV=prod bin/console k8s:render:apps media
# File: /media/thumbnailer.deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    klass8s.dev/app: media
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: media
    app.kubernetes.io/component: thumbnailer
  name: media-thumbnailer
spec:
  replicas: 4
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: media
      app.kubernetes.io/component: thumbnailer
  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: thumbnailer
    spec:
      containers:
        -
          args:
            - bin/console
            - 'messenger:consume'
            - thumbnails
          image: 'acme/media-thumbnailer:3.2.0'
          imagePullPolicy: IfNotPresent
          name: app
          resources:
            limits: { memory: 2Gi }
            requests: { cpu: 500m, memory: 1Gi }
RenderedAPP_ENV=test bin/console k8s:render:apps media
# File: /media/thumbnailer.deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    klass8s.dev/app: media
    klass8s.dev/deploy-priority: '0'
  labels:
    app.kubernetes.io/name: media
    app.kubernetes.io/component: thumbnailer
  name: media-thumbnailer
spec:
  replicas: 0
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: media
      app.kubernetes.io/component: thumbnailer
  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: thumbnailer
    spec:
      containers:
        -
          args:
            - bin/console
            - 'messenger:consume'
            - thumbnails
          image: 'acme/media-thumbnailer:3.2.0'
          imagePullPolicy: IfNotPresent
          name: app
          resources:
            limits: { memory: 512Mi }
            requests: { cpu: 100m, memory: 256Mi }
  • replicas sizes Deployments and StatefulSets, 0 included, which keeps a workload off in an environment. A Job or a CronJob has no replica count: a replicas key for one is ignored.
  • resources takes requests and limits with cpu, memory and storage, read by the same CPU and Memory value objects as code, for the main container of a Deployment, a StatefulSet, a Job or a CronJob.
  • A manifest that also declares the method fails the render ("Replicas for manifest … are declared both in manifests' config and in method …::replicas(), which leads to ambiguity", and the same for resources): each value has one owner.

Choosing

What differsMechanism
a number (replicas, limits)an environment method, or configuration with auto_set_*
a structure added in some environments#[AfterMethod(…, forEnvs: […])]
a value swapped in some environmentsa decorator with replacesReturnValue: true
whether a resource exists#[EnabledForEnvs], #[When]
dataper-environment klass8s.yaml

One rule ties them together: what differs between environments is reviewable in one place. And one caution: every difference in shape (a listener, a route, a Secret that exists in development only) is a way for a development cluster to stop proving production. Prefer differences in values (a hostname, a replica count) and keep the shapes the same where you can.

Rendering an environment

APP_ENV=prod bin/console k8s:render:apps | kubectl diff -f -
APP_ENV=staging bin/console k8s:dump:all

All of this is built on the event system: the environment methods and the decorators are ordinary subscribers, the kind your own rules can be.