Configuration

Configuration controls the Iggy server and active connectors in a deployment. Each saved change creates a version. You can activate a version or return to a compatible earlier version.

The platform encrypts configuration data at rest. Each saved configuration records the runtime release used to validate it in runtime_version. After an upgrade, use this field to identify configurations that need review before reuse.

Configuration Kinds

Kind	What It Configures
Iggy	Server limits, transport settings, runtime maintenance, and telemetry
Connectors	Global connectors runtime settings
Individual connector	Per-connector instance settings - stream/topic mappings, plugin configuration, batch settings

How It Works

A deployment starts with configuration for its runtime and topology, the arrangement of its nodes. To change it:

Save new values under the existing configuration kind name. For a connector instance, use its instance key as the name.
Activate the version that you want to use.
Create a reconfigure task, as described in Apply Configuration Changes.
Wait for Warden to retrieve the task and apply the active version.
If the change fails, activate a compatible earlier version and reconfigure the deployment.

Topic retention, segment size, and durability belong to topic configuration. See Server & Durability for their relationship to server configuration. Warden, plane, and shared connector-runtime configuration require administrative access.

Configuration Schemas

A schema defines the available fields, types, defaults, and rules. Retrieve the schema before you create a configuration. It shows which values you can change.

From the Console

Open your deployment's Configuration tab.
Select Iggy, Connectors, or a connector instance.
Read the form's current values, defaults, and descriptions.
Change the values that you need.
Click Save to create a version.
Click Activate to select that version for the deployment.

Managing Configurations

The Configuration tab provides these actions:

Read named configurations and their version history.
Find the primary configuration, the active version.
Compare two versions side by side.
Activate a saved version.
Delete configurations that you no longer need.

Use deployment:config:manage to create, activate, or delete configuration. Use deployment:config:read to read it.

API Reference

Get Configuration Schema

This endpoint returns the fields, types, and defaults for a configuration kind. It groups entries into sections with names and descriptions.

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

An entry from the TCP section looks like this:

{
  "tcp": {
    "name": "TCP",
    "description": "TCP listener configuration.",
    "schema": [
      {
        "key": "IGGY_TCP_ENABLED",
        "name": "TCP server enabled",
        "description": "Determines if the TCP server is active.",
        "default_value": true,
        "kind": "bool",
        "editable": true,
        "secret": false,
        "requirements": [],
        "rules": []
      }
    ]
  }
}

Section keys use snake_case. Examples include tcp, http, quic, websocket, partition, sharding, metadata, encryption, and data_maintenance.

Field	Description
`key`	Configuration key (e.g. `IGGY_TCP_ENABLED`)
`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 schemas also include sink, source, and plugin_config sections. Configuration responses include runtime_version, a SemVer release number. After an Iggy, Warden, or Connectors upgrade, compare it with the installed release before you reuse the configuration.

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": "iggy",
    "values": {
      "IGGY_DATA_MAINTENANCE_MESSAGES_INTERVAL": "1m"
    },
    "activate": false
  }'

A successful request returns 201 Created. The ld-config header contains the new configuration ID. Set "activate": true to activate it at 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"

A successful request 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"

A successful request returns 204 No Content.

Apply Configuration Changes

After you activate a version, create a reconfigure task for 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"
  }'

Warden on each node retrieves the task and applies the active configuration. For connectors, use connectors:reconfigure. These tasks require deployment:task:manage.

List Tasks

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

The response includes task types and statuses for the deployment. Use it to follow reconfiguration, upgrades, and other operations.