Skip to content

Requirements and dependencies

Complete this assessment before creating an operator values file. The result should identify who owns each dependency, how it is secured and recovered, and what capacity it must provide.

Collect the deployment inputs

Record the following for each environment:

  • Koldan release, chart package, container image locations, and registry credentials.
  • Cluster type, namespace, ingress or Route implementation, storage classes, and applicable security policies.
  • Public HTTP and gRPC hostnames, DNS ownership, certificate issuer, and TLS termination points.
  • Endpoints, credentials, CA chains, availability targets, and recovery objectives for every external dependency.
  • Expected concurrent and batch demand, maximum object size, data-retention policy, and growth forecast.
  • Monitoring, log collection, alert routing, backup, restore, change-management, and incident-response owners.

Use release-matched artifacts throughout the deployment. Validate supported platform versions against the release package and your Koldan support agreement rather than assuming that values from another release are compatible.

Cluster prerequisites

The deployment team needs:

  • A Kubernetes cluster, or an OpenShift cluster with access to the Route API.
  • Helm plus kubectl; OpenShift operators also need oc for platform-specific checks.
  • A dedicated namespace and permission to create the resources rendered by the selected chart configuration. These can include Deployments, Services, ConfigMaps, Secrets, ServiceAccounts, Ingresses or Routes, HorizontalPodAutoscalers, PersistentVolumeClaims, and dependency resources.
  • Access from cluster nodes to every selected container registry, including an image-pull Secret where anonymous pulls are not allowed.
  • A default or explicitly selected storage class for each persistent workload.
  • Cluster DNS and network paths to external services and public identity endpoints.
  • A Koldan license delivered through an approved secret-management process.

Render the chart with the intended values before requesting access approval. The rendered manifest is the most reliable inventory of resources and permissions for that environment.

Platform policy checks

Confirm these items with the cluster owner before installation:

  • Pod security settings permit the selected images and volume mounts under the namespace's assigned user and group IDs.
  • The service account settings meet organizational policy. The chart can create a service account and controls token mounting through serviceAccount.*.
  • Admission policies accept the image registries, resource limits, labels, annotations, and security contexts used by the release.
  • Resource quotas cover both Koldan workloads and any bundled dependencies.
  • NetworkPolicy allows the flows listed in Network, DNS, and ports.

Dependency decisions

For every service, choose either the bundled chart dependency or an independently operated endpoint. Do not enable a bundled dependency while also directing Koldan to an external instance of the same service unless that combination has been deliberately reviewed.

Service Provisioning decision Production acceptance criteria
PostgreSQL Set postgresql.install for the bundled subchart, or configure an external datasource. Durable storage, TLS where required, a Koldan database and least-privileged login, the PostgreSQL vector extension available to the database, connection headroom, monitored backups, and a tested restore.
Temporal Set temporal.install, or configure an external frontend endpoint. Reachable frontend, required namespace, retention policy, durable SQL persistence where self-managed, authentication and TLS where required, and monitored service health.
S3-compatible storage Set minio.install, or configure an external S3 endpoint. Existing bucket, least-privileged access, correct endpoint/region/addressing mode, encryption policy, capacity monitoring, lifecycle policy, and tested recovery or replication.
Identity provider Set keycloak.install, or configure a compatible external OIDC provider. Stable issuer and JWKS endpoints, required client registrations and redirect URIs, service credentials, trusted TLS, restricted administration, and recovery of provider configuration.
Search and coordination services Review elasticsearch.install, zookeeper.install, and legacyDependencies.*Enabled. They may both be omitted when Koldan Desktop and Koldan-managed internal engines are not used. When enabled, private endpoints, durable storage where applicable, health monitoring, and backup or rebuild procedures appropriate to the service.
Observability Review prometheus.install and grafana.install, or integrate existing services. Metrics scraping, controlled dashboard access, retained telemetry, and alerts routed to an owned response process.

The chart defaults are a starting point, not a production availability or durability design. When a bundled dependency is enabled, the Koldan operations team owns its security, upgrades, persistence, monitoring, backup, and recovery.

See the configuration guides for PostgreSQL, Temporal, S3-compatible storage, and identity providers.

Storage planning

Inventory every PersistentVolumeClaim produced by the rendered chart and document:

  • Storage class, access mode, requested size, expansion support, volume binding mode, topology constraints, and reclaim policy.
  • Expected daily growth, warning thresholds, expansion procedure, and the owner who approves capacity changes.
  • Snapshot or backup mechanism, retention, encryption, off-cluster copy, and restore procedure.
  • Scheduling behavior when replicas move between zones or nodes.

The chart can create persistent volumes for the HTTP workload's update data and for enabled stateful dependencies. A bound volume is not a backup. Test recovery from the backup system independently of the original cluster.

Capacity and availability planning

Before setting replicas and resources:

  1. Establish expected peak HTTP requests, concurrent gRPC sessions, file-ingestion rate, and background demand.
  2. Obtain the capacity limits of external processing services and reserve headroom for online traffic and failure recovery.
  3. Set CPU, memory, and ephemeral-storage requests and limits for every enabled workload. Do not leave production sizing dependent on chart placeholders.
  4. Calculate the PostgreSQL connection budget across every replica, Temporal, the identity provider, operational tools, and administrative reserve.
  5. Decide which workloads require multiple replicas, topology spread, anti-affinity, disruption protection, or dedicated nodes.
  6. Define measurable scale-up and scale-down triggers, then test them with representative traffic.

Use Scaling and capacity for the workload-specific controls and connection-budget calculation.

Security and secrets readiness

  • Choose a source of truth for credentials, private keys, license data, and provider tokens. Restrict read access and enable audit logging.
  • Before the first production startup, generate a site-specific koldan.security.encryption-key and koldan.api.api-keys.hmac-secret. Do not use the packaged development values. Record their consumers and recovery owners.
  • Decide how the deployment pipeline supplies secrets without committing them to source control. Restrict and minimize retention of rendered manifests and CI artifacts that contain sensitive values.
  • Issue certificates with Subject Alternative Names for every client-visible hostname and assemble private CA bundles for outbound dependencies.
  • Define rotation procedures for database, OIDC, S3, registry, provider, TLS, and license material. Account for the workload restart needed to consume updated mounted data.
  • Review Kubernetes Secret encryption, RBAC, service-account token mounting, egress control, and administrative access to dependency consoles.

Continue with Configuration and secrets and TLS and custom CAs.

Ready-to-install checklist

Installation can proceed when:

  • Release artifacts are accessible and their versions are recorded.
  • Namespace permissions and platform policies accept the rendered resources.
  • Every placeholder in the operator values file has an assigned owner and final value.
  • The encryption key and API-key HMAC secret are non-default, recoverable from the approved secret store, and delivered consistently to every consuming replica.
  • External dependencies are provisioned, resolvable, reachable, and backed up.
  • Storage classes, sizes, access modes, and recovery procedures are approved.
  • Public and private DNS records, certificates, load balancers, firewall rules, and NetworkPolicies are prepared.
  • Initial resource sizing and the PostgreSQL connection budget have been reviewed.
  • Monitoring, alerting, backup, restore, and rollback responsibilities are assigned.

Next, finalize Network, DNS, and ports, then install with Helm.