Helm

This is the configuration reference for the Scrydon Helm chart. It documents a condensed install and the operationally significant value groups — what each key does, why you'd change it, and how. If you just want the fastest path to a running cluster, start from your Location page (On-Premise, Azure (AKS), Air-Gapped) and come back here for the options.

For an air-gapped cluster (no outbound internet), use Air-Gapped Deployment instead — the same chart ships inside a Zarf bundle.

How configuration works

Three layers, lowest to highest precedence:

1. Chart defaults — the chart ships sane production defaults for everything. The authoritative list is the chart's own values.yaml (see Inspect the chart locally).
2. Your values.customer.yaml — the file you pass with -f. Override only what you need; everything else inherits the default.
3. --set flags — highest precedence, useful for resolving secrets at install time from a secret manager.

helm install scrydon oci://scrydonops.azurecr.io/scrydon/charts/scrydon \
  --version <version> -n scrydon-platform \
  -f values.customer.yaml \
  --set apiTable.secrets.STARROCKS_PASSWORD="$(vault kv get -field=password kv/scrydon/starrocks)"

Secrets live in your values file. values.customer.yaml and helm get values <release> both echo every user-supplied value. Keep the file out of source control, or manage it via Sealed Secrets / SOPS / External Secrets Operator, and restrict cluster RBAC on the release Secret.

Inspect the chart locally

The chart is an OCI artifact in scrydonops.azurecr.io — there is no public Git mirror. Pull it to read every template and the full default values.yaml:

helm pull oci://scrydonops.azurecr.io/scrydon/charts/scrydon \
  --version <version> --untar
less scrydon/values.yaml   # the authoritative default for every key below

Validate your configuration

The chart ships a values schema (values.schema.json). It rejects unknown or mistyped keys at the top level and in high-risk strict groups such as routing, ingress, license, namespaces, Pod Security, and NetworkPolicy. Some application blocks — including nested runtimePlane keys in current charts — remain permissive, so schema validation is necessary but not sufficient. A typo like routing.mdoe fails immediately:

Error: values don't meet the specifications of the schema(s) in the following chart(s):
scrydon:
- routing: Additional property mdoe is not allowed

Before an install or upgrade, run a preflight against your values and your cluster version:

# 1. Schema + lint — catches typo'd keys and structural mistakes
helm lint ./scrydon -f your-values.yaml

# 2. Render and validate against your Kubernetes version
#    (kubeconform: https://github.com/yannh/kubeconform)
helm template scrydon ./scrydon -f your-values.yaml \
  | kubeconform --strict --ignore-missing-schemas \
      --kubernetes-version "$(kubectl version -o json | jq -r '.serverVersion.gitVersion' | tr -d v)"

# 3. Dry-run the install against the live cluster (server-side validation)
helm install scrydon ./scrydon -f your-values.yaml --dry-run=server

The chart requires Kubernetes 1.28 or later (kubeVersion: ">=1.28.0-0") — helm install refuses older clusters with a clear error rather than failing mid-deploy.

Quick install

The minimum to a running cluster. Each step is expanded with environment-specific notes on the Location pages.

# 1. Log in to the registry (username = ACR token name from your account team)
helm registry login scrydonops.azurecr.io --username <acr-token-name>

# 2. Create the release namespace + an image-pull secret in it.
#    The chart defaults every service to scrydon-platform; split namespaces
#    are opt-in via namespaces.* (create the secret in each one you target).
kubectl create namespace scrydon-platform 2>/dev/null || true
kubectl create secret docker-registry scrydon-registry --namespace scrydon-platform \
  --docker-server=scrydonops.azurecr.io \
  --docker-username=<acr-token-name> --docker-password=<acr-token-password>

# 3. values.customer.yaml — the entire minimal install.
global:
  imageRegistry: scrydonops.azurecr.io   # pull images from the ACR you logged into
  imagePullSecrets:
    - scrydon-registry
  storageClass: <your-storage-class>     # cloud default class name, or your on-prem provisioner

routing:
  host: app.example.com                  # the hostname your DNS points at

ingress:
  tls:
    enabled: true                        # browser reaches Scrydon over HTTPS — see Ingress below

infra:
  db:
    credentials:
      password: REPLACE-WITH-DB-PASSWORD          # openssl rand -hex 16
auth:
  secrets:
    AUTH_SECRET: REPLACE-WITH-AUTH-SECRET         # openssl rand -hex 32
apiTable:
  secrets:
    STARROCKS_PASSWORD: REPLACE-WITH-STARROCKS-PW # openssl rand -hex 24

# 4. Install
helm install scrydon oci://scrydonops.azurecr.io/scrydon/charts/scrydon \
  --version <version> --namespace scrydon-platform \
  -f values.customer.yaml --wait

Run the setup wizard

Open https://app.example.com/platform/setup (or /setup if you mounted platform at the root). Five steps:

Pre-seed the license

Skip the wizard's license step by injecting the bundle on first install. The values are read once to seed the DB, after which the license lives in platform_config and is managed in the UI:

auth:
  secrets:
    AUTH_SECRET: REPLACE-WITH-AUTH-SECRET
    LICENSE: |                              # the bundle's `jwt` field (one line)
      eyJhbGciOiJSUzI1NiIs...
    LICENSE_PUBLIC_KEY: |                    # the bundle's `publicKey` field (PEM)
      -----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFA...
      -----END PUBLIC KEY-----

When both are set, the wizard's License step opens already verified.

Configuration reference

Every group below maps to a top-level key in the chart's values.yaml, in file order. Defaults shown are the chart defaults; override only what you need.

global — registry, images, storage

Cluster-wide settings every service inherits.

global:
  imageRegistry: scrydonops.azurecr.io
  imagePullSecrets:
    - name: scrydon-registry
  storageClass: managed-csi

namespaces — workload placement

Every service defaults to scrydon-platform. Override per service for multi-namespace isolation; the chart auto-aligns Dapr ACL policies and the secret-reader RBAC.

namespaces:
  infra: scrydon-infra
  platform: scrydon-platform
  agentic: scrydon-agentic
  analytics: scrydon-platform
  cortex: scrydon-platform

ingress — exposure and TLS scheme

Certificate choices for Let's Encrypt, private-only domains, internal ACME, and static corporate certificates are covered in TLS Certificates.

Other ingress controllers

traefik and nginx need no extra work. For AGIC, AWS ALB, GKE GCE, or HAProxy set ingress.className and add the controller's own annotations. In the default subpath mode the front-door Ingress resources share one host, so use routing.annotations; chart-wide settings go in ingress.annotations.

At minimum you need a request-body limit at least as large as the platform's 100 MB upload cap, and WebSocket-friendly read timeouts on the routing.paths.agenticRealtime route:

ingress:
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"

Two controller-specific notes:

• nginx: the Dapr-header strip is emitted as a configuration-snippet, which ingress-nginx ignores unless allow-snippet-annotations: true is set in its ConfigMap (default false since 1.9). Enable it, or set ingress.stripDaprHeaders.mode=external and strip the headers upstream.
• GKE GCE ingress: its default health check targets /, which the SSR apps answer with a redirect chain. Point it at each app's /api/healthz with a BackendConfig, or run ingress-nginx instead.

routing — subpath vs subdomain

Chooses how apps are exposed. Full discussion: Routing Modes.

routing:
  mode: subpath
  host: app.example.com
  paths:
    cortex: /scrydon/cortex      # customize prefixes if needed
    platform: /scrydon/platform

dapr — service mesh and identity

Service-to-service calls use Dapr with mTLS; the chart's ACL policies key on the SPIFFE trust domain.

Bringing your own Dapr requires the chart-tested 1.18.1 version, trust domain scrydon (or match it via dapr.trustDomain), and a running sidecar injector. See Existing Dapr installations.

Database — bundled Postgres or BYO

infra.db controls the bundled Postgres (pgvector). For an external/managed instance, the full recipe — per-provider notes, infra.db.external.* keys, pre-creating databases — is on BYO Database.

# Bundled (default) — just set a strong password:
infra:
  db:
    credentials:
      password: REPLACE-WITH-DB-PASSWORD
# BYO managed Postgres:
infra:
  db:
    enabled: false
    external:
      existingSecrets:
        auth: scrydon-auth-db
        agentic: scrydon-agentic-db
      lakekeeperUrl: "postgres://scrydon:REDACTED@pg.example.com:5432/lakekeeper"
      sslMode: require

StarRocks — Managed Tables (OLAP)

Single-pod allin1-ubuntu. Backs the Tables UI and the agentic schema-inference fallback. Pairs with apiTable.

For multi-AZ production, switch to the starrocks-kubernetes-operator (FE/BE split), set apiTable.starrocks.replicationNum to match its BE count, and point apiTable.starrocks.host at its FE Service.

SeaweedFS — object storage

Single-pod S3-compatible storage for uploads.

Application services

The product apps — auth (api-platform), platform, cortex, analytics, apiOntology, apiTable, agentic (app + realtime). Each block shares a common shape:

Notable app-specific keys:

auth:
  secrets:
    AUTH_SECRET: REPLACE-WITH-AUTH-SECRET   # session signing — openssl rand -hex 32
  auditLog:
    enabled: true                           # SIEM forwarding + retention crons (ADR 2026-04-16)
    chain:
      enabled: false                        # tamper-evident hash chain — opt-in, has signing cost

analytics:
  marimoDocument:
    enabled: true                           # private, compute-free document renderer
  marimoRuntime:
    startupDeadlineMs: 300000               # Connect/Run preparation deadline
  secrets:
    MARIMO_RUNTIME_HMAC_SECRET: ""           # blank → generated and reused across upgrades

apiTable:
  starrocks:
    host: ""                                # blank → bundled FE Service; set for external StarRocks
    user: root
  secrets:
    STARROCKS_PASSWORD: REPLACE-WITH-STARROCKS-PW

agentic:
  realtime:
    ingress:
      annotations:                          # sticky cookie for the WebSocket route
        traefik.ingress.kubernetes.io/service.sticky.cookie: "true"
  passkey:
    rpId: app.example.com                   # MUST match routing.host or passkey registration fails
    origin: https://app.example.com

auth.secrets.SERVICE_ADMIN_TOKEN is deprecated — production uses Dapr mTLS (SPIFFE). Only set it for local dev without sidecars. Where underscore keys are disallowed (Azure Marketplace protected settings), use auth.authSecret instead of auth.secrets.AUTH_SECRET.

executionFabric and runtimePlane

The runtime plane is opt-in until its Kata/KVM substrate and network controls are qualified. It owns fresh Agent exec pods, long-lived generation-fenced Marimo sessions, and fresh single-use notebook jobs. Opening a notebook still uses the compute-free document renderer; Connect, disconnected Run, and jobs refuse when the plane is unavailable. Marimo compute never falls back to a product-service process. The deployment-owned executionFabric policy selects between microvm and managed_process before dispatch. Both tiers ship by default: the generic managed-process actor host renders out of the box (the normal tier), and microvm (the isolated tier) is allowed and preferred, so a cluster that enables the Runtime Plane isolates automatically. An organization admin turns on Require isolated execution under Settings → Platform → Compute to make the microVM a hard floor for that organization — its executions then refuse rather than use the managed-process tier. A bound execution never downgrades after it starts.

The chart refuses to render an executionFabric whose allow-list has no deployed backend (for example allowedTiers: [microvm] with runtimePlane.enabled: false). That combination used to install silently and every execution then failed at runtime with "No permitted … execution tier is currently ready"; it now fails at helm install time with the values path to fix. A strict production posture that wants microVM only sets managedProcess.enabled: false explicitly — see values.production.example.yaml.

The managed tier is one generic Dapr actor-host Deployment and image. Dapr owns placement and horizontal routing; each invocation gets a fresh child process tree and workspace while reusing the same Agent, implementation, and notebook runners as the microVM backend. It shares the actor-host pod kernel and is explicitly weaker than a microVM.

Standard Agents always use AgentCapabilityContract with the fixed agent-capability-contract protocol. There is no integration-tool broker mode to enable during install or upgrade, and no operator value selects another Agent architecture. The chart pins the named protocol into Runtime Plane; an incompatible runner image is refused before an Agent workload is created.

The chart replicates your global.imagePullSecrets from the release namespace into the two runtime namespaces at install/upgrade time, so private registries work without extra steps. (helm template-then-apply pipelines have no cluster to read from — pre-create the pull secrets in both runtime namespaces in that workflow.)

The two deployment choices are microvm and managed_process. Historical Runtime Plane wire fields (require_true_vm, fallback, mediated, and hardened) are not Helm or organization tier controls. Tier-aware adapters emit a fixed microVM-only wire value after the shared resolver selects microvm, solely for rolling compatibility with the Rust plane.

networkPolicies:
  enabled: true

executionFabric:
  allowedTiers: [microvm, managed_process]
  preferredTiers: [microvm, managed_process]
  managedProcess:
    enabled: true

runtimePlane:
  enabled: true
  namespace: scrydon-runtimes
  workloadNamespace: scrydon-runtime-workloads
  persistence:
    size: 1Gi
  runnerImage: registry.example.com/scrydon/bundle-runner@sha256:<digest>
  enforcerImage: registry.example.com/scrydon/egress-enforcer@sha256:<digest>
  marimoRuntimeImage: registry.example.com/scrydon/marimo-runtime@sha256:<digest>
  blockedCidrs:
    - "10.0.0.0/8" # replace/extend with the actual pod + service CIDRs
    - "172.16.0.0/12"
    - "192.168.0.0/16"
  upstreamDns: "10.0.0.10:53"
  isolation:
    microvm:
      enabled: true
      renderRuntimeClass: false # AKS owns kata-vm-isolation

The controller Deployment and both workload identities consume global.imagePullSecrets. Single-use Agent/notebook-job pods use sa-runtime-exec; interactive Marimo pods use sa-runtime-workload. Both set automountServiceAccountToken: false, so untrusted code receives no Kubernetes API token while kubelet can still use the configured registry credential. Do not patch the namespace default ServiceAccount. When the registry requires a pull secret, create the same named Secret in runtimePlane.namespace, runtimePlane.workloadNamespace, and every enabled application namespace before installation, or provide equivalent node-level registry access.

After deployment, check the controller's boot capability report and prove the selected tier separately for Agent exec, Marimo interactive, and notebook-job profiles. Also prove that opening a notebook creates no runtime, Connect runs no cells, and disconnected Run executes the selected cell once. A Ready controller alone does not prove Kata, image pulls, callbacks, DNS, dependency installation, cleanup, or egress enforcement.

eventBackbone — durable platform events (managed Valkey)

Chart v1.3.22+ ships a durable event backbone (committed workflow-editor synchronization, organization event streams) and a model-discovery cache. Both are on by default and share one bundled persistent Valkey instance.

opa — authorization decision point

Every workspace/workflow/ontology authorization decision is evaluated by OPA.

license — validation posture

auth.secrets.LICENSE_PUBLIC_KEY must be set whenever license.enabled: true so api-platform can verify JWT signatures. Scrydon must run on a dedicated cluster because capacity includes all schedulable worker nodes. See Licensing and License capacity reporting.

When networkPolicies.enabled=true, set networkPolicies.kubernetesApiEgress.enabled=true and its cidr to the Kubernetes API Service IP with a /32 mask. This permits only the node-capacity API connection; RBAC still limits the identity to get/list on nodes.

packSources — chart-managed pack distribution

Pod security and disruption budgets

Pod scheduling

Chart-wide nodeSelector, tolerations, and affinity apply to every Deployment, StatefulSet, and migration Job — so pods can land on tainted or dedicated nodes. Per-component overrides are not exposed.

tolerations:
  - { key: workload, operator: Equal, value: scrydon, effect: NoSchedule }
nodeSelector:
  workload: scrydon
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - { key: node-role.kubernetes.io/scrydon, operator: Exists }

Trimming for low-resource installs

Defaults assume a production-shape cluster (≥ 8 vCPU / ≥ 32 GiB across nodes). On eval clusters (4 vCPU / 16 GiB), disable the heaviest optional pieces:

infra:
  starrocks:
    enabled: false     # ~2–8Gi RAM, 20Gi PVC — only Managed Tables + agentic schema-inference affected
apiTable:
  enabled: false
analytics:
  enabled: false       # drops the analytics UI + marimo sidecar (~2Gi)

Common configuration recipes

Customizing routing paths

Mount apps under different prefixes (e.g. everything under /scrydon/...) via routing.paths.* — see the routing table above and Routing Modes.

Rendering without a live cluster (GitOps / offline)

Use this whenever the chart is rendered without a connection to the target cluster — anything that runs helm template under the hood:

• ArgoCD (its default renderer)
• Kustomize's helmCharts: inflator
• helm template … | kubectl apply -f -, the usual offline air-gap flow
• helm install --dry-run, helm diff

Flux's HelmRelease drives a real helm upgrade --install and does not need this. Neither does a direct helm install/helm upgrade, nor zarf package deploy.

Why it matters. Every chart-managed secret resolves live cluster Secret → value you provided → generate a random one. Helm's lookup returns empty with no API connection, so the third branch fires and produces a different value on every render. Applying that rotates 38 secrets on each sync, and some rotations cannot be undone:

What to do. Set global.requireExplicitSecrets: true. Each generate branch becomes a render-time failure naming the exact values path, so a missing entry is loud instead of destructive. Start from values.gitops.example.yaml, which lists the full required set and the kubectl commands to read the current values out of an existing install before you adopt it:

helm template scrydon ./helm/scrydon \
  -f helm/scrydon/values.yaml \
  -f helm/scrydon/values.gitops.example.yaml \
  -n scrydon-platform

Generate each value once, store it in your secret manager, and inject it at render time (ArgoCD valuesFrom, a sops-decrypted overlay, --set-file). Keep the values stable — changing one here changes it in the cluster.

Existing Dapr installations

If the cluster already runs Dapr, set dapr.installControlPlane: false so the chart doesn't try to manage it, and point dapr.controlPlaneNamespace at where Dapr lives:

dapr:
  installControlPlane: false
  controlPlaneNamespace: dapr-system

Your Dapr must satisfy three prerequisites or sign-in works but account creation / cross-service calls fail with PermissionDenied:

kubectl -n <dapr-ns> get deploy dapr-sentry \
  -o jsonpath='{.spec.template.spec.containers[0].image}'   # expect sentry:1.18.1

Advanced ingress: behind a TLS-terminating load balancer

App Gateway / ALB / GCP LB / F5 setups need Traefik-controller tuning (trustedIPs, externalTrafficPolicy: Local, the ingress.tls.enabled public-scheme rule, private ingress, 502 troubleshooting). Full playbook: TLS Offloading.

StarRocks credentials

The bundled StarRocks ships root with no password. If you set a non-empty apiTable.secrets.STARROCKS_PASSWORD, the chart applies it for you — a password-reconciler sidecar inside the starrocks-fe pod reconciles the root password on every boot and then re-verifies it once a minute: it applies the password on a password-less root, no-ops when it already matches, rotates root automatically when you change the value (a checksum annotation restarts the pod; the sidecar re-keys from the previous password it recorded on the StarRocks PVC), and logs loudly — without clobbering anything — if root was changed out-of-band. No manual step is required; leave the value empty for a password-less root.

Two behaviors worth knowing:

• First passworded boot may restart starrocks-fe once. The image's own boot check races the very first password apply and shuts the container down if it loses; the password is already persisted by then, so the next boot is clean. One restart on a fresh install is benign — CrashLoop or repeated restarts are not.
• Rotation order is handled for you. Changing the value and running helm upgrade restarts starrocks-fe (sidecar rotates root) and api-table (its secret checksum changed) — no manual SET PASSWORD.

NEW_PW="<your-starrocks-password>"   # same value as apiTable.secrets.STARROCKS_PASSWORD
# StarRocks runs in the release namespace by default (namespaces.infra → scrydon-platform).
kubectl -n scrydon-platform exec -it deploy/starrocks-fe -- \
  mysql -h127.0.0.1 -P9030 -uroot -e "SET PASSWORD FOR 'root'@'%' = PASSWORD('${NEW_PW}');"
kubectl -n scrydon-platform rollout restart deployment/api-table

If the password never reaches StarRocks (older chart with the hook Job failed or the manual step skipped), api-table stays 1/2 Running — Ready container plus a sidecar, but the app fails its readiness probe (/api/table/health/ready → 503, "starrocks": false). It does not CrashLoop, so the pod looks healthy at a glance. Because a not-Ready pod is removed from its api-table-dapr service endpoints, any service that calls api-table over Dapr (api-ontology, for one) gets ERR_DIRECT_INVOKE: failed to resolve address for api-table-dapr…. See Troubleshooting. (replication_num is auto-clamped to the live BE count, so a single-pod StarRocks no longer fails table provisioning on its own.)

The root password is stored in FE metadata on the StarRocks PVC, so it survives pod restarts, and the reconciler sidecar re-verifies it continuously.

To bring your own StarRocks instead:

infra:
  starrocks:
    enabled: false
apiTable:
  starrocks:
    host: starrocks-fe.starrocks.svc.cluster.local
    user: scrydon
  secrets:
    STARROCKS_PASSWORD: REPLACE-WITH-STARROCKS-PASSWORD

Verify the deployment

kubectl get pods -n scrydon-platform   # all Running, 2/2 with the Dapr sidecar
kubectl get ingress -n scrydon-platform   # each Ingress has an ADDRESS
kubectl get certificates -A             # cert-manager Certificates READY=True

License claims (tier, entitlements, days-to-expiry) appear under Platform Settings → License after /setup. Sign in at https://app.example.com/ and switch apps via the product switcher without re-authenticating.

Troubleshooting

Day-2 operations

• Renew the license — paste the refreshed bundle under Settings → License → Update license; no restart. Licensing.
• Backup & restore — bundled Postgres CronJob (infra.db.backup) or your managed provider. Backup & Restore.
• Upgrades — Upgrades.
• Observability — Observability.