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_USERNAMEandIGGY_ROOT_PASSWORDbefore first boot. The server no longer generates a root password. Use--with-default-root-credentialsonly for development. - Remove
consumer_group.session_timeout. Session expiry derives fromheartbeat.intervalwith a factor of 1.2.consumer_group.heartbeat_intervalcontrols membership heartbeat pacing. - Replace
user_idwithusernameinhttp.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_peeridentical 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.
