Guide
Helm charts
Third-party charts as releases of your project - values in the same per-environment configuration, rendered by the same commands, annotated and ordered like your Apps.
Third-party software arrives as Helm charts, and that is right: a community chart encodes its project's operational knowledge, and rewriting cert-manager as classes would be waste. What usually follows is not: a second configuration system (values-prod.yaml beside everything else), a second render pipeline, and a deploy order your own manifests know nothing about.
Klass8s makes a release, a chart with its values, part of the project. Its values sit in the same per-environment configuration, it renders through the same commands, its output carries the same klass8s.dev/* annotations, and it is ordered with your Apps. Helm does what it is good at, the chart's templates; Klass8s owns the configuration.
Rendering runs helm template, so the helm binary must be installed.
Releases in configuration
klass8s:
helm:
repositories:
bitnami: https://charts.bitnami.com/bitnami
releases:
valkey:
chart: bitnami/valkey
version: '3.0.4'
namespace: cache
values:
architecture: standalone
cert-manager:
chart: oci://quay.io/jetstack/charts/cert-manager
version: 'v1.18.2'
deploy_priority: -10
values_from: App\Helm\CertManagerValues
enabled: '%env(bool:INSTALL_CERT_MANAGER)%'
parameters:
env(INSTALL_CERT_MANAGER): 'true'| Key | Meaning |
|---|---|
chart | required; see chart references |
version | the chart's version; left out, the latest |
values | the values, with %env(…)% and parameters resolved |
values_from | the id of a service implementing ValuesProviderInterface; not together with values |
namespace | passed to helm template --namespace; some charts write it into their resources |
deploy_priority | written as the klass8s.dev/deploy-priority annotation of every resource of the release |
enabled | true by default; a boolean or a placeholder that resolves to one, such as '%env(bool:INSTALL_CERT_MANAGER)%'. A release that is not enabled is not rendered |
Repositories are added (helm repo add) before a render that needs them. They are chart repositories served over HTTP, since helm repo add takes no OCI registry: a chart in an OCI registry is named in chart by its full oci:// reference, as cert-manager's is above. Because this is Symfony configuration, config/packages/prod/klass8s.yaml overrides a release's values for production the way it overrides your manifests' data:
# config/packages/prod/klass8s.yaml
klass8s:
helm:
releases:
valkey:
values:
replica: { replicaCount: 3 }Values computed in code
When values need logic (a hostname derived from another manifest, a count per environment), implement ValuesProviderInterface and name the service with values_from:
namespace App\Helm;
use Klass8s\Bridge\Helm\ValuesProviderInterface;
/** Values computed in code: named in klass8s.yaml with values_from. */
final readonly class CertManagerValues implements ValuesProviderInterface
{
__construct(private string $environment = 'dev') {}
values(): map<string, mixed> => [
'crds' => ['enabled' => true],
'replicaCount' => 'prod' === $this->environment ? 2 : 1,
];
}<?php
declare(strict_types=1);
namespace App\Helm;
use Klass8s\Bridge\Helm\ValuesProviderInterface;
/** Values computed in code: named in klass8s.yaml with values_from. */
final readonly class CertManagerValues implements ValuesProviderInterface
{
public function __construct(private string $environment = 'dev') {}
/**
* @return array<string, mixed>
*/
public function values(): array
{
return [
'crds' => ['enabled' => true],
'replicaCount' => 'prod' === $this->environment ? 2 : 1,
];
}
}For full control, implement HelmReleaseInterface (a name, a chart reference, a deploy priority, a namespace and values()): every service that implements it is a release. The readonly HelmRelease class implements it, for when you would rather construct one than write a class.
Chart references
| Form | Example | Resolved by |
|---|---|---|
repository/name | bitnami/valkey | helm pull from a declared repository |
https://… | a chart archive's URL | helm pull |
oci://… | an OCI reference | helm pull |
./path | ./charts/legacy | a local chart, relative to the project |
/path | an absolute path | a local chart |
A local path is checked when the container compiles, so a mistyped path fails the build. Pulled charts are kept between renders, per chart and version: in helm.chart_cache_dir if set, else KLASS8S_CHART_CACHE_DIR, else $XDG_CACHE_HOME/klass8s/charts, else ~/.cache/klass8s/charts, and only when none is writable in the kernel's cache. A pinned version is pulled once per machine; a release without a version is pulled again every hour. Pin versions.
What rendering does
k8s:render:helm (or k8s:render:all) runs, per release, helm template <name> <chart> --include-crds with the namespace and the values. Then Klass8s parses every document of the output and dispatches HelmManifestProcessedEvent for it: its kind, its name, the release and the resource itself, mutable. Built-in subscribers add the klass8s.dev/app (the release's name) and klass8s.dev/deploy-priority annotations, and remove the namespace when strip_namespace is on. Yours can correct whatever a chart does not let you configure; the event system reaches vendor YAML too:
namespace App\EventSubscriber;
use Klass8s\Event\Helm\HelmManifestProcessedEvent;
use stdClass;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/** Pulls the images of every chart's Deployments through the company's mirror. */
final class ImageMirrorSubscriber implements EventSubscriberInterface
{
static getSubscribedEvents(): map<string, string> => [HelmManifestProcessedEvent::NAME => 'onHelmManifest'];
onHelmManifest(HelmManifestProcessedEvent $event): void {
if ('Deployment' !== $event->kind) {
return;
}
foreach (self::containers($event->resource) as $container) {
$image = $container->image ?? null;
if (is_string($image)) {
$container->image = str_replace('docker.io/', 'mirror.example.com/', $image);
}
}
}
// A chart's output is parsed YAML, plain objects without a schema: every step is checked.
private static containers(stdClass $deployment): list<stdClass> {
$spec = $deployment->spec ?? null;
$template = $spec instanceof stdClass ? $spec->template ?? null : null;
$podSpec = $template instanceof stdClass ? $template->spec ?? null : null;
$containers = $podSpec instanceof stdClass ? $podSpec->containers ?? null : null;
$found = [];
foreach (is_array($containers) ? $containers : [] as $container) {
if ($container instanceof stdClass) {
$found[] = $container;
}
}
return $found;
}
}<?php
declare(strict_types=1);
namespace App\EventSubscriber;
use Klass8s\Event\Helm\HelmManifestProcessedEvent;
use stdClass;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/** Pulls the images of every chart's Deployments through the company's mirror. */
final class ImageMirrorSubscriber implements EventSubscriberInterface
{
/**
* @return array<string, string>
*/
public static function getSubscribedEvents(): array
{
return [HelmManifestProcessedEvent::NAME => 'onHelmManifest'];
}
public function onHelmManifest(HelmManifestProcessedEvent $event): void
{
if ('Deployment' !== $event->kind) {
return;
}
foreach (self::containers($event->resource) as $container) {
$image = $container->image ?? null;
if (is_string($image)) {
$container->image = str_replace('docker.io/', 'mirror.example.com/', $image);
}
}
}
// A chart's output is parsed YAML, plain objects without a schema: every step is checked.
/**
* @return list<stdClass>
*/
private static function containers(stdClass $deployment): array
{
$spec = $deployment->spec ?? null;
$template = $spec instanceof stdClass ? $spec->template ?? null : null;
$podSpec = $template instanceof stdClass ? $template->spec ?? null : null;
$containers = $podSpec instanceof stdClass ? $podSpec->containers ?? null : null;
$found = [];
foreach (is_array($containers) ? $containers : [] as $container) {
if ($container instanceof stdClass) {
$found[] = $container;
}
}
return $found;
}
}A chart's output is parsed YAML, plain objects, not klass8s/k8schema classes: Klass8s does not check it against the Kubernetes schema, and a subscriber checks each step of the tree it walks.
Rendering and dumping
bin/console k8s:render:helm # every release, to standard output
bin/console k8s:render:helm valkey # one
bin/console k8s:render:all # your Apps, then the releases, in one stream
bin/console k8s:dump:all # files: var/k8s-manifests/<env>/apps/… and …/helm/<release>/…From there, nothing downstream needs to know which YAML came from a class and which from a chart. Ordering both is the subject of Rendering and deploying.
What the bridge is not
- Not
helm install. Klass8s only templates. Installing, upgrading and rolling back belong to the deploy step:kubectl applythe output, or a GitOps controller, and Helm's release records are not used. Where you want them for a chart, install that chart withhelminstead of rendering it here. - Not for your own applications. A chart for your own service, rendered through the bridge, is two templating systems where manifest classes need none.