Deploy on Kubernetes

Vaks PM · Deployment on an existing cluster · Kubernetes · June 2026

Overview

Vaks PM is delivered as a small set of container images and is designed to run entirely on infrastructure the organization controls, with no mandatory dependency on any external online service. The only optional outbound connections are an email relay (for notifications) and a corporate identity provider (for single sign-on).

This guide covers the Kubernetes installation path, which is intended for organizations that already operate a Kubernetes cluster. The other supported path, a guided installer that provisions a Docker Swarm cluster from scratch over SSH, is documented separately in Deploy on Docker Swarm. Both paths run the identical application from the identical images; the choice is driven by existing operational tooling, not by feature differences.

Installation uses Helm, the Kubernetes package manager. A ready-to-use chart (Helm package) ships in the repository at deploy/helm/vaks-pm. The chart deploys all of the stateless application services and, optionally, the three backing dependencies (database, cache, object storage) either inside the cluster (for evaluation) or by pointing at existing external services (the production recommendation).

Glossary

Acronyms and terms used throughout this guide, defined once here for reference.

Deployed architecture

Whichever options are chosen, the running system is the same set of services. The application is stateless where it can be (the api, web and worker services hold no local data and scale horizontally); all durable state lives in three backing stores: PostgreSQL, Redis and the S3 object store.

A schema-migration job (a Helm hook named vaks-pm-dbpush) runs automatically on every install and upgrade, before the services start, to synchronize the database structure. No manual migration step is required.

Network routing (Ingress)

The chart generates a single Ingress that splits traffic for one host name by request path:

Tenancy modes

The chart supports two tenancy models, selected by tenancy.mode. This is independent of the single-vs-HA decision in the next section.

Prerequisites & initial state

The lists below describe the expected starting point before any install command is run. The expected initial state is a working Kubernetes cluster on which the administrator has full rights over at least one namespace.

Cluster and workstation

Network and certificates

• A public host name for the instance (for example pm.example.com) and the authority to create a DNS record pointing it to the Ingress controller's entry point.
• For production, a TLS certificate for that host name, supplied as an existing Kubernetes Secret or issued automatically by a certificate manager (for example cert-manager).
• Only the standard HTTPS port (443) needs to be reachable from clients; everything else stays inside the cluster.

Optional, configurable after install

• An outbound email relay (SMTP) for notifications.
• A corporate identity provider (for example Microsoft Entra ID) only if single sign-on is required.
• For production: existing PostgreSQL, Redis and S3 services. For evaluation only, the chart can bundle all three in-cluster.

Single vs HA · choose the topology

The chart can install in two very different shapes. This choice is independent of the tenancy mode and is the most consequential decision for a production deployment. Read the table carefully: a single install is suitable only for evaluation.

Sizing

The values below are the chart's default requests (reservations), indicative for a production deployment serving roughly 200 users. Adjust to observed load. The unit m is the processor milli-core (1000 m = 1 vCPU); Mi and Gi are mebibytes and gibibytes of memory.

Images · mirror and pull credentials

Three application images are required: vaks-pm/api, vaks-pm/web and vaks-pm/worker. Mirror them into a registry the cluster can reach, then note that registry's host address (for example registry.example.com). Set the host as image.registry; the chart appends the repository (vaks-pm/api and so on), giving registry.example.com/vaks-pm/api. Do not repeat the vaks-pm segment in image.registry.

If the registry stores the images under different names, override image.api.repository, image.web.repository and image.worker.repository. The three images share one tag (image.tag, defaulting to the chart's appVersion).

Create the namespace and, for a private registry, a pull Secret to reference later via imagePullSecrets:

kubectl create namespace vaks-pm

# Private registry only:
kubectl -n vaks-pm create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=<user> \
  --docker-password=<password>

Secrets

The application requires four mandatory secrets. Generate them with strong random values:

openssl rand -hex 32      # jwtAccessSecret
openssl rand -hex 32      # jwtRefreshSecret
openssl rand -base64 32   # mfaEncryptionKey
openssl rand -hex 32      # workerApiToken

Values files

The configuration lives in a values file passed with -f. Two complete examples follow: Scenario A for production (external dependencies, HA replicas, anti-affinity) and Scenario B for evaluation (bundled dependencies, single replicas).

Scenario A · Production (external PostgreSQL / Redis / S3, HA)

The organization's own Kubernetes, managed database and cache, an existing S3 service, and replicas spread across nodes by anti-affinity. Single-organization (dedicated) mode.

image:
  registry: registry.example.com   # host only; chart appends vaks-pm/api|web|worker
  tag: "1.0.0"
imagePullSecrets:
  - name: regcred

publicBaseUrl: https://pm.example.com
tenancy:
  mode: dedicated

# --- HA replicas ---
api:
  replicaCount: 3
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            topologyKey: kubernetes.io/hostname
            labelSelector:
              matchLabels: { app.kubernetes.io/component: api }
web:
  replicaCount: 2
worker:
  replicaCount: 3

# --- Database: managed / external ---
postgresql:
  enabled: false
externalDatabase:
  url: "postgresql://vakspm:<password>@pg.internal.example.com:5432/vakspm?schema=public"

# --- Cache: managed / external ---
redis:
  enabled: false
externalRedis:
  url: "redis://redis.internal.example.com:6379"

# --- Object storage: existing S3 service (e.g. MinIO / Ceph / AWS) ---
minio:
  enabled: false
s3:
  external:
    endpoint: "https://s3.internal.example.com:9000"
    region: us-east-1
    useSSL: true
    forcePathStyle: true        # true for MinIO/Ceph/Garage
    accessKey: "<access-key>"
    secretKey: "<secret-key>"   # prefer secrets.existingSecret
    bucketPrefix: ""
    createBuckets: true

ingress:
  enabled: true
  className: nginx
  host: pm.example.com
  tls:
    enabled: true
    secretName: pm-example-tls

# Prefer secrets.existingSecret in production (see Secrets section).
secrets:
  jwtAccessSecret: "<openssl rand -hex 32>"
  jwtRefreshSecret: "<openssl rand -hex 32>"
  mfaEncryptionKey: "<openssl rand -base64 32>"
  workerApiToken: "<openssl rand -hex 32>"

Scenario B · Evaluation (fully bundled, single replicas)

All dependencies inside the cluster, suitable for a quick or disconnected setup. Replicas reduced to 1.

image:
  registry: registry.example.com   # host only; chart appends vaks-pm/api|web|worker
  tag: "1.0.0"

publicBaseUrl: https://pm.example.test
tenancy:
  mode: dedicated

api:    { replicaCount: 1 }
web:    { replicaCount: 1 }
worker: { replicaCount: 1 }

postgresql: { enabled: true }
redis:      { enabled: true }
minio:      { enabled: true }

ingress:
  enabled: true
  className: nginx
  host: pm.example.test
  tls: { enabled: false }

# Creates the demo organization and administrator account.
migrations:
  seedDemo: true

secrets:
  jwtAccessSecret: "<openssl rand -hex 32>"
  jwtRefreshSecret: "<openssl rand -hex 32>"
  mfaEncryptionKey: "<openssl rand -base64 32>"
  workerApiToken: "<openssl rand -hex 32>"

S3 storage

Vaks PM stores binary files (task attachments, branding logos, document templates, project charters and compressed audit archives) in an S3-compatible object store. Any compliant implementation works (Amazon S3, MinIO, Ceph RGW, Garage, NetApp StorageGRID, Wasabi…). The chart translates the storage section into environment variables; only the parameters below change between providers.

The application uses five buckets (names shown before the prefix is applied): charter-blobs, document-templates, vaks-pm-attachments, vaks-pm-branding, vaks-pm-audit-archive. When createBuckets is false, create these five (prefixed) buckets beforehand and grant the service account read, write, delete and list rights on them. At start-up the API logs an S3 backend: … line summarizing the configuration in effect.

Helm install

Before installing, validate the chart rendering against the values file:

helm lint ./deploy/helm/vaks-pm -f values-production.yaml

helm template vaks-pm ./deploy/helm/vaks-pm -f values-production.yaml \
  | kubectl apply --dry-run=client -f -

Then install. The --timeout gives the schema-migration job time to complete:

helm install vaks-pm ./deploy/helm/vaks-pm \
  -n vaks-pm --create-namespace \
  -f values-production.yaml \
  --timeout 5m

Wait for the pods to become ready:

kubectl -n vaks-pm get pods
kubectl -n vaks-pm rollout status deploy/vaks-pm-api

Verification

Watch the schema-migration hook while it runs (it auto-deletes on success), then validate each network path. Replace pm.example.com with the configured host name.

# Schema-migration job. It is a Helm hook DELETED automatically on success,
# so watch it while it runs rather than after:
kubectl -n vaks-pm get pods -w        # the vaks-pm-dbpush-* pod should reach Completed
# If it FAILS, the job is kept; read its logs:
kubectl -n vaks-pm logs job/vaks-pm-dbpush

# API readiness (expected response: {"status":"ok","db":"up"})
curl -s https://pm.example.com/api/v1/health/ready

# API liveness
curl -s https://pm.example.com/api/v1/health/live

# Home page (expected: HTTP 200)
curl -s -o /dev/null -w "%{http_code}\n" https://pm.example.com/

Encryption on Kubernetes · overview

A complete deployment has three independent encryption concerns. They are orthogonal (enabling one does not enable the others), and only the first two are addressed by the quick-start values.

• Field-level secrets. Application secrets (SMTP password, multi-factor seeds, single-sign-on client secrets) are encrypted inside the database by the application itself, using envelope encryption (a per-tenant DEK wrapped by a KEK). On by default.
• In transit. Network traffic: browser↔cluster (the external edge), the internal hops to the dependencies (database, cache, object storage), and pod-to-pod traffic.
• At rest. Data on disk: the dependency volumes (PVCs) and the Kubernetes Secrets (which hold the KEK keyring, signing keys and credentials) in the cluster datastore.

Field-level secrets (envelope encryption)

Sensitive fields are encrypted with a per-tenant DEK that is wrapped by a KEK. This is built in and works out of the box: the KEK defaults to MFA_ENCRYPTION_KEY (registered under the ref env), a path that always works for both encrypt and decrypt. Nothing extra is required for a baseline.

Field-level encryption protects the listed secrets, not the bulk business data (projects, tasks, users). Protecting the full dataset at rest is the job of the volume-encryption layer in At rest.

Custody options (crypto.*)

Two custody models exist; both are portable across the Swarm and Kubernetes paths because the application only reads a mounted keyring directory (crypto.keysDir, default /etc/vaks/keys) and does not care who mounted it.

• Local key ring. Mount a versioned keyring of files named kek_v<N> (base64, 32 bytes) and point crypto.activeKek at the version new writes should use; older keys stay usable to decrypt legacy blobs. Provide the keys inline via crypto.keks (the chart builds a Secret), or, the recommended choice for production, reference a Secret managed out-of-band with crypto.existingSecret, mounted read-only into api/worker/controlplane. This enables KEK rotation without re-encrypting data.
• External KMS / HSM custody. Set crypto.provider to kms or hsm to move KEK wrap/unwrap off-box, so the master key never resides in the cluster. For KMS, fill crypto.kms.keyId / region / endpoint (prefer workload identity over static keys; otherwise a Secret via crypto.kms.existingSecret). For an on-premise HSM, deploy the PKCS#11 key-broker sidecar and set crypto.hsm.brokerUrl / keyLabel with the shared token in crypto.hsm.existingSecret. Only the KEK moves off-box; the per-tenant DEK stays local. Migration is online: deploy with the provider set, then re-wrap via Admin → Encryption keys.

In transit

External edge (Ingress)

Terminate HTTPS at the Ingress by supplying a certificate as an existing Kubernetes Secret, or by letting a certificate manager issue one:

ingress:
  enabled: true
  className: nginx          # or traefik
  host: pm.example.com
  tls:
    enabled: true
    secretName: pm-example-tls  # cert-manager or supplied

Internal services (database, cache, object storage)

These hops carry the application's data to its dependencies and are plaintext unless enabled. Each is a separate setting:

Pod-to-pod network

The simplest way to encrypt all in-cluster traffic at once, including the database, cache, object-storage and any KMS/HSM-broker hops, is to encrypt the pod network itself rather than each service individually:

• Encrypted CNI. For example a WireGuard backend (such as k3s --flannel-backend=wireguard-native), or Cilium / Calico with encryption enabled. This encrypts node-to-node pod traffic without any change to the application.
• Service-mesh mTLS. A mesh (Istio, Linkerd) enforces mutual TLS between pods.

At rest

Data volumes (PVCs)

The database, cache and object-storage volumes hold the full dataset (not just the field-level secrets). Encrypt them with an encrypted StorageClass; only the volumes are encrypted, never the node OS:

postgresql:
  persistence:
    storageClass: gp3-encrypted   # a cloud-KMS or CSI-encrypted class
# do the same for redis.persistence.storageClass / minio.persistence.storageClass,
# or use managed services with provider-side encryption

Options: a cloud provider's encrypted block-storage class (KMS-backed), a Container Storage Interface (CSI) driver with encryption, or nodes whose disks are encrypted (for example LUKS, Linux Unified Key Setup). When the dependencies are external/managed, use the provider's encryption (RDS encryption, S3 server-side encryption, and so on) instead.

Kubernetes Secrets

The KEK keyring, the signing keys and the database/storage credentials live in Kubernetes Secrets. A Secret is only base64-encoded in the cluster datastore, not encrypted by default. Protect it with one of:

• Datastore encryption at rest. An EncryptionConfiguration with an aescbc or (better) a kms provider on the API server. On k3s this is the built-in k3s secrets-encrypt enable, which requires the embedded etcd datastore (install with --cluster-init; it has no effect on the default SQLite datastore).
• External secret store. The External Secrets Operator, a CSI secrets driver, or a sealed-Secret controller, so the key material is sourced from a vault rather than stored in the datastore. This pairs with secrets.existingSecret and crypto.existingSecret.
• Off-box KEK custody. Moving the KEK to a KMS/HSM (see Field-level secrets) means the most sensitive key is never in a Kubernetes Secret at all.

Encrypted HA example

This consolidated values file ties the production HA shape together with every application-level encryption control enabled. It still relies on cluster-level controls (encrypted CNI, datastore Secret encryption) that are configured outside Helm, as noted in the comments.

image:
  registry: registry.example.com
  tag: "1.0.0"
imagePullSecrets:
  - name: regcred

publicBaseUrl: https://pm.example.com
tenancy:
  mode: dedicated

# --- HA replicas + anti-affinity ---
api:    { replicaCount: 3 }
web:    { replicaCount: 2 }
worker: { replicaCount: 3 }

# --- External, managed, TLS-terminating dependencies ---
postgresql:
  enabled: false
externalDatabase:
  url: "postgresql://vakspm:<password>@pg.internal.example.com:5432/vakspm?schema=public&sslmode=require"
redis:
  enabled: false
externalRedis:
  url: "rediss://redis.internal.example.com:6379"   # rediss:// = TLS
minio:
  enabled: false
s3:
  external:
    endpoint: "https://s3.internal.example.com:9000"
    region: us-east-1
    useSSL: true                # TLS to object storage
    forcePathStyle: true
    accessKey: "<access-key>"
    secretKey: "<secret-key>"
    createBuckets: true

# --- In-transit TLS to PostgreSQL with CA verification ---
tls:
  postgres: true                # PG_TLS=1
  postgresCaSecret: pg-ca       # Secret holding ca.crt
  postgresVerifyMode: verify-full

# --- External edge TLS ---
ingress:
  enabled: true
  className: nginx
  host: pm.example.com
  tls:
    enabled: true
    secretName: pm-example-tls

# --- Field-level KEK: versioned keyring with rotation ---
crypto:
  existingSecret: vaks-pm-keyring   # holds kek_v1, kek_v2, …
  activeKek: v2                     # new writes wrap with kek_v2

# --- All sensitive values from an out-of-band Secret ---
secrets:
  existingSecret: vaks-pm-secrets

# Cluster-level controls configured OUTSIDE Helm (plan before building):
#   * encrypted CNI (e.g. WireGuard) for pod-to-pod traffic
#   * datastore Secret encryption (EncryptionConfiguration / k3s secrets-encrypt)
#   * encrypted StorageClass for any in-cluster PVCs (none here: all deps external)

Upgrade

An upgrade points the release at a newer image tag and re-applies the chart. The customer never builds or edits code — only the tag moves. Because the application services are stateless and run several replicas, Kubernetes performs a rolling update (new pods must pass their readiness probe before old pods are retired), so the operation is zero-downtime. The database schema travels with the image and is applied by a Helm hook Job, so there is no separate SQL migration pack to run in the routine case.

1 · Mirror the new image tag

The chart pulls the three images (api, web, worker) from the registry named in image.registry at the tag in image.tag. Mirror the new version into that registry first (see Images · mirror and pull credentials), so every node can pull it. Pin a unique version tag (e.g. 1.4.0) rather than a moving tag, so the rolled-out revision is reproducible.

2 · Run the upgrade

Set the new tag and re-apply the same values file. The --timeout gives the schema-migration hook room to complete before Helm rolls the app pods:

helm upgrade vaks-pm ./deploy/helm/vaks-pm \
  -n vaks-pm -f values-production.yaml \
  --set image.tag=1.4.0 --timeout 5m

kubectl -n vaks-pm rollout status deploy/vaks-pm-api      # new pods Ready
kubectl -n vaks-pm rollout status deploy/vaks-pm-web

Helm runs the vaks-pm-dbpush hook (below) as a pre-upgrade step, so the schema is aligned before the new api pods start. If the hook fails, the upgrade stops and the running pods keep serving the old version.

3 · Database schema

The schema travels in the image. The chart ships a Helm hook Job, vaks-pm-dbpush, that runs prisma db push on install and upgrade (gated by migrations.enabled, on by default). It auto-deletes on success and is retained on failure for inspection — so for a routine upgrade there is no manual migration step.

# watch the hook while it runs (it is deleted on success):
kubectl -n vaks-pm get pods -w             # vaks-pm-dbpush-* should reach Completed
kubectl -n vaks-pm logs job/vaks-pm-dbpush # only present if it FAILED

kubectl -n vaks-pm run dbpush --rm -it --restart=Never \
  --image=<registry>/vaks-pm/api:1.4.0 \
  --env DATABASE_URL='postgresql://<owner>:…@<host>:5432/<db>' \
  -- sh -c 'cd /app/api && npx prisma db push --accept-data-loss'

4 · Rollback

To revert the workloads to the previous release (image tag, values, and manifests):

helm history vaks-pm -n vaks-pm            # find the previous good revision
helm rollback vaks-pm <revision> -n vaks-pm --timeout 5m

5 · Verify after the upgrade

kubectl -n vaks-pm get pods                       # all Running on the new image
curl -s https://pm.example.com/api/v1/health/ready   # {"status":"ok","db":"up"}

All app pods Running on the new tag, the migration hook Completed, sign-in works, and an attachment upload succeeds (exercises the S3 path). Adding an organization (pooled mode) is not an upgrade: provision a new tenant with its own database and host name; existing tenants are undisturbed.

Uninstall

helm uninstall vaks-pm -n vaks-pm

Parameter reference

The most-used parameters. See deploy/helm/vaks-pm/values.yaml for the exhaustive, commented list.

Troubleshooting

Related: The product · Architecture · Deploy on Docker Swarm · Security · Operations · Demo