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.

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.

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.