DeployingRendering and deploying

Deploying

Rendering and deploying

From classes to a running cluster - the render and dump commands, kubectl, GitOps, and ordering a deploy with what the output carries.

Klass8s stops at plain YAML, on purpose: nothing of it runs in the cluster, it keeps no state, and its output does not depend on it. This page covers the way from there to a running cluster: the bundle's render and dump commands, kubectl, GitOps, and how to order a deploy with what every rendered resource carries.

Rendering: YAML to standard output

bin/console k8s:render:apps                # every App
bin/console k8s:render:apps shop billing   # some
bin/console k8s:render:helm                # every Helm release
bin/console k8s:render:all                 # Apps, then releases, one stream (alias k8s:render)

The output is one multi-document YAML stream, each document after a # File: comment that names the file k8s:dump:* would write, so a long stream stays navigable. Two properties make it the main interface rather than a debugging aid:

  • Deterministic. The same code, configuration and APP_ENV give the same bytes, so a diff of the output means something.
  • Composable. It pipes into anything that reads YAML: kubectl, kubectl diff, yq, a GitOps repository.

The environment is chosen the Symfony way:

APP_ENV=prod bin/console k8s:render:apps | kubectl diff -f -

An App with nothing to render prints nothing.

Dumping: YAML to files

bin/console k8s:dump:apps            # or k8s:dump:helm, k8s:dump:all (alias k8s:dump)
bin/console k8s:dump:all -D build/   # another output directory
bin/console k8s:dump:all -R          # empty the environment's directory first

Files go under <manifests_dir>/<env>/, so the environments never overwrite each other:

var/k8s-manifests/dev/
├── apps/
│   └── shop/
│       ├── api.deployment.yaml
│       ├── api.service.yaml
│       └── config.config-map.yaml
└── helm/
    └── valkey/
        └── valkey-primary.stateful-set.yaml

One file per resource, named <name>.<kind>.yaml with the kind in kebab case. Without -R, a dump never deletes: a manifest removed from the code leaves its old file behind, so use -R for anything that feeds a deploy. Dump when you want files: a tree to commit for GitOps, to attach to a release, or to hand to a tool that reads directories.

kubectl

For one environment on a cluster you manage yourself, this is the whole deployment:

bin/console k8s:render:apps | kubectl diff -f -        # what would change
bin/console k8s:render:apps | kubectl apply -f -       # apply it
bin/console k8s:render:apps shop | kubectl apply -f -  # one App

No release state and no tool between you and the cluster. What a single kubectl apply does not give you is order: everything applies at once, and a resource can arrive before the operator that understands it.

Ordering a deploy

Klass8s does not deploy, so it does not order either; it gives the tool that applies what it needs to. Every rendered resource carries two annotations:

  • klass8s.dev/app: the App it belongs to, or the Helm release it came from;
  • klass8s.dev/deploy-priority: its App's deployPriority(), or a release's deploy_priority, set in the class or in config/packages/klass8s.yaml (Apps).

With the commands alone, render the Apps one at a time in the order you need, waiting where the next one depends on the last:

bin/console k8s:render:apps shop-setup | kubectl apply -f -
kubectl wait --for=condition=complete job/shop-setup-migration --timeout=300s
bin/console k8s:render:apps shop | kubectl apply -f -

A deploy tool or a GitOps controller can read the annotations instead: group the documents by klass8s.dev/app and apply the groups in ascending klass8s.dev/deploy-priority. Where your controller orders by an annotation of its own, a subscriber can write it next to these.

CI and GitOps

  • Render in CI. Rendering needs only PHP: no cluster and, because the manifests contain no secrets, no credentials. A job that runs composer install and k8s:render:apps (or the render tests) catches most mistakes in the pull request. With Phaenon, add vendor/bin/phn check.
  • Rendered manifests in Git. Commit the output of k8s:dump:all -R to the repository a GitOps controller such as Flux or Argo CD applies, one directory per App if the controller orders directories. The diff of the rendered YAML in a pull request is the review of what will change in the cluster; a release is a merge, and a rollback a revert.

Next