ReferenceConfigurators

Reference

Configurators

Every builder a manifest method receives, by area, with its public methods.

Named constructors (Image::fromName(), PodField::metadataName(), CPU::millicores()) return static in a class you may extend and self in a final one, and fluent methods return static. Manifest hook methods are void: they receive a framework-instantiated builder, you call methods on it, and the framework assembles the result (the escape hatch runs afterwards for anything a builder doesn't cover). This page catalogs every builder, grouped by domain, with its complete public API.

Two conventions recur throughout: *Class(...) methods take a manifest ::class reference resolved (and validated) at render time, while their string twins take raw names for resources outside the build; and withExternalApp('alias') returns a configurator bound to another App for cross-App references. Most APIs are fluent; void-returning methods are flagged.

Identity & references

MetadataConfigurator (Klass8s\Manifest) — received by metadata() on every manifest:

  • labels(): StringMap · annotations(): StringMap

ManifestClassReference (Klass8s\Manifest\Reference) — the cross-App reference value object; returned from serviceAccount(), dataSource(), StatefulSetInterface::serviceName(), gatewayClass(), and accepted by several configurators:

  • __construct(string $appAlias, string $className, ?string $apiGroup = null)

VersionedManifestClassReference — same, with ?string $apiVersion instead of apiGroup; used by HPA scaleTargetRef() and KEDA.

Label selectors

SelectorConfigurator (Klass8s\Core\LabelSelector) — selector() on Deployment/StatefulSet/Job/PVC and Prometheus monitors; also nested in topology constraints and ClusterRole aggregation:

  • addLabel(string $name, string $value): static · addLabels(array $labels): static
  • addExpression(LabelSelectorExpression $expression): static

LabelSelectorExpression:

  • static withKey(string $key): static, then one of in(array) / notIn(array) / exists() / doesNotExist() (operator immutable once set)

Container

Received through the container API.

EnvConfigurator (Klass8s\Core\Container\Env) — env():

  • var(string $name, string $value): static — literal
  • addConfigMapClass(string $class, bool $mustExist = true, ?string $varNamesPrefix = null): static · addSecretClass(string $class, bool $mustExist = true): static — all keys as env vars
  • addConfigMap(string $name, bool $mustExist = true, ?string $varNamesPrefix = null, bool $external = false): static · addSecret(string $name, bool $mustExist = true, bool $external = false): static — by raw name; external: true skips build validation
  • addFromClass(string $class, bool $mustExist = true, ?string $varNamesPrefix = null): static · addFromClasses(string ...$classes): static — kind-agnostic class refs
  • varFromConfigMapClass(string $var, string $class, string $key, bool $optional = false): static · varFromSecretClass(string $var, string $class, string $key, bool $optional = false): static — single key
  • varFromPod(string $var, PodField $field): static · varFromContainerResources(string $var, ContainerResourcesField $field): static — downward API
  • withExternalApp(string $appAlias): EnvConfigurator

PodField (Klass8s\Core\Pod) — static factories metadataName(), metadataNamespace(), metadataLabels(), metadataAnnotations(), metadataUid(), nodeName(), serviceAccountName(), hostIp(), podIp().

ContainerResourcesField (Klass8s\Core\Container\Resources) — static factories cpuLimits(), cpuRequests(), memoryLimits(), memoryRequests(), storageLimits(), storageRequests(); plus setContainerName(?string): static, setDivisor(string): static.

PortsConfigurator — ports(): add(int $containerPort): ContainerPortBuilder, then setName(string), setProtocol(IPProtocol) (TCP|UDP|SCTP), setHostIP(string), setHostPort(int) — all : static.

ResourcesConfigurator (implements ContainerResourcesInterface) — resources(); the interface is exactly six methods:

  • requestCPU(CPU): static · limitCPU(CPU): static
  • requestMemory(Memory): static · limitMemory(Memory): static
  • requestStorage(Memory): static · limitStorage(Memory): static

CPU — static millicores(int), static cores(int), static fromString(string); arithmetic/comparison add(), greaterThan(), lowerThan(), equals(); millicoresNumber(): int, toString().

Memory — static bytes(int) … kibibytes / mebibytes / gibibytes / tebibytes / pebibytes / exbibytes, static fromString(string) (a whole number of bytes, alone or followed by Ki, Mi, Gi, Ti, Pi or Ei: 134217728, 128Mi; anything else, a fraction, an exponent or surrounding whitespace included, is an InvalidArgumentException, and so is an amount larger than PHP can count: Memory string "…" is more bytes than PHP can count, which is 9223372036854775807.); same arithmetic/comparison; bytesNumber(): int, toString().

Image (Klass8s\Core\Container\Image) — return type of image():

  • static fromName(string), static fromString(string) (parses a full reference)
  • setName(), setRegistryUrl(), setTag(), setPrefix() — all : static; readers imageName(), registryUrl(), tag(), fullName()

ProbesConfigurator — probes(): livenessProbe() / readinessProbe() / startupProbe(), each : ProbeConfigurator:

  • tuning: setInitialDelaySeconds(int), setPeriodSeconds(int), setTimeoutSeconds(int), setFailureThreshold(int), setSuccessThreshold(int) — all : static
  • action(): ProbeActionConfigurator → exec(array $command): void · tcpSocket(int|string $port, ?string $host = null): void · httpGet(int|string $port): HttpGetActionBuilder

HttpGetActionBuilder — setPath(), setScheme(), setHost(), setPort(), addHeader(string $name, string $value) — all : static.

LifecycleConfigurator — lifecycle(): preStop() / postStart() : LifecycleActionConfigurator with the same exec() / tcpSocket() (void) / httpGet() action API as probes.

SecurityContextConfigurator — securityContext():

  • runAsUser(int), setRunAsGroup(int), runAsNonRoot(bool), setReadOnlyRootFilesystem(bool), allowPrivilegeEscalation(bool), setPrivileged(bool), setProcMount(string) — all : static
  • capabilities(): CapabilitiesConfigurator → add(array $capabilities): void · drop(array $capabilities): void (note: arrays, e.g. drop(['ALL']))
  • seLinuxOptions(): SELinuxOptionsConfigurator → setUser(), setRole(), setType(), setLevel() — all : static

VolumeMountsConfigurator — volumeMounts(): add(string $volumeName, string $mountPath, bool $checkVolumeExistence = true): VolumeMountBuilder, then setReadOnly(bool), setSubPath(string), setSubPathExpression(string), setVolumePropagation(MountPropagation) — all : static.

Pod

Received by workload manifests (see the shared pod surface).

VolumesConfigurator (Klass8s\Core\Pod\Volume) — volumes():

  • fromConfigMapClass(string $volumeName, string $class) / fromConfigMap(string $volumeName, string $name) : ConfigMapVolumeBuilder
  • fromSecretClass(...) / fromSecret(...) : SecretVolumeBuilder
  • fromPvcClass(...) / fromPvc(...) : PVCVolumeBuilder
  • fromEmptyDir(string $volumeName): EmptyDirVolumeBuilder · fromHostPath(string $volumeName, string $path): HostPathVolumeBuilder · fromDownwardAPI(string $volumeName): DownwardAPIVolumeBuilder
  • withExternalApp(string $appAlias): VolumesConfigurator

Volume builders:

  • ConfigMap/Secret: mapKeyToPath(string $key, string $path), setOptional(bool), setDefaultMode(int) — : static
  • EmptyDir: useRAM(): static, setSizeLimit(Memory): static
  • DownwardAPI: setDefaultMode(int): static, exposePodInfo(string $filePath, PodField $field, ?int $mode = null): static, exposeContainerResources(string $filePath, ContainerResourcesField $field, ?int $mode = null): static
  • HostPath: setType(HostPathVolumeType): static (DirectoryOrCreate|Directory|FileOrCreate|File|Socket|CharDevice|BlockDevice)
  • PVC: setReadOnly(): void

AffinityConfigurator — affinity(): nodeAffinity(): NodeAffinityBuilder, podAffinity() / podAntiAffinity() : PodAffinityBuilder:

  • NodeAffinityBuilder: addRequirement(NodeAffinityExpression): static · addPreference(NodeAffinityExpression, int $weight): static
  • PodAffinityBuilder: addRequirementByLabels(array $labels, string $topologyKey, ?array $namespaces = null): static · addPreferenceByLabels(array $labels, int $weight, string $topologyKey, ?array $namespaces = null): static · addRequirementByExpression(...) / addPreferenceByExpression(...) — same with a PodAffinityExpression
  • PodAffinityExpression: static label(string $key) / static field(string $key), then the LabelSelectorExpression operators; NodeAffinityExpression adds greaterThan(int) / lowerThan(int)

TolerationsConfigurator — tolerations():

  • add(?string $key, TolerationOperator $operator = Equal, ?string $value = null, ?TolerationEffect $effect = null, ?int $tolerationSeconds = null): static (Exists|Equal; NoSchedule|PreferNoSchedule|NoExecute)

TopologySpreadConstraintsConfigurator — topologySpreadConstraints():

  • add(int $maxSkew, string $topologyKey, WhenUnsatisfiable $whenUnsatisfiable): TopologySpreadConstraintConfigurator (DoNotSchedule|ScheduleAnyway), then labelSelector(): SelectorConfigurator, matchLabelKeys(string ...), setMinDomains(int), nodeAffinityPolicy(NodePolicy) / nodeTaintsPolicy(NodePolicy) (Honor|Ignore) — : static

ImagePullSecretsConfigurator (Klass8s\Core\Pod\ImagePullSecrets) — workload imagePullSecrets():

  • addSecretClass(string $secretClass): static · addSecret(string $secretName): static

PriorityClassConfigurator — priorityClass():

  • fromPHPClass(string $class): void · fromPriorityClassName(string $name): void · withExternalApp(string $appAlias): static

Workload-specific

StrategyConfigurator (Klass8s\Core\Deployment) — strategy(); void methods:

  • rollingUpdate(NumberOrPercents $maxSurge, NumberOrPercents $maxUnavailable): void · recreate(): void
  • NumberOrPercents: static number(int) / static percents(int)

UpdateStrategyConfigurator (Klass8s\Core\StatefulSet\UpdateStrategy) — updateStrategy():

  • onDelete(): void · rollingUpdate(): RollingUpdateStrategyConfigurator → setPartition(int): void

Service

ServicePortsConfigurator — ports(): add(int $servicePort, int|string $targetPort): ServicePortConfigurator, then setName(string), setProtocol(IPProtocol), setNodePort(int) — : static.

ServiceTypeConfigurator — type(); void methods: clusterIP(), nodePort(), loadBalancer(), externalName(string $externalName).

Ingress

IngressRulesConfigurator — rules(): addHttpRule(?string $host = null): IngressRuleConfigurator → addPath(PathType $pathType, ?string $path = null): HttpIngressPathConfigurator (Exact|Prefix|ImplementationSpecific) → backend(): IngressBackendConfigurator.

IngressBackendConfigurator — also received directly by defaultBackend(); void methods:

  • fromServiceClassAndPort(string $serviceClass, int|string $servicePort): void · fromServiceNameAndPort(string $serviceName, int|string $servicePort): void · fromManifestReference(ManifestClassReference): void
  • withExternalApp(string $appAlias): static

ServiceAccount

Distinct from the pod-level image-pull configurator — this one takes references:

ImagePullSecretsConfigurator (Klass8s\Core\ServiceAccount\Configurator) — imagePullSecrets(): add(ManifestClassReference $secretReference): static (must reference a SecretInterface class).

SecretsConfigurator — secrets(): addFromManifestReference(ManifestClassReference): static · addFromObjectReference(ObjectReference): static.

RBAC

PolicyRulesConfigurator — rules(): add(): PolicyRuleConfigurator, then (all : static):

  • addApiGroups(string ...) ('' = core group) · addResources(string ...) · addResourceNames(string ...) · addNonResourceURLs(string ...) · addVerbs(Verb ...) (Get|List|Watch|Create|Update|Patch|Delete|DeleteCollection|All)
  • rule(): PolicyRule — raw k8schema escape hatch (e.g. for resource-specific verbs like impersonate, bind, escalate, use)

AggregationRuleConfigurator — ClusterRole aggregationRule(): addClusterRoleSelector(): SelectorConfigurator.

RoleRefConfigurator — binding roleRef(); void methods (configure once, no chaining):

  • fromRoleClass(string $roleClass): void · fromClusterRoleClass(string $clusterRoleClass): void — validated against the owning App
  • fromRoleName(string): void · fromClusterRoleName(string): void
  • withExternalApp(string $appAlias): RoleRefConfigurator

SubjectsConfigurator — binding subjects() (all : static):

  • addServiceAccountClass(string $class, string $namespace) · addServiceAccount(string $name, string $namespace)
  • addUser(string $name) · addGroup(WellKnownUserOrGroup|string $group)
  • withExternalApp(string $appAlias)

Autoscaling (HPA)

MetricsConfigurator — metrics() (all : static):

  • addResourceMetric(ContainerResource $resource, TypedMetricTarget $target) (CPU|MEMORY|EPHEMERAL_STORAGE|STORAGE)
  • addContainerResourceMetric(ContainerResource, TypedMetricTarget, string $container)
  • addPodsMetric(string $name, TypedMetricTarget, ?\Closure $selectorCallback = null)
  • addObjectMetric(string $name, TypedMetricTarget, VersionedManifestClassReference|CrossVersionObjectReference $describedObject, ?\Closure $selectorCallback = null)
  • addExternalMetric(string $name, TypedMetricTarget, ?\Closure $selectorCallback = null)

TypedMetricTarget — static utilization(int), static value(float|string), static averageValue(float|string).

BehaviorConfigurator — HPA and KEDA behavior(): scaleUp() / scaleDown() : HPAScalingRulesConfigurator:

  • addPolicy(ScalingPolicy): static (ScalingPolicy::pods(int $amountOfChange, int $periodSeconds) / ::percents(...))
  • stabilizationWindowSeconds(int): static (0–3600) · selectPolicy(SelectPolicy): static (Min|Max|Disabled)

PVC

PvcResourcesConfigurator — resources() on PVCs: requestStorage(Memory): static · limitStorage(Memory): static.

StorageClass

AllowedTopologiesConfigurator — allowedTopologies() on StorageClasses: addTerm(): AllowedTopologyTermConfigurator (terms are OR-ed), then matchLabel(string $key, string ...$values): static (requirements within a term are AND-ed). parameters() receives the raw K8Schema\Collection\StringMap (add(string $name, string $value)).

CRD

CrdNamesConfigurator — names() (all : static): singular(string), listKind(string), shortNames(string ...), categories(string ...).

CrdVersionsConfigurator — versions(): addVersion(string $name, bool $served = true, bool $storage = true): CrdVersionConfigurator, then:

  • openApiV3Schema(array $schema): static — raw OpenAPI v3 array, by design
  • addPrinterColumn(string $name, string $type, string $jsonPath): PrinterColumnConfigurator → description(string), format(string), priority(int) — : static
  • subresources(): SubresourcesConfigurator → enableStatus(): static · scale(string $specReplicasPath, string $statusReplicasPath, ?string $labelSelectorPath = null): static
  • addSelectableField(string $jsonPath): static · deprecated(bool $deprecated = true, ?string $warning = null): static

Gateway API

ListenersConfigurator — Gateway listeners(): add(string $name): ListenerConfigurator:

  • port(int), protocol(ProtocolType) (HTTP|HTTPS|TLS|TCP|UDP), hostname(string) — : static
  • tls(): TlsConfigurator → terminate() / passthrough() / mode(TlsMode), certificateRefFromClass(string $secretClass, ?string $namespace = null), certificateRef(string $name, ?string $namespace = null, string $group = '', string $kind = 'Secret'), options(array) — : static
  • allowedRoutes(): AllowedRoutesConfigurator → fromSameNamespace(), fromAllNamespaces(), fromSelector(array $matchLabels), allowHTTPRoutes(), allowGRPCRoutes(), allowKinds(array) — : static

AddressesConfigurator — Gateway addresses(): addIPAddress(string), addHostname(string), addNamedAddress(string), add(AddressType, string) — : static.

InfrastructureConfigurator — Gateway infrastructure(): label(string, string), annotation(string, string), parametersRef(string $group, string $kind, string $name) — : static.

ParentRefsConfigurator — route parentRefs(): add(string $name) / addFromClass(string $gatewayClass) : ParentRefConfigurator → namespace(string), sectionName(string), port(int), group(string), kind(string) — : static.

HTTPRouteRulesConfigurator — rules(): add(): HTTPRouteRuleConfigurator:

  • name(string): static · timeout(string $duration): static · backendTimeout(string $duration): static · retry(array $codes, int $attempts, ?string $backoff = null): static
  • match(): HTTPRouteMatchConfigurator → pathPrefix(string), pathExact(string), pathRegex(string), path(PathMatchType, string), method(HTTPMethod), header(string $name, string $value, HeaderMatchType $type = Exact), queryParam(...) — : static
  • filter(): HTTPRouteFilterConfigurator → urlRewrite(?string $hostname = null, ?HTTPPathModifierType $pathType = null, ?string $pathValue = null), requestRedirect(?string $scheme, ?string $hostname, ?int $port, ?int $statusCode, ?HTTPPathModifierType $pathType, ?string $pathValue), requestHeaderModifier(array $set = [], array $add = [], array $remove = []), responseHeaderModifier(...), requestMirror(string $serviceName, int $port, ?int $percent = null, ?string $namespace = null), extensionRef(string $group, string $kind, string $name) — : static
  • backendRef(): HTTPBackendRefConfigurator → serviceClass(string $serviceClass, int $port), service(string $name, int $port), weight(int), namespace(string), group(string), kind(string) — : static; filter(): HTTPRouteFilterConfigurator

GRPCRouteRulesConfigurator — add(): GRPCRouteRuleConfigurator with name(), match(): GRPCRouteMatchConfigurator (method(?string $service = null, ?string $method = null, GRPCMethodMatchType $type = Exact), header(...)), plus the same filter() / backendRef() as HTTP routes.

TargetRefsConfigurator — BackendTLSPolicy targetRefs(): addServiceClass(string $serviceClass, ?string $sectionName = null), addService(string $name, ?string $sectionName = null), add(string $group, string $kind, string $name, ?string $sectionName = null) — : static.

TLSValidationConfigurator — validation() (all : static): hostname(string), caCertificateFromSecretClass(string) / caCertificateFromSecret(string $name, …) / caCertificateFromConfigMapClass(string) / caCertificateFromConfigMap(string $name, …), wellKnownCACertificates(string $type = 'System'), subjectAltNameHostname(string), subjectAltNameURI(string).

OptionsConfigurator — options(): set(string $key, string $value): static.

ReferenceGrantFromConfigurator — from(): allowHTTPRoutes(string $namespace), allowGRPCRoutes(string $namespace), allowGateways(string $namespace), add(string $group, string $kind, string $namespace) — : static. ReferenceGrantToConfigurator — to(): allowServices(?string $name = null), allowSecrets(?string $name = null), allowConfigMaps(?string $name = null), add(string $group, string $kind, ?string $name = null) — : static.

KEDA triggers

triggers(TriggerBuildersRegistry $builders) on ScaledObject/ScaledJob yields built triggers; fetch DI-registered builders with $builders->get(SomeTrigger::class). Every trigger extends AbstractTriggerBuilder — build(): Trigger, metricType(TargetType): static, useCachedMetrics(bool): static — and validates its required keys at build().

TriggerKey methods (all : static)
CronTriggertimezone(\DateTimeZone), start(string $cron), end(string $cron), desiredReplicas(int)
CpuTrigger / MemoryTriggerstatic withValue(int), value(int), containerName(string)
RabbitMQTriggerstatic forQueue(string), queue(string), host(string) / hostFromEnv(string), mode(Mode) (QueueLength|MessageRate), value(int|float), activationValue(int|float)
PrometheusTriggerstatic withQuery(string), serverAddress(string), threshold(int|float), activationThreshold(int|float), namespace(string), customHeaders(array), ignoreNullValues(bool), queryParameters(array), unsafeSsl(bool)
MySQLTriggerstatic withQuery(string), connectionString(string) / connectionStringFromEnv(string), query(string), queryValue(int|float), activationQueryValue(int|float)
PostgreSQLTriggerstatic withQuery(string), connection(string) / connectionFromEnv(string), query(string), targetQueryValue(int|float), activationTargetQueryValue(int|float)
RedisTriggerstatic forList(string), address(string) / addressFromEnv(string), password(string) / passwordFromEnv(string), listName(string), listLength(int), activationListLength(int), enableTLS(bool), databaseIndex(int)
RedisStreamTriggerstatic forStream(string), stream(string), consumerGroup(string), one of pendingEntriesCount(int|string) / streamLength(int|string) / lagCount(int|string) (mutually exclusive), address/host/port variants, activationLagCount(int|string)
NatsJetStreamTriggerstatic forConsumer(string $stream, string $consumer), monitoringEndpoint(string), stream(string), consumer(string), lagThreshold(int), activationLagThreshold(int), account(string) (KEDA default $G), useHttps(bool) — scales on the durable consumer's num_pending read from the NATS HTTP monitoring endpoint

Scale-target value objects: ScaleTargetReference(string $name, string $apiVersion = Deployment::API_VERSION, string $kind = Deployment::KIND, ?string $envSourceContainerName = null), WorkloadContainerReference(VersionedManifestClassReference $manifestReference, ?string $containerName = null), Fallback(int $failureThreshold, int $replicas).

ScaledJob extras: RolloutConfigurator — setStrategy(string): static, setPropagationPolicy(string): static; ScalingStrategyConfigurator — setStrategy(string): static, setCustomScalingQueueLengthDeduction(int): static, setCustomScalingRunningJobPercentage(float): static, setPendingPodConditions(array): static, setMultipleScalersCalculation(string): static.

Prometheus

NamespaceSelectorConfigurator — namespaceSelector(): any(bool): static · matchNames(array): void.

EndpointsConfigurator — endpoints() / podMetricsEndpoints(): add(): EndpointConfigurator (all : static):

  • port(string), targetPort(int|string), path(string), scheme(string), interval(string), scrapeTimeout(string)
  • basicAuth(SecretKeyReference $username, SecretKeyReference $password), bearerTokenSecret(SecretKeyReference), bearerTokenFile(string), tlsConfig(array)
  • honorLabels(bool), honorTimestamps(bool), params(array), proxyUrl(string), relabelings(array), metricRelabelings(array)

SecretKeyReference::fromSecretNameAndKey(string $secretName, string $secretKey, bool $optional): self.

RuleGroupsConfigurator — groups(): add(string $name): RuleGroupConfigurator → interval(string), partialResponseStrategy(string) — : static; rules(): GroupRulesConfigurator → add(int|string $expr): GroupRuleConfigurator → alert(string) / record(string), for(string) — : static; labels(): StringMap, annotations(): StringMap.

Collections

From klass8s/k8schema — received wherever the catalog above says so:

  • StringMap (data(), stringData(), nodeSelector(), Service::selector(), labels/annotations): add(string $name, string $value): self, addAll(array): self, get(string): string, has(string): bool, remove(string): self, all(), count(), clear()
  • StringList (args(), command(), hostnames(), target-label hooks): add(string): self, addAll(array): self, all(): array, count(), clear()

Next