Install on IBM Cloud (IKS)

This page covers only the IBM Cloud specifics. The canonical flow — namespaces, the license and application Secrets, the values file, the Helm release, and the migrations — lives in Install on Kubernetes (Helm), and every step reference below points back to it. Work through System Requirements first; here you provision an IKS cluster and its IBM Cloud backing services, then layer a small values-ibm.yaml onto the canonical values file.

Before you begin

In addition to the canonical prerequisites, have ready:

• An IBM Cloud account with sufficient VPC, IKS, Databases, and Object Storage quota.
• The ibmcloud CLI with the kubernetes-service, cos, and infrastructure-service plugins installed (ibmcloud plugin install ...).
• cluster-admin on the target cluster and a targeted resource group (ibmcloud target -g <group>).

Everything below uses dynamiq.example.com as the domain and the us-south region; replace both throughout.

Provision the cluster

Create an IKS cluster on VPC Gen2 running a supported Kubernetes version (1.32 or newer). At minimum you need a VPC, a subnet with a public gateway, and a worker pool:

ibmcloud ks cluster create vpc-gen2 \
  --name dynamiq \
  --zone us-south-1 \
  --version 1.32 \
  --vpc-id <vpc-id> \
  --subnet-id <subnet-id> \
  --flavor bx2.4x16 \
  --workers 3

Size the worker pool for the sizing baseline plus your real workload; see the IBM Cloud Kubernetes Service docs for VPC and worker-pool detail. Then install NATS with JetStream as usual.

Databases for PostgreSQL

Provision an IBM Cloud Databases for PostgreSQL deployment at version 16, then create the three logical databases Dynamiq needs — nexus, synapse, and catalyst. One deployment with three databases is fine.

Create a service credential and read the host, port, database, username, and password from it, then map them into the three *-db Secrets — nexus-db, synapse-db, and catalyst-db — exactly as in install Step 4.

Cloud Object Storage

Dynamiq's storage service is fixed to s3, but IBM Cloud Object Storage (COS) is S3-compatible, so you point the S3 client at a COS regional endpoint and authenticate with HMAC keys. This is exactly the "S3-compatible endpoint" (Pattern B) case from the Configuration Reference — the section below is a worked example of it.

Instance, bucket, HMAC keys. Create a COS instance and a bucket, then a service credential with HMAC enabled:

ibmcloud resource service-key-create dynamiq-cos-hmac Writer \
  --instance-name dynamiq-cos \
  --parameters '{"HMAC":true}'

The credential's cos_hmac_keys.access_key_id and cos_hmac_keys.secret_access_key are your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Endpoint. Use the bucket's public regional S3 endpoint, which follows the pattern s3.<region>.cloud-object-storage.appdomain.cloud — for us-south, https://s3.us-south.cloud-object-storage.appdomain.cloud. (A private worker-to-COS path uses the s3.direct.<region>... form.)

Wiring it up. The endpoint and region are non-secret and go in each backend's configMapData (shown in Provider values below). The two HMAC keys are secrets: add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to each service's pre-created Secret — the nexus, synapse, catalyst, and runtime Secrets from install Step 4, extended with those two keys. Keep the canonical STORAGE_S3_BUCKET pointed at your COS bucket name.

Ingress and certificates

An IKS cluster ships a managed Application Load Balancer (ALB) and an IBM-provided ingress subdomain. For a quick internal validation you can expose the services under that subdomain, but production installs need your own domain with wildcard TLS across the five synapse zones.

Keep the canonical className: nginx ingress and issue the certificate with cert-manager using a DNS-01 solver against your DNS provider (IBM Cloud Internet Services / CIS, or wherever the zone lives), because wildcard certificates require DNS-01. Point DNS records for api., app., and the five wildcard zones at the ALB hostname.

Provider values

Save this as values-ibm.yaml. It is the entire IBM Cloud delta: it adds the COS endpoint and region to each backend's ConfigMap. The HMAC keys are not here — they go in the per-service Secrets as described above. Everything else comes from the canonical values.yaml in install Step 5.

nexus:
  configMapData:
    AWS_ENDPOINT_URL: https://s3.us-south.cloud-object-storage.appdomain.cloud
    AWS_REGION: us-south

synapse:
  configMapData:
    AWS_ENDPOINT_URL: https://s3.us-south.cloud-object-storage.appdomain.cloud
    AWS_REGION: us-south

catalyst:
  configMapData:
    AWS_ENDPOINT_URL: https://s3.us-south.cloud-object-storage.appdomain.cloud
    AWS_DEFAULT_REGION: us-south

runtime:
  configMapData:
    AWS_ENDPOINT_URL: https://s3.us-south.cloud-object-storage.appdomain.cloud
    AWS_REGION: us-south

These configMapData keys merge into the canonical ones (they don't replace STORAGE_SERVICE, STORAGE_S3_BUCKET, or NATS_URL).

Install and verify

Install with both files — the canonical values plus the IBM delta. Later files win on any key collision, so the storage keys layer cleanly onto the canonical release:

helm upgrade --install dynamiq \
  oci://registry-1.docker.io/dynamiqai/dynamiq \
  --version 0.39.0 \
  --namespace dynamiq \
  -f values.yaml \
  -f values-ibm.yaml

(Authenticate to the registry first, exactly as in install Step 6.) The post-install migration hook then runs automatically; watch it and verify the platform per install Step 7 and Step 8.

Next steps