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:
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, soresourcesProd()starts from whatresources()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,
iterableequalsarray|Traversableand class names ignore case. Types are compared as PHP resolves them: where a base method declared in a parent class saysself, the variant in a subclass names that parent class. A mismatch fails the render withClass "…" 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:
// 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:
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:
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']],
},
];
}
}# 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-1Configuration 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():
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']);
}
}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']);
}
}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 }klass8s:
apps:
media:
manifests:
thumbnailer:
replicas: 4
resources:
requests: { cpu: 500m, memory: 1Gi }
limits: { memory: 2Gi }klass8s:
apps:
media:
manifests:
thumbnailer:
replicas: 0 # off in the test cluster# 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 }# 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 }replicassizes Deployments and StatefulSets,0included, which keeps a workload off in an environment. A Job or a CronJob has no replica count: areplicaskey for one is ignored.resourcestakesrequestsandlimitswithcpu,memoryandstorage, read by the sameCPUandMemoryvalue 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 differs | Mechanism |
|---|---|
| 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 environments | a decorator with replacesReturnValue: true |
| whether a resource exists | #[EnabledForEnvs], #[When] |
| data | per-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:allAll of this is built on the event system: the environment methods and the decorators are ordinary subscribers, the kind your own rules can be.