Guide
ConfigMaps and Secrets
Defining configuration and secrets, consuming them by class, the checksums that restart exactly the pods that read a change, and keeping real secrets out of manifests.
Configuration reaches pods through ConfigMaps and Secrets, and so do several classic failures: a consumer that names a resource that was renamed, pods running yesterday's configuration, credentials committed with the manifests. Klass8s answers each one structurally.
A ConfigMap
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringMap;
use Klass8s\App\ReadsResourceFiles;
use Klass8s\Core\ConfigMap\AbstractConfigMap;
class ApiConfigMap extends AbstractConfigMap
{
const string KEY_CACHE_HOST = 'CACHE_HOST';
const string KEY_NGINX = 'nginx.conf';
static shortName(): string => 'api';
data(StringMap $data): void {
assert($this->app instanceof ReadsResourceFiles);
$data->add(self::KEY_CACHE_HOST, 'valkey.cache.svc.cluster.local');
$data->add('LOG_LEVEL', 'info');
$data->add(self::KEY_NGINX, $this->app->readFile('configs/nginx.conf')); // a file stays a file
}
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringMap;
use Klass8s\App\ReadsResourceFiles;
use Klass8s\Core\ConfigMap\AbstractConfigMap;
class ApiConfigMap extends AbstractConfigMap
{
public const string KEY_CACHE_HOST = 'CACHE_HOST';
public const string KEY_NGINX = 'nginx.conf';
public static function shortName(): string
{
return 'api';
}
public function data(StringMap $data): void
{
assert($this->app instanceof ReadsResourceFiles);
$data->add(self::KEY_CACHE_HOST, 'valkey.cache.svc.cluster.local');
$data->add('LOG_LEVEL', 'info');
$data->add(self::KEY_NGINX, $this->app->readFile('configs/nginx.conf')); // a file stays a file
}
}Key names that other classes use are constants, so a renamed key is a change the type checker sees. A configuration file stays a file in the App's Resources/ directory (Apps). binaryData() takes binary values, and keysPrefix() puts a prefix before every key.
A Secret
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringMap;
use Klass8s\Core\Secret\AbstractSecret;
class SessionKeySecret extends AbstractSecret
{
const string KEY = 'session.key';
static shortName(): string => 'session-key';
// dev and test only: a real key comes from a secret store (below)
stringData(StringMap $stringData): void => $stringData->add(self::KEY, 'dev-session-key');
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use K8Schema\Collection\StringMap;
use Klass8s\Core\Secret\AbstractSecret;
class SessionKeySecret extends AbstractSecret
{
public const string KEY = 'session.key';
public static function shortName(): string
{
return 'session-key';
}
// dev and test only: a real key comes from a secret store (below)
public function stringData(StringMap $stringData): void
{
$stringData->add(self::KEY, 'dev-session-key');
}
}stringData() takes plain text, which Kubernetes encodes; data() takes values already base64-encoded. type() returns a SecretType, Opaque unless you say otherwise; AbstractBasicAuthSecret, AbstractDockerConfigSecret and AbstractServiceAccountSecret build the structured kinds (reference). A value written in a class is fine for development; a real secret does not belong there (below).
Consuming them as variables
A consumer names a class, and Klass8s resolves the resource name when it renders:
env(EnvConfigurator $env): void {
// every key as a variable
$env->addConfigMapClass(ApiConfigMap::class);
// with a prefix, and tolerating the ConfigMap's absence
$env->addConfigMapClass(FeatureFlagsConfigMap::class, mustExist: false, varNamesPrefix: 'FF_');
// one key
$env->varFromSecretClass('SESSION_KEY', SessionKeySecret::class, SessionKeySecret::KEY);
// a Secret this project does not render: the ExternalSecret's target, written by the operator
$env->addSecret('shop-database', external: true);
}public function env(EnvConfigurator $env): void
{
// every key as a variable
$env->addConfigMapClass(ApiConfigMap::class);
// with a prefix, and tolerating the ConfigMap's absence
$env->addConfigMapClass(FeatureFlagsConfigMap::class, mustExist: false, varNamesPrefix: 'FF_');
// one key
$env->varFromSecretClass('SESSION_KEY', SessionKeySecret::class, SessionKeySecret::KEY);
// a Secret this project does not render: the ExternalSecret's target, written by the operator
$env->addSecret('shop-database', external: true);
}external: true says that a name does not come from a manifest of this project. A name without it must belong to a ConfigMap or Secret the build renders, or the render fails: a mistake that would otherwise stop the pod with CreateContainerConfigError after the deploy fails on your machine instead. The check is made by the checksum subsystem (below), so with checksums switched off it is not made. To use another App's class, call withExternalApp('other') first (Apps).
Mounting them as files
volumes(VolumesConfigurator $volumes): void {
$volumes->fromConfigMapClass('nginx', ApiConfigMap::class)
->mapKeyToPath(ApiConfigMap::KEY_NGINX, 'default.conf');
$volumes->fromSecretClass('session', SessionKeySecret::class)->setDefaultMode(0o440);
$volumes->fromSecret('tls', 'shop-tls', external: true)->setDefaultMode(0o440);
}
volumeMounts(VolumeMountsConfigurator $mounts): void {
$mounts->add('nginx', '/etc/nginx/conf.d')->setReadOnly(true);
$mounts->add('session', '/run/session')->setReadOnly(true);
$mounts->add('tls', '/etc/tls')->setReadOnly(true);
}public function volumes(VolumesConfigurator $volumes): void
{
$volumes->fromConfigMapClass('nginx', ApiConfigMap::class)
->mapKeyToPath(ApiConfigMap::KEY_NGINX, 'default.conf');
$volumes->fromSecretClass('session', SessionKeySecret::class)->setDefaultMode(0o440);
$volumes->fromSecret('tls', 'shop-tls', external: true)->setDefaultMode(0o440);
}
public function volumeMounts(VolumeMountsConfigurator $mounts): void
{
$mounts->add('nginx', '/etc/nginx/conf.d')->setReadOnly(true);
$mounts->add('session', '/run/session')->setReadOnly(true);
$mounts->add('tls', '/etc/tls')->setReadOnly(true);
}external: true means the same here. mapKeyToPath() mounts one key under a file name of your choice, and setDefaultMode() sets the files' permissions.
Checksums: a change restarts exactly the pods that read it
Kubernetes does not restart pods when a ConfigMap they read as variables changes: they keep the old values until something else restarts them. Klass8s closes that gap by default. When it renders, it computes for each workload a checksum of the ConfigMaps and Secrets the workload reads, and writes it into the pod template:
# File: /shop/api.deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
klass8s.dev/app: shop
klass8s.dev/deploy-priority: '0'
labels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
name: shop-api
spec:
replicas: 1
revisionHistoryLimit: 1
selector:
matchLabels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
template:
metadata:
annotations:
klass8s.dev/env-sources-checksum: 1a0b87569057be6646a023158a864294
klass8s.dev/volume-sources-checksum: e40032017357918b3400d0f67ae9cf9f
labels:
app.kubernetes.io/name: shop
app.kubernetes.io/component: api
spec:
containers:
-
env:
- { name: SESSION_KEY, valueFrom: { secretKeyRef: { key: session.key, name: shop-session-key, optional: false } } }
envFrom:
- { configMapRef: { name: shop-api, optional: false } }
- { configMapRef: { name: shop-feature-flags, optional: true }, prefix: FF_ }
- { secretRef: { name: shop-database, optional: false } }
image: 'acme/shop-api:1.4.0'
imagePullPolicy: IfNotPresent
name: app
volumeMounts:
- { mountPath: /etc/nginx/conf.d, name: nginx, readOnly: true }
- { mountPath: /run/session, name: session, readOnly: true }
- { mountPath: /etc/tls, name: tls, readOnly: true }
volumes:
-
configMap:
items: [{ key: nginx.conf, path: default.conf }]
name: shop-api
name: nginx
-
name: session
secret:
defaultMode: 288
secretName: shop-session-key
-
name: tls
secret:
defaultMode: 288
secretName: shop-tlsenv-sources-checksum covers what the containers read as variables, volume-sources-checksum what they mount. Change a value in ApiConfigMap, render and apply, and the annotation changes, so the pod template changes, so Kubernetes rolls exactly the workloads that read that ConfigMap. Nothing else restarts, and no kubectl rollout restart is needed. It works because consumption is declared by class reference: Klass8s knows which workload reads what.
The calculation reads every container of the pod, init containers included. It is deterministic (sources sorted by name and kind, their data sorted before hashing), so the same input renders the same bytes, which is what lets a CI job render again and compare.
What a checksum cannot see
A source marked external: true, or a ConfigMap or Secret whose manifest is virtual, is a name without content: Klass8s never renders it, so it adds nothing to the checksum. The common case is an ExternalSecret: the pointer is rendered, the operator writes the Secret, and a rotation in the secret store restarts nothing. Klass8s cannot notice without reading the secret itself, and should not. A workload that must restart on rotation says so on its own: an annotation for a reloader controller, a process that re-reads the file, a sidecar that watches the mount.
A change of the reference itself (another Secret name, another mount path, another file mode) is part of the pod template already, and rolls the pods.
Switch the checksums off only with a reason:
klass8s:
auto_generate_checksums: falseReal secrets stay out of manifests
A credential in a Secret manifest is a credential in your repository, your CI logs and every rendered file. Keep the kinds apart:
- Development and test values may live in code, as above: they protect nothing.
- Real secrets stay in a secret manager. In the cluster, External Secrets Operator writes them into Secrets. The project renders only the pointer, an
ExternalSecret, and workloads read its target withexternal: true:
namespace App\K8S\Shop\Manifest;
use Klass8s\Manifest\AbstractSelfMakingManifest;
/** Asks External Secrets Operator to write the Secret shop-database from the store's entry. */
class DatabaseExternalSecret extends AbstractSelfMakingManifest
{
static apiVersion(): string => 'external-secrets.io/v1';
static kind(): string => 'ExternalSecret';
static shortName(): string => 'database';
spec(): map<string, mixed> => [
'refreshInterval' => '1h',
'secretStoreRef' => ['kind' => 'ClusterSecretStore', 'name' => 'platform'],
'target' => ['name' => $this->computedFullName],
'dataFrom' => [['extract' => ['key' => 'shop/database']]],
];
}<?php
declare(strict_types=1);
namespace App\K8S\Shop\Manifest;
use Klass8s\Manifest\AbstractSelfMakingManifest;
/** Asks External Secrets Operator to write the Secret shop-database from the store's entry. */
class DatabaseExternalSecret extends AbstractSelfMakingManifest
{
public static function apiVersion(): string
{
return 'external-secrets.io/v1';
}
public static function kind(): string
{
return 'ExternalSecret';
}
public static function shortName(): string
{
return 'database';
}
/**
* @return array<string, mixed>
*/
public function spec(): array
{
return [
'refreshInterval' => '1h',
'secretStoreRef' => ['kind' => 'ClusterSecretStore', 'name' => 'platform'],
'target' => ['name' => $this->computedFullName],
'dataFrom' => [['extract' => ['key' => 'shop/database']]],
];
}
}- Per environment, the store differs, not the consumers: one store class whose provider is chosen per environment (example).
Because the rendered output then contains no secret, it can be rendered and applied from anywhere (a laptop, a CI job without credentials) and committed for review without redaction.
Next
- Custom resources: the
ExternalSecretand other operators' kinds. - Events: the machinery the checksums are built on.