ReferenceConfiguration

Reference

Configuration

The complete klass8s configuration tree, its defaults and what each key does.

The klass8s: configuration, usually in config/packages/klass8s.yaml. Every key is optional. It is Symfony configuration, so a key in config/packages/prod/klass8s.yaml overrides the same key for APP_ENV=prod (Environments).

The tree at a glance

With the default values:

klass8s:
    # locations
    code_dir: '%kernel.project_dir%/src/K8S'
    namespace_prefix: 'App\K8S\'
    manifests_dir: '%kernel.project_dir%/var/k8s-manifests'

    # behaviour flags
    auto_set_replicas: false
    auto_set_resources: false
    auto_generate_checksums: true
    set_default_metadata_labels: true
    set_default_selector_labels: true
    set_default_service_selector: true
    strip_namespace: false

    # environment methods
    env_management:
        env_suffixed_methods:
            - replicas
            - resources

    # Apps and data for their manifests, keyed by the App's name
    apps:
        shop:
            enabled: true
            deploy_priority: 0
            manifests:
                api:
                    virtual: false
                    replicas: 4                        # read when auto_set_replicas is on
                    resources: { requests: { cpu: 100m, memory: 128Mi } }
                    rate_limit: 200                    # any other key: $this->config

    # Helm releases
    helm:
        chart_cache_dir: ~
        repositories:
            bitnami: https://charts.bitnami.com/bitnami
        releases:
            valkey:
                chart: bitnami/valkey
                version: '3.0.4'
                values: { architecture: standalone }
                namespace: ~
                deploy_priority: 0
                enabled: true

Locations

KeyDefaultMeaning
code_dir%kernel.project_dir%/src/K8Swhere k8s:make:* writes new classes; created by the first command that writes there
namespace_prefixApp\K8S\the namespace of the classes k8s:make:* writes
manifests_dir%kernel.project_dir%/var/k8s-manifestswhere k8s:dump:* writes; the environment is appended (layout); created by the first dump

Behaviour flags

KeyDefaultEffect
auto_set_replicasfalsea Deployment's or StatefulSet's replicas() is answered from manifests.<name>.replicas of its App's entry, 0 included; a Job or CronJob, which has no replicas, is left alone. A class that also declares replicas() fails the render with an error about the ambiguity: one owner per value (example)
auto_set_resourcesfalsethe same for resources(), from manifests.<name>.resources, for a Deployment, StatefulSet, Job or CronJob whose class is its own container
auto_generate_checksumstruethe checksums of the ConfigMaps and Secrets a pod reads, in its template; false removes the subscriber, and with it the check that every referenced name exists
set_default_metadata_labelstrueapp.kubernetes.io/name and app.kubernetes.io/component on every resource
set_default_selector_labelstruethe same labels in workloads' selectors
set_default_service_selectortruea Service's selector from the workload with its short name
strip_namespacefalseremoves metadata.namespace from all output, Apps and Helm releases alike, for projects that choose the namespace when they deploy (kubectl -n)

The three set_default_* flags switch their subscriber off for the whole project. For one class, use the attributes #[NoDefaultMetadataLabels], #[NoDefaultSelectorLabels] and #[NoDefaultServiceSelector].

Two more switches are environment variables: defining KLASS8S_USE_REPLICAS_POLICIES or KLASS8S_USE_RESOURCE_POLICIES (with any value) switches on centrally defined presets for replicas or resources, and KLASS8S_REPLICAS_POLICIES_ENV / KLASS8S_RESOURCE_POLICIES_ENV choose the environment whose presets apply (the kernel's by default).

env_management

env_suffixed_methods lists the methods that have environment variants. An entry is a name or an object:

klass8s:
    env_management:
        env_suffixed_methods:
            - replicas
            - { name: resources, for: [container, manifest] }
            - { name: ports, for: [container] }
            - { name: tolerations, if: '%spot_nodes%' }
            - { name: nodeSelector, if_not: '%some_parameter%' }
FieldDefaultMeaning
namerequiredthe method
for[container, manifest]the methods of manifests, of containers, or both
if, if_notnonethe entry applies when a boolean, or a parameter resolving to one, is true (false); not both. The list is compiled into the container, so an environment variable (%env(…)%) cannot decide it: container compilation fails and says why

Leaving the key out means replicas and resources, for both. The list is not merged across files: the last definition wins whole, so declare it in one place.

apps

Apps are found without configuration (Apps). This section switches them off, orders them, registers a class under another name, and gives their manifests data. It is keyed by the App's name, a valid DNS subdomain; a list whose entries carry the name as alias is read the same way.

KeyDefaultMeaning
enabledtruefalse leaves the App out: nothing registers, nothing renders
deploy_priority0the App's deployPriority(), written as the klass8s.dev/deploy-priority annotation of everything it owns
classfound by namethe App's class; needed only when the App's name is not a class's name(), to register a class twice
manifests.<short name>data for one manifest, below

Per manifest:

KeyMeaning
virtualtrue keeps the manifest in the build, referenceable by class, and leaves it out of the output: for a resource something else creates in this cluster. A workload that reads a virtual ConfigMap or Secret treats it as external, and the checksums leave it out
replicasread by auto_set_replicas
resourcesread by auto_set_resources: requests and limits maps of cpu, memory and storage, read by the same CPU and Memory value objects as code (memory as a whole number of bytes, alone or followed by Ki, Mi, Gi, Ti, Pi or Ei, and no more than PHP can count); or a string that points at another manifest's section, such as 'shop.manifests.api.resources.limits'
any other keyallowed by design; reaches the manifest as $this->config

helm

Helm releases. chart_cache_dir is where pulled charts are kept; left empty, KLASS8S_CHART_CACHE_DIR, then $XDG_CACHE_HOME/klass8s/charts, then ~/.cache/klass8s/charts, then the kernel's cache directory. repositories maps names to URLs, added with helm repo add before a render needs them. releases is keyed by release name:

KeyDefaultMeaning
chartrequiredrepository/name, https://…, oci://…, ./relative or /absolute (forms); a local path is checked when the container compiles
versionnullthe chart's version; null takes the latest, pulled again every hour
valuesnullthe values; placeholders resolved
values_fromnullthe id of a ValuesProviderInterface service; not together with values
deploy_priority0the klass8s.dev/deploy-priority annotation of the release's resources
namespacenullpassed to helm template --namespace; Helm's default is default
enabledtruea boolean or a placeholder resolving to one; a release that is not enabled is not rendered

Parameters outside the tree

ParameterDefaultMeaning
klass8s.annotation_domainklass8s.devthe domain of the checksum and autoscaling annotations