GuideHelm charts

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

config/packages/klass8s.yaml
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'
KeyMeaning
chartrequired; see chart references
versionthe chart's version; left out, the latest
valuesthe values, with %env(…)% and parameters resolved
values_fromthe id of a service implementing ValuesProviderInterface; not together with values
namespacepassed to helm template --namespace; some charts write it into their resources
deploy_prioritywritten as the klass8s.dev/deploy-priority annotation of every resource of the release
enabledtrue 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:

src/Helm/CertManagerValues.phnsrc/Helm/CertManagerValues.php
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

FormExampleResolved by
repository/namebitnami/valkeyhelm pull from a declared repository
https://…a chart archive's URLhelm pull
oci://…an OCI referencehelm pull
./path./charts/legacya local chart, relative to the project
/pathan absolute patha 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:

src/EventSubscriber/ImageMirrorSubscriber.phnsrc/EventSubscriber/ImageMirrorSubscriber.php
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 apply the output, or a GitOps controller, and Helm's release records are not used. Where you want them for a chart, install that chart with helm instead 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.