Settings key reference
This page is the catalogue of platform configuration keys. Platform configuration is a deployment-wide key-value store, so a value can change without rebuilding an image and can be restored after disaster recovery.
You read and change these values on the Configuration page. Its Simple mode covers the common settings with guided controls, and its Advanced mode shows the full key catalogue this page documents. Every key is a dot-separated name, for example system.core.auth_mode. The first segment is the prefix and says which part of the platform reads the key.
Platform configuration is not project configuration. Per-project settings such as the ingestion queue live on the project’s own configuration page under Projects. It is also not the Features table. A feature is a capability bundle, switched on and off there.
Some values take effect only after the affected service restarts. If a change does not show up, restart the service that reads the key from Service Restarts. For which values cannot be edited from the browser, see Configuration.
Prefix guide
| Prefix | Audience | Purpose |
|---|---|---|
system.* | Operator / platform | Core API auth, retention, statics rotation, project worker image |
runner_config.* | Operator | Default object store and S3 gzip behaviour for runners |
frontend.* | Operator | Control Centre login integration |
report.* | Operator | Report definitions for the dashboard Reports page and the v2 Reports API |
monitoring.Grafana.* | Operator | Embedded Grafana URLs in Control Centre |
scheduler.* | Operator | Scheduler poll intervals and runner pod limits (optional) |
qa.* | Operator (non-prod) | Cypress QA user reset |
privacy.* | Operator | Data privacy policy shown on first login |
public_api_v1.* | Integrator (legacy) | v1 cloud settings bundle (internal catalog) |
The public_api_v1.* bundle (connection strings, mail, cloud database settings and similar) is documented in an engineering catalog inside the monorepo, not on this site. HEAT Auth loads that prefix at startup. External integrators may read public_api_v1.* and frontend.facade only.
Key reference
The tables below list the operator and platform keys.
system.*
| Key | Purpose | Affects | Limitations | Default |
|---|---|---|---|---|
system.core.auth_mode | Core API authentication mode: Local, ClusterOnly, or Strict. | Every Core API request via CoreAuthMiddleware. | ClusterOnly requires ingress to set X-HEAT-Request-Source: external for outside traffic. | Local (seeded at setup) |
system.core.internal_request_privilege | Privilege for in-cluster requests without the external header. | Internal service access to platform-only resources. | Use System only for trusted services (for example v2 API aggregating statics). Default Privileged. | Privileged |
system.retention.tick_minutes | Minutes between session output retention archive sweeps. | Session retention background job. | Integer 1-1440; invalid values fall back to ~5 minutes. | ~5 |
system.statics.global_singleton_session_rotate_hour_utc | UTC hour (0-23) to rotate global singleton static backing sessions. | Statics (for example Resource Monitor). | Unset: no platform-wide rotation hour. | (none) |
system.ProjectWorkerContainerImage | Container image for project-worker (JetStream ingest). | Scheduler provisioning of per-project workers. | Must exist in cluster registry; privileged key. | heatglobal.azurecr.io/heat-project-worker:latest |
runner_config.*
Read as nested JSON from GET /api/config/runner_config (for example default_store under the runner_config object).
| Key | Purpose | Affects | Limitations | Default |
|---|---|---|---|---|
runner_config.default_store | Default data source name when nodes omit dataSourceName. | Python runners, system-utils dimension nodes, uploads. | Must match a registered data source (usually HEAT Managed Object Store). | HEAT Managed Object Store |
runner_config.gzip_node_outputs | When literal true, eligible JSON S3 node outputs may be stored gzip-compressed. | system-utils S3 writers, node output download path. | Applies to eligible JSON S3 outputs (not heatx range blobs). | true |
frontend.*
| Key | Purpose | Affects | Limitations | Default |
|---|---|---|---|---|
frontend.facade | When true, Control Centre login uses HEAT Auth. | Control Centre /login flow. | Required for HEAT Auth login; setup forces true. | true |
report.*
Report definitions. The dashboard Reports page, the v2 Reports API and the legacy v1 facade all read these keys. The Reports API guide covers column and filter authoring, and it can create and update these keys for you.
| Key | Purpose | Affects | Limitations | Default |
|---|---|---|---|---|
report.Settings.Reports | JSON array of available report definitions. | Reports page, v2 Reports API and legacy /v1/Report routing. | Each entry needs matching report.Configurations.{key}.* keys. | Seeded session-list entry |
report.Settings.Default | Default report key when none is requested. | Report export when no report key is requested. | Must exist in report.Settings.Reports. | session-list |
report.Configurations.sessionList.Columns.Date | Column spec for session date. | Session list report | Edit through the Reports API or as JSON | JSON column |
report.Configurations.sessionList.Columns.Account | Column spec for account name. | Session list report | Edit through the Reports API or as JSON | JSON column |
report.Configurations.sessionList.Columns.DimensionName | Column spec for dimension name. | Session list report | Edit through the Reports API or as JSON | JSON column |
report.Configurations.sessionList.FileName | Export filename prefix. | Session list CSV and XLSX export | None | Session_List |
report.Configurations.{configurationKey}.* | Pattern: per-report blocks (columns, FileName, and similar). | Custom reports | Add keys for each configurationKey in report.Settings.Reports | (operator-defined) |
monitoring.Grafana.*
Operator-added keys for on-prem Grafana. Example dashboard names: CoreApi, HeatAuth, HeatScheduler, LegacyRunner, V1ExternalApi.
| Key | Purpose | Affects | Limitations |
|---|---|---|---|
monitoring.Grafana.BaseUrl | Grafana base URL for embeds. | Control Centre monitoring pages | Must match live Grafana ingress |
monitoring.Grafana.Dashboards.{name} | Pattern: public dashboard path per service. | Embedded panels in Control Centre | One key per dashboard |
scheduler.*
Optional keys read by the scheduler as one nested group. When they are missing, the scheduler uses built-in defaults. poll_interval_ms and config_update_interval_ms are typically 10000. Runner deployments default to minimum_pods 2 and maximum_pods 4 per runner type unless overridden below.
| Key | Purpose | Affects | Limitations |
|---|---|---|---|
scheduler.poll_interval_ms | Task polling interval (ms). | Runner task claiming | String numeric value |
scheduler.config_update_interval_ms | Config reload interval (ms). | Scheduler control loop | String numeric value |
scheduler.limits.{runnerName}.* | Pattern: min/max pods per runner type. | Kubernetes runner deployments | Must match SchedulerConfig shape. Precedence per value: this key, then the runner manifest’s optional deployment block (minimumPods, maximumPods, cpuRequest, memoryRequest), then the defaults of 2 min and 4 max pods with requests at half the limits. |
system.ProjectWorkerContainerImage is exposed to the scheduler via GET /api/config/system as ProjectWorkerContainerImage (not under the scheduler. prefix).
runner_sdk.*
Optional keys for runners built with the HEAT Runner SDK. Every key has a default, and a missing or non-positive value keeps it. The v2 API picks up changes within a minute. HEAT Auth reads the two token keys when it starts.
| Key | Purpose | Default | Limitations |
|---|---|---|---|
runner_sdk.max_output_bytes | Largest output a runner may write. | 4 GiB | Decoded size for compressed outputs. |
runner_sdk.single_upload_max_bytes | Largest output sent in one request. Larger outputs are uploaded in parts. | 16 MiB | |
runner_sdk.upload_part_bytes | Size of each part of a large upload. | 32 MiB | Keep it below the ingress request body limit. |
runner_sdk.claim_max_wait_seconds | Longest time a runner waits for a task in one request. | 20 | |
runner_sdk.heartbeat_interval_seconds | How often runners report progress. | 30 | Tasks with no progress for 20 minutes are reclaimed. |
runner_sdk.list_page_max_size | Largest page of inputs returned to a runner. | 500 | |
runner_sdk.incremental.max_inputs_per_task | Most inputs one incremental task may consume. A follow-up task processes the rest. | 512 | Runners may ask for fewer. |
runner_sdk.incremental.max_bytes_per_task | Most input bytes one incremental task may consume. | 2 GiB | The first input is always delivered, even when it alone is larger. |
runner_sdk.token_ttl_hours | Lifetime of the runner tokens the scheduler issues. | 24 | At most 168. The scheduler issues a new token when a third of the lifetime remains. |
runner_sdk.developer_token_max_days | Longest lifetime of a runner token issued to a developer. | 30 |
qa.*
Non-production Cypress environments only. See monorepo tests/qa-environments.md.
| Key | Purpose | Affects | Limitations |
|---|---|---|---|
qa.enabled | Enables QA user reset endpoint. | HEAT Auth QaController | Never true in production |
qa.lastResetUtc | Last successful reset timestamp (ISO). | Written by reset endpoint | Runtime-written |
qa.users.admin | Current QA admin external user GUID. | Cypress admin login | Runtime-written |
qa.users.instructor | Current QA instructor GUID. | Cypress | Runtime-written |
qa.users.trainee | Current QA trainee GUID. | Cypress | Runtime-written |
qa.users.developer | Current QA developer GUID. | Cypress | Runtime-written |
privacy.*
The policy every user must accept on first login (the dashboard’s /privacy-policy page) is platform configuration, so an administrator edits it on the Settings page under the privacy prefix. No rebuild or deployment change is involved; the next request for the policy returns the new text.
| Key | Purpose |
|---|---|
privacy.policy_content | The policy text. Rendered as HTML by the dashboard, so plain paragraphs or simple HTML both work. |
privacy.policy_version | ISO 8601 date-time returned as the policy’s version. Update it when the text changes. |
Both keys are created on the first start of HEAT Auth from its built-in default, which is a template with placeholders for the organisation name and address. Replace it before an environment ships. A blank policy text falls back to the built-in default. Acceptance is recorded per user and is not tied to the version, so publishing a new policy does not ask existing users to accept it again.
Feature toggles (legacy bundle)
The Next dashboard feature flag API reads FeatureToggleSettings.FeatureToggles from the nested public_api_v1 configuration (comma-separated names). That key lives in the public_api_v1.* internal catalog, not in the operator table above.
Ingestion queue (JetStream)
Projects with Enable ingestion queue on (the default for new projects) buffer uploads per project before storage and batch them into heatx bundles. Three places size that path. All three matter when a site replays a large capture in one burst.
| Setting | Where | Default | Notes |
|---|---|---|---|
HEAT_INGEST_JS_MAX_BYTES | heat-v2-api environment | 8 GiB | Cap on queued bytes in the HEAT_INGEST stream. The stream refuses new publishes when full and the v2 API then writes that upload straight to the object store, so a burst larger than the cap is slower but never dropped. Keep it well under the NATS PVC size. |
HEAT_INGEST_JS_MAX_AGE_SECONDS | heat-v2-api environment | 7 days | Queued blobs a project worker has not acknowledged by this age are discarded without any signal, so keep it long. A stalled worker shows up as a Control Centre advisory (“Ingestion backlog not being written”) while the messages are still in the queue; once they age out the upload is gone although the client received a 202. |
HEAT_INGEST_STALL_FALLBACK_SECONDS | heat-v2-api environment | 600 | Before queueing an upload the v2 API checks the project’s JetStream consumer. If a backlog exists and the project worker has not acknowledged anything for this long (or nothing is pulling at all for a minute), the API logs an error and writes uploads directly to the object store until the worker recovers. 0 disables the stall check (the no-worker check stays on). |
maxWorkerMemory, maxFlushThresholdMb, maxBufferAgeSeconds | Project configuration page (Projects) | 512Mi, 16, 30 | Per-project worker sizing. maxWorkerMemory is the worker pod’s memory request; the scheduler sets the limit to the request plus 256Mi and re-applies the worker Deployment within a minute of a change. Minimum 512Mi (the API refuses less, and an upgrade raises existing rows below it). 1Gi is a comfortable starting point on a site that replays exports. |
| NATS container memory | heat-nats-queue StatefulSet | 2Gi | The worker bounds its in-flight deliveries (16 messages, 64 MB per pull), which is what keeps NATS memory flat. |
A stalled queue shows up as the input node’s output count creeping up in small steps and downstream nodes re-running per batch. Judge results only after the count has stopped growing.
Related
- Configuration: Features
- Projects
- Session retention
- Statics
- Grafana on-prem
- Runners and Core Utils
- HEAT v2 API (the configuration routes, for integrators)