Helm values

Use the values.yaml packaged with the Koldan chart you are installing as the exhaustive, version-matched reference. This page explains the operator-facing value contracts and important interactions; it does not duplicate every value accepted by dependency subcharts.

Pin a chart version before preparing overrides:

helm show chart <chart-reference> --version <chart-version>
helm show values <chart-reference> --version <chart-version> > koldan-defaults.yaml

Keep a small, site-owned override file in source control and protect any secret-bearing companion file. Do not copy the full defaults into the override: copied defaults hide changes introduced by a later chart release.

Configuration precedence

The chart builds the application configuration in this order:

1. Chart defaults for the service names of bundled dependencies.
2. Chart-derived values, including the advertised HTTP endpoint when web.ingress.enabled is true.
3. Operator application YAML supplied through config.

The last layer takes precedence. Use dedicated Helm values for Kubernetes resources-images, replicas, Services, exposure, storage, pod security, and placement-and use config for the application properties that do not have a dedicated chart value.

config is rendered into a ConfigMap. Do not place credentials there when an existing-Secret interface is available. If the current configuration contract requires a credential in config, treat the values file, rendered manifests, Helm release record, ConfigMap, and their backups as sensitive.

Release-wide controls

Helm stores supplied values and rendered manifests in the release record. Access to Helm release Secrets is therefore equivalent to access to the sensitive values submitted through the chart.

Koldan workload controls

Common pod controls

The following paths are available where listed in the packaged defaults:

A change to an image, resource, security, metadata, volume, or placement value changes the pod template and triggers a Kubernetes rollout. Confirm rollout status and readiness before continuing to the next workload.

The chart exposes strategy for HTTP, gRPC, discovery, and each worker pool. The supported profiles set maxSurge: 0 and maxUnavailable: 1; changing this affects rollout capacity and availability. Koldan application PodDisruptionBudgets and generic topology-spread controls are not exposed. Use the available affinity controls, dependency-subchart placement controls, or separately reviewed Kubernetes resources where required.

API workloads

web.replicaCount and grpc.replicaCount default to 0; an operator must explicitly enable the required workloads. When an API HPA is enabled, the Deployment omits its fixed replica count and the HPA uses:

• autoscaling.minReplicas
• autoscaling.maxReplicas
• autoscaling.targetCPUUtilizationPercentage
• optional autoscaling.targetMemoryUtilizationPercentage

Resource-utilization HPAs require meaningful resource requests and a working cluster metrics pipeline.

The Hikari paths for these workloads use camel case: hikari.maximumPoolSize and hikari.minimumIdle. Include every replica and HPA maximum in the database connection budget.

Engine instances

engineSlibe.instances and engineK2.instances are lists. Each entry creates one named Deployment and private Service. Because Helm replaces lists rather than merging them, an operator override of instances must contain every instance that should remain deployed.

Although the packaged values include instances[].autoscaling, the current chart has no engine HPA template. Do not set instances[].autoscaling.enabled: true: it suppresses the Deployment replica count without creating an HPA. Use instances[].replicaCount and confirm the rendered Deployment has the intended replica count.

Workflow-worker pools and Temporal task queues

The chart creates the compute, inference, and orchestration pools under workerPools. The compute pool supports an optional resource-utilization HPA. Inference and orchestration use explicit replica counts because their safe scale depends on external-provider and coordination capacity.

Shared controls under workflowsWorker apply to all pools. A non-empty pool-local nodeSelector, tolerations, or affinity takes precedence over the shared value. Pool-specific operational controls are:

The workerPools.<pool>.workers lists, task types, and task-queue assignments are release-managed. Do not replace them in operator values and do not set spring.temporal.workers under config; either action can remove required pollers. Override capacity only for a worker name present in the same packaged pool. Helm deep-merges these overrides without applying Temporal-specific semantic validation; inspect the rendered worker ConfigMap before an upgrade.

A capacity override changes the affected pool's pod-template checksum and automatically rolls that Deployment. Wait for the rollout, then verify that its queues have pollers:

kubectl rollout status deployment/<release>-worker-<pool> -n <namespace>

Before increasing replicas or concurrency, calculate the Temporal, inference-backend, database, CPU, memory, and ephemeral-storage budgets. Use the compute HPA's maxReplicas in those budgets when autoscaling is enabled. The queue map, capacity formulas, review steps, and rollback procedure are in Temporal and Scaling and capacity.

Optional documentation workload

docs.replicaCount, docs.image.*, docs.siteUrl, docs.service.*, and docs.ingress.* control the optional documentation site. It is independent of the Koldan API workloads and defaults to zero replicas with Ingress disabled.

Services, DNS, and TLS

HTTP exposure

Use web.service.type, .port, .nodePort, and .annotations for the HTTP Service. Use exactly one chart-managed edge:

• Kubernetes Ingress: web.ingress.enabled, .className, .annotations, .hosts, and .tls.
• OpenShift Route: web.route.enabled, .host, .path, .annotations, and .tls.*.

The chart rejects a release when both the web Ingress and Route are enabled. When web Ingress is enabled, its first host and TLS presence are used to derive the advertised HTTP endpoint. Route, NodePort, and LoadBalancer exposure do not receive that derivation; set the externally reachable advertisement properties under config and verify generated links from outside the cluster.

For web.service.type: NodePort, an empty web.service.nodePort renders the chart fallback 31113.

gRPC exposure

Use grpc.service.type, .port, .nodePort, and .annotations for the gRPC Service. For OpenShift, configure grpc.route.*. For grpc.service.type: NodePort, an empty grpc.service.nodePort renders the fallback 31114.

grpc.certificate.enabled, .cert, and .key configure TLS in the Koldan gRPC pod and create a chart-managed Secret. These values are distinct from grpc.route.tls.*, which configures OpenShift Route termination and can place private-key material directly in the Route manifest. Prefer a platform-managed certificate path where available. Certificate Secret changes do not alter the pod checksum; restart gRPC pods after rotation and verify both the certificate chain and hostname.

The chart does not derive the advertised gRPC address from its Service or Route. Supply and verify it through config.

Keycloak exposure

The bundled identity provider uses its subchart Ingress values under keycloak.ingress.* or the Koldan-provided OpenShift Route values under keycloak.route.*. The chart rejects a release when both are enabled. See Identity providers for redirect URI and client requirements.

Keep management ports, engine Services, data stores, and coordination services off untrusted networks. See Network, DNS, and ports and Operational endpoints.

Persistence

Koldan update storage

web.persistence.updates.create, .class, .size, and .accessModes configure the update PVC mounted by the web workload. The current template always mounts <fullname>-updates; setting create: false requires an operator-created PVC with that exact name. The declared web.persistence.updates.name value does not change the generated or mounted claim name in the current chart.

Render this PVC before installation and validate accessModes against the target cluster. Test expansion with the selected StorageClass; Kubernetes does not support shrinking a PVC. Back up required content before uninstall or storage migration.

Bundled dependency storage

These packaged defaults are the main persistence entry points:

Storage behavior is owned by the pinned dependency chart. Inspect its version-matched defaults and rendered StatefulSets/PVCs before changing storage class, topology, replicas, or retention. A Helm rollback cannot reverse data migration or restore deleted data; follow Backup and restore and Upgrade and rollback.

Bundled and external dependencies

Each dependency is gated by an exact install value:

Setting an install switch to false prevents that subchart from rendering in the target release. On an upgrade from true to false, Helm can remove dependency resources that the release previously managed; it does not migrate their data, configure the external replacement, rewrite Koldan's default endpoint, or validate connectivity. Back up the dependency, provision and test the replacement, supply all external settings in the same controlled change, and inspect the planned manifest changes before applying them.

Elasticsearch and ZooKeeper also have application-level switches. install: false alone means “use an externally managed service”; it does not disable the Koldan integration. To run without either service, use both layers:

elasticsearch:
  install: false
zookeeper:
  install: false
legacyDependencies:
  elasticsearchEnabled: false
  zookeeperEnabled: false

Elasticsearch can be disabled when Koldan Desktop client-log ingestion/query is not required. ZooKeeper can be disabled when no Koldan-managed internal engines are deployed. Both application switches default to true for backward compatibility.

All other values nested under postgresql, temporal, minio, keycloak, zookeeper, elasticsearch, prometheus, and grafana are passed to their pinned subcharts. Use the packaged Chart.yaml and Chart.lock to identify the exact dependency version, then consult that version's values.yaml. Do not assume a value from a newer upstream chart is supported by the Koldan release.

Credential and secret exposure

Never pass sensitive values through --set; shells and CI systems can retain command arguments. Use protected values files, --set-file for supported scalar/file values, or an approved deployment secret integration. Restrict access to rendered manifests, release Secrets, diagnostic bundles, and namespace backups.

Rollout and restart matrix

Preflight and verification

Before every install or upgrade:

1. Pin the chart version and review its packaged Chart.yaml, Chart.lock, values.yaml, and release notes.
2. Confirm each dependency package matches the lock file before deployment.
3. Compare the site override with the new defaults; pay special attention to lists such as engine instances.
4. Render the exact release inputs in a protected workspace.
5. Inspect Deployments, replica counts, HPAs, Services, Ingresses or Routes, Secrets, PVCs, resource requests, service accounts, security contexts, and placement rules.
6. Apply through Install with Helm or Upgrade and rollback.
7. Verify rollout status, readiness, public HTTP and gRPC connectivity, Temporal pollers, dependency health, and licensed operation.

helm lint <unpacked-chart-directory> -f operator-values.yaml
helm template <release> <chart-reference> \
  --version <chart-version> \
  --namespace <namespace> \
  -f operator-values.yaml > rendered.yaml

helm get values <release> -n <namespace> --all
helm get manifest <release> -n <namespace>
kubectl get deploy,statefulset,hpa,svc,ingress,pvc -n <namespace>

Rendering proves only that Helm can produce manifests. Complete the task-specific verification in the linked Operations guides, and use Troubleshooting if a rollout stalls or a dependency remains unhealthy.