Building resources with value objects

Resources compose from typed value objects in RoundlyConsulting\KubernetesApi\Resources\Types, each serialising to the exact shape the apiserver expects. A pod with probes, resources, environment and volumes:

use RoundlyConsulting\KubernetesApi\Resources\ConfigMap;
use RoundlyConsulting\KubernetesApi\Resources\Secret;
use RoundlyConsulting\KubernetesApi\Resources\Types\Container;
use RoundlyConsulting\KubernetesApi\Resources\Types\Probe;
use RoundlyConsulting\KubernetesApi\Resources\Types\Volume;

$configVolume = Volume::make()->fromConfigMap(ConfigMap::make()->setName('checkout-config'));
$tlsVolume = Volume::make()->fromSecret(Secret::make()->setName('checkout-tls'));
$cacheVolume = Volume::make()->emptyDirectory('cache', ['sizeLimit' => '500Mi']);

$app = Container::make()
    ->setName('app')
    ->setImage('registry.example.com/checkout', 'v1.4.0')
    ->addPort(8080, 'TCP', 'http')
    ->setEnvironment(['APP_ENV' => 'production', 'LOG_CHANNEL' => 'stderr'])
    ->addToEnvironmentFromSecret('DB_PASSWORD', 'checkout-db', 'password')
    ->addToEnvironmentFromConfigMap('FEATURE_FLAGS', 'checkout-config', 'flags')
    ->addToEnvironmentFromFieldReference('POD_NAME', 'metadata.name')
    ->setMinimumCpu('250m')
    ->setMaximumCpu('1')
    ->setMinimumMemory(256, 'Mi')
    ->setMaximumMemory(512, 'Mi')
    ->setReadinessProbe(Probe::http('/healthz', 8080))
    ->setLivenessProbe(Probe::tcp(8080))
    ->addVolumeMount($configVolume->mountTo('/etc/checkout'))
    ->addVolumeMount($tlsVolume->mountTo('/etc/tls'))
    ->addVolumeMount($cacheVolume->mountTo('/var/cache/checkout'));

$pod = $cluster->pods()
    ->setNamespace('shop')
    ->setName('checkout-debug')
    ->setLabels(['app' => 'checkout', 'purpose' => 'debug'])
    ->setContainers([$app])
    ->addVolumes([$configVolume, $tlsVolume, $cacheVolume])
    ->addImagePullSecret('registry-credentials')
    ->create();

Container

Method	Writes
`setImage($image, $tag = 'latest')`	image as image:tag.
`addPort($containerPort, $protocol = 'TCP', $name = null)`	ports[].
`setEnvironment([...]) · addToEnvironment($name, $value) · addMultipleToEnvironment([...])`	env[] — setEnvironment() replaces the list.
`addToEnvironmentFromSecret($name, $secretName, $key = null)`	env[].valueFrom.secretKeyRef — the key defaults to the secret name.
`addToEnvironmentFromConfigMap($name, $configMapName, $key)`	env[].valueFrom.configMapKeyRef.
`addToEnvironmentFromFieldReference($name, $fieldPath)`	env[].valueFrom.fieldRef.
`setMinimumCpu($size) / setMaximumCpu($size)`	resources.requests.cpu / resources.limits.cpu.
`setMinimumMemory($size, $measure = 'Gi') / setMaximumMemory(…)`	resources.requests.memory / resources.limits.memory.
`setReadinessProbe() · setLivenessProbe() · setStartupProbe()`	The three probes, from a Probe.
`addVolumeMount() · addVolumeMounts() · setVolumeMounts()`	volumeMounts[], from VolumeMount objects.

The plural forms take maps: addToEnvironmentFromSecrets(['DB_PASSWORD' => ['checkout-db', 'password']]), addToEnvironmentFromConfigMaps(['FLAGS' => ['checkout-config', 'flags']]) and addToEnvironmentFromFieldReferences(['POD_NAME' => 'metadata.name']). Anything else — command, args, imagePullPolicy — goes through the magic setters.

Probes

Probe::http(), Probe::tcp() and command() build the three probe kinds. Tune thresholds and timings, or any other probe field, with the magic setters:

use RoundlyConsulting\KubernetesApi\Resources\Types\Probe;

Probe::http('/healthz', 8080);                                  // httpGet, scheme HTTP
Probe::http('/ready', 8443, ['X-Probe' => 'kubelet'], 'HTTPS'); // headers + scheme
Probe::tcp(5432);                                               // tcpSocket
Probe::make()->command(['pg_isready', '-U', 'shop']);           // exec

// Every probe starts with failureThreshold: 1 and successThreshold: 1
Probe::http('/healthz', 8080)
    ->setFailureThreshold(3)
    ->setPeriodSeconds(10)
    ->setInitialDelaySeconds(5);

Volumes, mounts and ports

Volume::fromConfigMap() and fromSecret() name the volume after its source — checkout-config-config-volume, checkout-tls-secret-volume.
emptyDirectory($name, $options) adds an emptyDir volume; pass its options, such as sizeLimit.
mountTo($mountPath, $subPath = null) turns any volume into a VolumeMount with the matching name.
Pod takes them through setContainers(), setInitContainers(), addVolume(s)(), setVolumes() and addImagePullSecret(s)(), and reads them back as objects with getContainers(), getInitContainers() and getVolumes().
Port::http($containerPort = 80) builds a TCP service port 80 targeting the container port; build other ports with Port::make() and the magic setters.
PersistentVolumeClaimTemplate describes a stateful set’s per-replica claim — see Workloads.

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages