If Apache Iggy is useful to you, give it a star on GitHubStar apache/iggy
Skip to Content
Apache Iggy
Server
These are the docs for Apache Iggy 0.10, kept for reference and no longer updated. Read the current docs.

Upgrading from 0.9 to 0.10

Prepare a fresh data directory, matching clients and updated configuration for Apache Iggy 0.10.0.

Apache Iggy 0.10.0 changes the wire protocol, data directory format and public SDK APIs. Upgrade the server and clients together.

Preserve data before the upgrade

There is no migration from a 0.9.x data directory. Keep a backup and export messages that you need with the old server and compatible clients. Start 0.10.0 with a separate, empty data directory. Import the retained data through a compatible client. Do not point the new server at the old directory.

Do not use a rolling upgrade between server versions. Every cluster node must run the same server version. Keep the old deployment and its data available until you finish the cutover checks.

Upgrade clients and tools

Server 0.10.0 uses protocol 0.12.0. The server rejects incompatible binary clients at login. Use the versions in Server compatibility. The 0.9 documentation remains available for the old deployment.

Review API changes before recompiling applications. Resource creation uses typed options. Updates change only the fields supplied through set/reset patches. Stream and topic purge, flush unsaved buffer, and the old UpdateStream, UpdateTopic and UpdateUser wire commands are removed. The SDK update methods use UpdateResource internally.

Rust stream builders take stream and topic names, without caller-assigned IDs. Python requires Python 3.11 or later. The SDK guides describe the release APIs and examples.

Review server configuration

Compare your configuration with the 0.10 reference. Do not copy obsolete keys into the new deployment.

  • Set IGGY_ROOT_USERNAME and IGGY_ROOT_PASSWORD before first boot. The server no longer generates a root password. Use --with-default-root-credentials only for development.
  • Remove consumer_group.session_timeout. Session expiry derives from heartbeat.interval with a factor of 1.2. consumer_group.heartbeat_interval controls membership heartbeat pacing.
  • Replace user_id with username in http.jwt.trusted_issuers. The mapped account must exist and cannot be root. HTTP clients and the Web UI must log in again because old self-issued access and refresh tokens are rejected.
  • Supply a valid logging.level. An invalid filter stops startup. Log files rotate by size, with retention and total-size cleanup.
  • Keep cluster.coordinator.replica_connections_per_peer identical on all nodes. Cluster membership is limited to 32 nodes.
  • Keep node clocks synchronized. Authenticated HTTP forwarding uses short-lived proofs.

New topics inherit cluster.default_replication_factor, which defaults to all. Select a different factor at topic creation with replication_factor. Existing topics retain their stored value. See Multi-leader partitions.

Review consumer checkpoints

A checkpoint records how far a consumer processed a partition. The current poll API defaults to manual commits. Rust high-level consumers also default to manual commits, and the stream builder starts with PollingStrategy::next().

Store offsets after processing, or select an explicit automatic commit policy. Without stored offsets, a restarted consumer can read retained messages again. Committing on read can advance the offset before application processing. See Deferred polling.

Connector sinks use deferred polling. Replace poll_interval with max_wait and min_count. The runtime rejects a sink configuration that still sets poll_interval.

Review encryption

Encryption is selected when a stream is created. Each encrypted stream has its own data key. Enabling server encryption does not encrypt an existing unencrypted stream. Keep all keys required to read retained streams and backups. See Stream options for key creation and rotation.

Check the cutover

Run producers and consumers against the new deployment before moving application traffic. Test resource creation, permissions, message payloads and headers, checkpoints, and reconnects. For a cluster, also test requests to different partition primaries and node failure. An accepted write and a processed message are different events. Select the required durability policies and commit behavior explicitly.

On this page