Configuration

Every deployment has configuration that controls the behavior of the Iggy server and any active connectors. Configuration is versioned - you can create multiple versions, activate a specific version, and roll back to a previous one.

All configuration data is encrypted at rest alongside all other sensitive data on the platform.

Every saved config also records the runtime version it was validated against (Iggy, Warden, or Connectors). After an upgrade, the runtime_version on existing configs tells you whether a row was written against an older schema and may need review before reuse.

Configuration Kinds

Kind	What It Configures
Iggy	Iggy server settings - topic sizes, retention policies, system limits, transport settings
Connectors	Global connectors runtime settings
Individual connector	Per-connector instance settings - stream/topic mappings, plugin configuration, batch settings

How It Works

Each deployment starts with a default configuration based on best-practice defaults
You can create a new named configuration with custom values
Each named config maintains a version history - every save creates a new version
Activate a specific version to apply it to the deployment
Trigger a reconfigure task to apply the change (see Apply Configuration Changes)
The Warden agent pulls the task and applies the active configuration
If something goes wrong, activate a previous version and reconfigure to roll back

Configuration Schemas

Every configuration kind has a schema that defines the available settings, their types, defaults, and validation rules. You can retrieve the schema to see what's configurable before creating a config.

From the Console

Navigate to your deployment and open the Configuration tab
Select the configuration kind (Iggy, Connectors, or a specific connector instance)
The schema is displayed as a form with current values, defaults, and descriptions
Modify values and click Save to create a new version
Click Activate to apply the version to the deployment

Managing Configurations

From the Configuration tab you can:

View all named configs for each kind with their version history
See the primary (active) configuration
Compare versions side-by-side
Activate any version to make it live
Delete configurations you no longer need

Required permission: deployment:config:manage (create, activate, delete) or deployment:config:read (view)

API Reference

Get Configuration Schema

Returns the available settings, types, and defaults for a configuration kind. The response is organized into sections, each with a human-readable name, description, and list of schema entries.

curl {supervisor_url}/deployments/{deployment_id}/configs/iggy/schema \
  -H "ld-api-key: YOUR_API_KEY"

{
  "segment": {
    "name": "Segment",
    "description": "Log segment size and rotation settings.",
    "schema": [
      {
        "key": "IGGY_SEGMENT_SIZE",
        "name": "Segment Size",
        "description": "Maximum size of a single log segment",
        "default_value": "1 GB",
        "kind": "size",
        "versions": "all",
        "editable": true,
        "secret": false,
        "requirements": [],
        "rules": []
      }
    ]
  },
  "stream": {
    "name": "Stream",
    "description": "Stream creation defaults and limits.",
    "schema": [...]
  },
  "topic": {
    "name": "Topic",
    "description": "Topic creation defaults and limits.",
    "schema": [...]
  }
}

Each section key is a snake_case identifier (e.g. segment, stream, topic, tcp, http, quic, compression, encryption, data_maintenance). Schema entries include:

Field	Description
`key`	Configuration key (e.g. `IGGY_SEGMENT_SIZE`)
`name`	Human-readable name
`description`	What the setting controls
`default_value`	Default value
`kind`	Field type - `string`, `bool`, `int`, `float`, `size`, `duration`, `path`, `url`, etc.
`editable`	Whether the value can be changed
`secret`	Whether the value is masked in responses
`requirements`	Dependencies on other config values
`rules`	Validation rules (min, max, etc.)

Connector config schemas use the same format with additional sections: sink, source, and plugin_config.

Config responses include a runtime_version field (SemVer) indicating the runtime release the config was written against. After an Iggy/Warden/Connectors upgrade, compare this to the currently installed version to spot configs that may need re-validation.

Create a Configuration

curl -X POST {supervisor_url}/deployments/{deployment_id}/configs/iggy \
  -H "ld-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "high-throughput",
    "values": {
      "IGGY_SYSTEM_TOPIC_MAX_SIZE": "2 GB"
    },
    "activate": false
  }'

Returns 201 Created with ld-config header containing the new config ID.

Set "activate": true to immediately apply the config after creation.

Get Active Configuration

curl {supervisor_url}/deployments/{deployment_id}/configs/iggy/primary \
  -H "ld-api-key: YOUR_API_KEY"

List All Configurations

curl {supervisor_url}/deployments/{deployment_id}/configs/iggy \
  -H "ld-api-key: YOUR_API_KEY"

Get a Specific Configuration

curl {supervisor_url}/deployments/{deployment_id}/configs/iggy/{config_id} \
  -H "ld-api-key: YOUR_API_KEY"

Get Version History

curl {supervisor_url}/deployments/{deployment_id}/configs/iggy/{config_name}/versions \
  -H "ld-api-key: YOUR_API_KEY"

Get a Specific Version

curl {supervisor_url}/deployments/{deployment_id}/configs/iggy/{config_name}/versions/{version} \
  -H "ld-api-key: YOUR_API_KEY"

Activate a Version

curl -X PUT {supervisor_url}/deployments/{deployment_id}/configs/iggy/{config_name}/activate/{version} \
  -H "ld-api-key: YOUR_API_KEY"

Returns 204 No Content.

Delete a Configuration

curl -X DELETE {supervisor_url}/deployments/{deployment_id}/configs/iggy/{config_id} \
  -H "ld-api-key: YOUR_API_KEY"

Returns 204 No Content.

Apply Configuration Changes

After activating a new configuration version, trigger a reconfigure task to apply it to the deployment:

curl -X POST {supervisor_url}/deployments/{deployment_id}/tasks \
  -H "ld-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "iggy:reconfigure"
  }'

The Warden agent on each node pulls the task and applies the active configuration automatically. Use connectors:reconfigure to apply connector configuration changes instead.

Required permission: deployment:task:manage

List Tasks

curl {supervisor_url}/deployments/{deployment_id}/tasks \
  -H "ld-api-key: YOUR_API_KEY"

Returns all tasks for the deployment, including their status and type. Use this to monitor the progress of reconfigure, upgrade, and other operational tasks.