Skip to content

Install with Helm

Use the Koldan chart supplied with your release to install or reconcile Koldan on Kubernetes. Keep the chart, container images, license, and documentation on the same supported release.

Before you begin

Complete the requirements and networking checks. You also need:

  • cluster access that can create the resources rendered by the chart;
  • access to the Koldan chart and every required container image;
  • DNS names and certificates for the HTTP and gRPC interfaces you will publish;
  • reachable PostgreSQL, Temporal, S3-compatible storage, and OIDC services, or an explicit decision to install the corresponding chart dependencies;
  • a valid Koldan license and the service credentials required by your deployment; and
  • storage classes and backup targets for every stateful dependency installed in the cluster.

Use the Kubernetes and Helm versions supported by the Koldan release. The common chart defaults contain placeholders and are not a deployment profile. Start from one of the supported capacity overlays, then apply the site's configuration afterward.

Prepare deployment inputs

Maintain a small, deployment-owned override file instead of copying the entire chart values.yaml. This makes release-to-release changes visible during review and avoids replacing chart-managed lists.

The following is an incomplete site-values example. Replace every placeholder and add the dependency and application configuration described in the Configure section:

web:
  replicaCount: 2
  image:
    repository: registry.example.com/koldan/backend
  imagePullSecrets:
    - name: koldan-registry
  ingress:
    enabled: true
    className: nginx
    hosts:
      - host: koldan.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: koldan-web-tls
        hosts:
          - koldan.example.com

grpc:
  replicaCount: 2
  image:
    repository: registry.example.com/koldan/backend
  imagePullSecrets:
    - name: koldan-registry
  service:
    type: LoadBalancer

workflowsWorker:
  image:
    repository: registry.example.com/koldan/backend
  imagePullSecrets:
    - name: koldan-registry

postgresql:
  install: false
minio:
  install: false
keycloak:
  install: false
temporal:
  install: false

Set nonzero replicas only for the Koldan workloads required by your licensed deployment. Configure images, pull secrets, resources, placement, and service credentials for every enabled workload. Keep the chart-managed workerPools.*.workers lists out of your override file; use capacityOverrides when concurrency must be changed.

For each optional dependency, set its install value deliberately. Disabling a bundled dependency does not configure its replacement; add the external endpoint, TLS, and credentials through the supported application configuration. If you install a dependency with the chart, review all of its persistence, authentication, resource, availability, and backup values.

Handle secrets

Before rendering the release, generate and securely deliver the mandatory koldan.security.encryption-key and koldan.api.api-keys.hmac-secret described in Configuration and secrets. A production release must not fall back to either packaged development value. Confirm the same encryption key reaches every Koldan workload connected to the database and the same HMAC secret reaches every HTTP and gRPC replica.

Create registry and serving-certificate Secrets before the Helm release when your deployment references them:

kubectl create namespace koldan

kubectl create secret docker-registry koldan-registry \
  --namespace koldan \
  --docker-server=registry.example.com \
  --docker-username="$REGISTRY_USERNAME" \
  --docker-password="$REGISTRY_PASSWORD"

kubectl create secret tls koldan-web-tls \
  --namespace koldan \
  --cert=server.crt \
  --key=server.key

Use environment variables or your deployment system's secret integration; do not put literal credentials in shell history. If your platform creates these Secrets by another controlled process, verify their names and keys instead of running the example commands.

The chart accepts the license and application configuration as Helm values. Supply file-valued inputs at deployment time so their contents do not need to be committed:

helm upgrade --install koldan ./koldan \
  --namespace koldan \
  --values operator-values.yaml \
  --set-file license=license.json \
  --set-file config=application-userdefined.yaml \
  --atomic \
  --timeout 20m

Some service credentials are also chart values. Pass them from a protected, short-lived values file or an approved Helm secret-delivery integration. Helm stores release values and rendered manifests in the cluster; restrict access to Helm release metadata and exclude it from unprotected logs and backups. See Configuration and secrets for rotation guidance.

The current chart does not expose a general existing-Secret or environment-variable interface for the two root secrets. If a platform injection layer is used, inspect the final rendered or admitted Deployment and confirm the secret references are present. Creating a Secret without wiring it into the pod does not override the application default.

Validate before installation

For an unpacked chart, build its pinned dependencies, then lint and render with the same inputs used for installation:

helm dependency build ./koldan
helm lint ./koldan \
  --values operator-values.yaml \
  --set-file license=license.json \
  --set-file config=application-userdefined.yaml

umask 077
render_dir="$(mktemp -d)"
helm template koldan ./koldan \
  --namespace koldan \
  --values operator-values.yaml \
  --set-file license=license.json \
  --set-file config=application-userdefined.yaml \
  > "$render_dir/rendered.yaml"

If you received a packaged chart with its dependencies, use that immutable package rather than rebuilding it. Inspect the rendered output in its protected temporary directory for unresolved placeholders, unintended public Services or Ingresses, incorrect image tags, missing resource limits, certificate material, PVC sizes, and dependency selections. Delete the rendered file securely according to your organization's policy because it contains Secrets.

Before proceeding, confirm that:

  • every enabled image can be pulled from the target cluster;
  • all external names resolve from both client and pod networks;
  • certificates contain the published hostnames and form a complete trusted chain;
  • PostgreSQL, Temporal, S3, and OIDC endpoints are reachable from the namespace;
  • the sum of database connection pools fits the PostgreSQL connection budget; and
  • each PVC can bind in the intended failure domain.

Install or upgrade

Run the command shown under Handle secrets. --atomic waits for Kubernetes resources and automatically reverses a failed upgrade; a failed first installation is removed. Increase the timeout only when you understand which initialization or volume operation requires it.

Record the following with the change ticket or deployment record:

  • chart version and digest;
  • application image tags or digests;
  • revision of the non-secret values file;
  • references to the secret versions used;
  • Helm release revision; and
  • the pre-deployment backup or restore point.

Do not edit chart-managed Deployments, ConfigMaps, Secrets, Services, Routes, or Ingresses directly. Helm will replace those edits on the next reconciliation.

Verify the deployment

Start with Kubernetes and Helm state:

helm status koldan --namespace koldan
kubectl get deployments,statefulsets,pods,services,ingresses,pvc \
  --namespace koldan
kubectl get events --namespace koldan --sort-by=.lastTimestamp

Every enabled workload must reach its intended replica count, every required pod must become Ready, and every required PVC must be Bound. Then verify the deployment from the networks that will use it:

  1. Validate the HTTP and gRPC DNS records and complete certificate chains.
  2. Confirm the published HTTP and gRPC interfaces accept authenticated requests.
  3. Confirm startup and readiness logs show successful connections to PostgreSQL, Temporal, object storage, and the identity provider.
  4. Exercise one representative operation for each licensed use case enabled in this deployment.
  5. Confirm metrics and logs reach the monitoring platform and no management port is publicly exposed.

Use the chart's Kubernetes readiness probes as the primary traffic signal. See Health and monitoring for endpoints and alerting guidance.

Recover from a failed deployment

If an installation fails, preserve the rendered input, events, pod descriptions, and logs in an access-controlled incident record before retrying:

kubectl get events --namespace koldan --sort-by=.lastTimestamp
kubectl describe pod --namespace koldan <pod-name>
kubectl logs --namespace koldan <pod-name> --all-containers
helm history koldan --namespace koldan

Correct the deployment inputs and run helm upgrade --install again. For a failed upgrade that was not run with --atomic, roll back only after checking database and dependency compatibility:

helm rollback koldan <known-good-revision> \
  --namespace koldan \
  --wait \
  --timeout 20m

A Helm rollback does not restore databases, object storage, PVC contents, external identity configuration, or rotated credentials. Follow the upgrade and rollback and backup and restore procedures before reversing a release that may have changed persistent state.