Configuration

The Kastoria Health images that read or write stored data — kastoria-health, kastoria-studyprocessor, kastoria-eventnotification, kastoria-smart-launch-api and kastoria-consoleapi — share one configuration document. It tells a container where Kastoria Core's storage lives, how to authenticate to it, and, for kastoria-eventnotification, which queue to publish Notification Events to.

Supplying the configuration

The document is JSON, supplied through one of two environment variables:

Variable	Contents
`KASTORIA_CONFIG_JSON`	The document itself, as an inline JSON string.
`KASTORIA_CONFIG_FILE`	A path, inside the container, to a file holding the document.

At least one must be set, or the container fails at startup. If both are set, KASTORIA_CONFIG_JSON takes precedence and KASTORIA_CONFIG_FILE is not read.

Kastoria Health authenticates to Azure Storage with user-assigned managed identities, so the document names storage accounts and identity client IDs only, and carries no credentials. When deploying with the compute module, the document is rendered from app_config and delivered as KASTORIA_CONFIG_JSON through an inline container app secret on every app and job. It is not stored in Key Vault, so its full contents are also held in OpenTofu state.

Sample configuration

An Azure deployment using a user-assigned managed identity, with the block store sharded across three storage accounts and a queue for Notification Events:

{
  "organization": "Example Org",
  "name": "sample",
  "purpose": "production",
  "uris": [
    { "type": "public", "uri": "https://sample.example.org" }
  ],
  "storageTiers": [
    {
      "name": "hot",
      "blockStore": [
        {
          "type": "azure-hybrid",
          "configuration": {
            "shards": [
              {
                "accountName": "sasampleabcdsb01",
                "containerName": "hot-blocks-01",
                "tableName": "hotblocks01",
                "managedIdentityClientId": "00000000-0000-0000-0000-000000000001"
              },
              {
                "accountName": "sasampleabcdsb02",
                "containerName": "hot-blocks-02",
                "tableName": "hotblocks02",
                "managedIdentityClientId": "00000000-0000-0000-0000-000000000001"
              },
              {
                "accountName": "sasampleabcdsb03",
                "containerName": "hot-blocks-03",
                "tableName": "hotblocks03",
                "managedIdentityClientId": "00000000-0000-0000-0000-000000000001"
              }
            ]
          }
        }
      ],
      "namedRoot": [
        {
          "type": "azure-hybrid",
          "configuration": {
            "accountName": "sasampleabcdsn01",
            "containerName": "hot-nodes-01",
            "tableName": "hotnodes01",
            "managedIdentityClientId": "00000000-0000-0000-0000-000000000001"
          }
        }
      ]
    }
  ],
  "queueWriter": {
    "type": "azure-storage-queue",
    "configuration": {
      "accountName": "saqsampleabcd",
      "managedIdentityClientId": "00000000-0000-0000-0000-000000000002",
      "queueName": "kastoria-events",
      "messageEncoding": "text"
    }
  }
}

Configuration parameters

Top level

Parameter	Type	Required	Default	Description
`organization`	string	Yes	—	The organization that owns the deployment.
`name`	string	Yes	—	The deployment's name.
`purpose`	string	Yes	—	What the deployment is for, e.g. `production` or `development`.
`uris`	array	No	`[]`	Informational list of URIs, each with a `type` and a `uri`. Not currently read by Kastoria Health, but validated at startup: each entry needs `type` and `uri`. The compute module fills it with one `public` entry per container app, using the app's Container Apps URL.
`uris[].type`	string	Yes	—	The kind of URI, e.g. `public`.
`uris[].uri`	string	Yes	—	The URI.
`storageTiers`	array	Yes	—	The storage tiers. At least one is required.
`queueWriter`	object	No	—	The queue Notification Events are published to. Read only by `kastoria-eventnotification`, which fails without it; every other image ignores it.

Any other top-level key is accepted and ignored.

When deploying with the compute module, the document is rendered from the module's app_config input. The module renames one field and adds two keys that Kastoria Health ignores:

Document key	Source in the compute module
`organization`	`app_config.organization`
`name`	`app_config.environment_name`
`purpose`	`app_config.purpose`
`uris`	Generated: one `public` entry per container app
`storageTiers`	`app_config.storage_tiers`, a JSON-encoded string
`queueWriter`	`app_config.queue_writer`, a JSON-encoded string; omitted when null
`systemStorage`	`app_config.system_storage`, a JSON-encoded string. A required module input, but ignored by Kastoria Health; `jsonencode([])` is sufficient
`config_version`	Added by the module as `1.0.0`; ignored by Kastoria Health

Storage tiers

Parameter	Type	Required	Default	Description
`storageTiers[].name`	string	Yes	—	The tier's name, e.g. `hot`.
`storageTiers[].blockStore`	array	Yes	—	Where content blocks are stored. Each entry is a backend: `type` plus `configuration`.
`storageTiers[].namedRoot`	array	Yes	—	Where Named Roots, the Changelog and Ranged Indexes are stored. Each entry is a backend: `type` plus `configuration`.
`…[].type`	string	Yes	—	Must be `azure-hybrid`.
`…[].configuration`	object	Yes	—	The backend's settings; see `azure-hybrid` configuration.

Kastoria Health stores data in the first tier, using its first blockStore and first namedRoot entry. Any further tiers or entries are still validated and connected to at startup, so they must be reachable, but no data is currently written to them — they are planned for future use.

`azure-hybrid` configuration

Values up to cutOff bytes are stored in an Azure Table; larger values are stored as blobs in the container, with a pointer in the table. A backend is a single table and container, written flat in configuration, or — on the block store only — several, listed in shards.

Parameter	Type	Required	Default	Description
`shards`	array	No	—	Block store only. Spreads blocks across several table-and-container pairs, typically in separate storage accounts, by hash. Each entry takes `accountName`, `managedIdentityClientId`, `containerName`, `tableName` and `cutOff`, as below; when `shards` is set, those fields are not read from the backend level. A one-entry array behaves as the flat form. Not accepted on the named root.
`accountName`	string	Yes	—	The storage account.
`managedIdentityClientId`	string	Yes	—	Client ID of the user-assigned managed identity to authenticate to the storage account as. The identity must be attached to the container.
`containerName`	string	Yes	—	The blob container.
`tableName`	string	Yes	—	The table.
`partitionKeyDepth`	integer	No	`1`	Block store only: how many leading hash segments of a block's key form the table partition key. Must be at least `1`, and is set on the backend, not per shard. Leave unset unless advised otherwise.
`cutOff`	integer	No	`32768`	The largest value, in bytes, stored inline in the table (`1`–`65536`). Must be at least `1024` on the named root.

Queue writer

Parameter	Type	Required	Default	Description
`queueWriter.type`	string	Yes	—	Must be `azure-storage-queue`.
`queueWriter.configuration`	object	Yes	—	The writer's settings, below. Unlike the storage backends, an unrecognized setting is refused.

queueWriter.configuration:

Parameter	Type	Required	Default	Description
`accountName`	string	Yes	—	The storage account holding the queue.
`managedIdentityClientId`	string	Yes	—	Client ID of the user-assigned managed identity to publish as. The identity must be attached to the container. With the queue module, the publisher identity's client ID.
`queueName`	string	Yes	—	The queue: 3–63 lowercase letters, digits and hyphens, starting and ending with a letter or digit, with no two hyphens in a row.
`messageEncoding`	string	Yes	—	`text` sends each event's JSON as-is; `base64` sends it Base64-encoded. Choose the encoding your reader expects.
`createQueueIfMissing`	boolean	No	`false`	Creates the queue if it does not exist. When `false`, a missing queue fails the publish.